diff options
Diffstat (limited to 'usr/src/man')
96 files changed, 10352 insertions, 376 deletions
diff --git a/usr/src/man/Makefile b/usr/src/man/Makefile index 74d27fb221..f4fc11d776 100644 --- a/usr/src/man/Makefile +++ b/usr/src/man/Makefile @@ -84,6 +84,7 @@ SUBDIRS= man1 \ man3tsol \ man3uuid \ man3volmgt \ + man3vnd \ man3xcurses \ man3xnet \ man4 \ diff --git a/usr/src/man/man1/Makefile b/usr/src/man/man1/Makefile index 3549e2b05e..3307298389 100644 --- a/usr/src/man/man1/Makefile +++ b/usr/src/man/man1/Makefile @@ -73,6 +73,7 @@ MANFILES= acctcom.1 \ clear.1 \ cmp.1 \ col.1 \ + column.1 \ comm.1 \ command.1 \ compress.1 \ @@ -85,6 +86,8 @@ MANFILES= acctcom.1 \ csh.1 \ csplit.1 \ ctags.1 \ + ctfdiff.1 \ + ctfdump.1 \ ctrun.1 \ ctstat.1 \ ctwatch.1 \ @@ -218,6 +221,7 @@ MANFILES= acctcom.1 \ m4.1 \ mac.1 \ mach.1 \ + machid.1 \ madv.so.1.1 \ mail.1 \ mailcompat.1 \ @@ -351,13 +355,6 @@ MANFILES= acctcom.1 \ spell.1 \ split.1 \ srchtxt.1 \ - ssh.1 \ - ssh-add.1 \ - ssh-agent.1 \ - ssh-http-proxy-connect.1 \ - ssh-keygen.1 \ - ssh-keyscan.1 \ - ssh-socks5-proxy-connect.1 \ strchg.1 \ strings.1 \ strip.1 \ @@ -474,6 +471,9 @@ MANLINKS= batch.1 \ helpuid.1 \ helpyorn.1 \ hist.1 \ + i286.1 \ + i386.1 \ + i486.1 \ if.1 \ intro.1 \ jsh.1 \ @@ -518,9 +518,11 @@ MANLINKS= batch.1 \ sh.1 \ snca.1 \ source.1 \ + sparc.1 \ spellin.1 \ stop.1 \ strconf.1 \ + sun.1 \ switch.1 \ ulimit.1 \ unalias.1 \ @@ -650,6 +652,12 @@ unlimit.1 := LINKSRC = limit.1 dumpkeys.1 := LINKSRC = loadkeys.1 +i286.1 := LINKSRC = machid.1 +i386.1 := LINKSRC = machid.1 +i486.1 := LINKSRC = machid.1 +sparc.1 := LINKSRC = machid.1 +sun.1 := LINKSRC = machid.1 + rmail.1 := LINKSRC = mail.1 page.1 := LINKSRC = more.1 diff --git a/usr/src/man/man1/column.1 b/usr/src/man/man1/column.1 new file mode 100644 index 0000000000..a8c23310ba --- /dev/null +++ b/usr/src/man/man1/column.1 @@ -0,0 +1,129 @@ +.\" 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. +.\" +.\" @(#)column.1 8.1 (Berkeley) 6/6/93 +.\" $FreeBSD$ +.\" +.\" Portions Copyright (c) 2013 Joyent, Inc. All rights reserved. +.\" +.TH COLUMN 1 "Jan 10, 2013" +.SH NAME +column \- columnate lists +.SH SYNOPSIS +.LP +.nf +\fBcolumn\fR [\fB-tx\fR] [\fB-c\fR \fIcolumns\fR] [\fB-s\fR \fIsep\fR] [\fIfile\fR ... ] +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcolumn\fR +utility formats its input into multiple columns. +Rows are filled before columns. +Input is taken from +\fIfile\fR +operands, or, by default, from the standard input. +Empty lines are ignored. +.SH OPTIONS +.sp +.LP +The options are as follows: +.sp +.ne 2 +.na +\fB\fB-c\fR \fIcolumns\fR\fR +.ad +.RS 17n +Output is formatted for a display \fIcolumns\fR +wide. +.RE + +.sp +.ne 2 +.na +\fB\fB-s\fR \fIsep\fR\fR +.ad +.RS 17n +Specify a set of characters to be used to delimit columns for the +\fB-t\fR option. +.RE + +.sp +.ne 2 +.na +\fB\fB-t\fR\fR +.ad +.RS 17n +Determine the number of columns the input contains and create a table. +Columns are delimited with whitespace, by default, or with the characters +supplied using the \fBs\fR +option. +Useful for pretty-printing displays. +.RE + +.sp +.ne 2 +.na +\fB-x\fR +.ad +.RS 17n +Fill columns before filling rows. +.RE + +.SH ENVIRONMENT +The COLUMNS , LANG , LC_ALL +and +LC_CTYPE +environment variables affect the execution of +\fBcolumn\fR +as described in +\fBenviron\fR(5). + +.SH EXIT STATUS +The \fBcolumn\fR utility exits 0 on success and >0 if an error occurs. + +.SH EXAMPLES +.sp +.in +2 +.nf +(printf \&"PERM LINKS OWNER GROUP SIZE MONTH DAY \&"\ \&;\ \&\e +printf \&"HH:MM/YEAR NAME\en\&"\ \&;\ \&\e +ls -l \&| sed 1d) \&| column -t +.fi +.in -2 +.sp + + +.SH SEE ALSO +\fBls\fR(1), \fBpaste\fR(1), \fBsort\fR(1) + +.SH HISTORY +The \fBcolumn\fR command appeared in 4.3BSD-Reno. + +.SH BUGS +Input lines are limited to LINE_MAX bytes in length. diff --git a/usr/src/man/man1/crontab.1 b/usr/src/man/man1/crontab.1 index c93255f406..1008b63a21 100644 --- a/usr/src/man/man1/crontab.1 +++ b/usr/src/man/man1/crontab.1 @@ -1,6 +1,7 @@ '\" te .\" Copyright 1989 AT&T .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2011, Joyent, Inc. All Rights Reserved .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. .\" The Institute of Electrical and Electronics Engineers 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 @@ -10,7 +11,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH CRONTAB 1 "Apr 6, 2009" +.TH CRONTAB 1 "Sep 23, 2013" .SH NAME crontab \- user crontab file .SH SYNOPSIS @@ -26,7 +27,7 @@ crontab \- user crontab file .LP .nf -\fB/usr/bin/crontab\fR \fB-l\fR [\fIusername\fR] +\fB/usr/bin/crontab\fR \fB-l\fR [\fB-g\fR] [\fIusername\fR] .fi .LP @@ -46,7 +47,7 @@ crontab \- user crontab file .LP .nf -\fB/usr/xpg4/bin/crontab\fR \fB-l\fR [\fIusername\fR] +\fB/usr/xpg4/bin/crontab\fR \fB-l\fR [\fB-g\fR] [\fIusername\fR] .fi .LP @@ -66,7 +67,7 @@ crontab \- user crontab file .LP .nf -\fB/usr/xpg6/bin/crontab\fR \fB-l\fR [\fIusername\fR] +\fB/usr/xpg6/bin/crontab\fR \fB-l\fR [\fB-g\fR] [\fIusername\fR] .fi .LP @@ -86,6 +87,17 @@ users' crontabs. .LP If \fBcrontab\fR is invoked with \fIfilename\fR, this overwrites an existing \fBcrontab\fR entry for the user that invokes it. +.sp +.LP +Cron supports a merged crontab with entries coming from either the user's +\fB/var/spool/cron/crontabs\fR file or from the user's +\fB/etc/cron.d/crontabs\fR file. The entries in the user's +\fB/var/spool/cron/crontabs\fR file are editable whereas those in +\fB/etc/cron.d/crontabs\fR are system-defined entries which may not +be customized by the user. The dual set of crontab entries is only +of interest to system-defined users such as \fBroot\fR. Except where +otherwise explicitly indicated, all variants of the \fBcrontab\fR command +act only on the editable crontab files found in \fB/var/spool/cron/crontabs\fR. .SS "\fBcrontab\fR Access Control" .sp .LP @@ -343,6 +355,9 @@ file using the \fB-r\fR option. If \fIusername\fR is specified, the specified user's \fBcrontab\fR file is edited, rather than the current user's \fBcrontab\fR file. This can only be done by root or by a user with the \fBsolaris.jobs.admin\fR authorization. +.sp +Only the entries in the user's \fB/var/spool/cron/crontabs\fR file are +editable. .RE .sp @@ -354,6 +369,22 @@ done by root or by a user with the \fBsolaris.jobs.admin\fR authorization. Lists the \fBcrontab\fR file for the invoking user. Only root or a user with the \fBsolaris.jobs.admin\fR authorization can specify a username following the \fB-l\fR option to list the \fBcrontab\fR file of the specified user. +.sp +Entries from the user's \fB/var/spool/cron/crontabs\fR file are listed, unless +the \fB-g\fR option is given, in which case only entries from the user's +\fB/etc/cron.d/crontabs\fR file are listed. +.RE + +.sp +.ne 2 +.na +\fB\fB-g\fR\fR +.ad +.RS 6n +In conjunction with the \fB-l\fR option, lists the global \fBcrontab\fR file +for the invoking or specified user (if authorized) instead of the editable +\fBcrontab\fR file. This option is not valid unless the \fB-l\fR option is +also given. .RE .sp @@ -583,6 +614,15 @@ list of denied users .sp .ne 2 .na +\fB\fB/etc/cron.d/crontabs\fR\fR +.ad +.RS 28n +system spool area for \fBcrontab\fR +.RE + +.sp +.ne 2 +.na \fB\fB/var/cron/log\fR\fR .ad .RS 28n diff --git a/usr/src/man/man1/ctfdiff.1 b/usr/src/man/man1/ctfdiff.1 new file mode 100644 index 0000000000..1934c64c52 --- /dev/null +++ b/usr/src/man/man1/ctfdiff.1 @@ -0,0 +1,337 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2015, Joyent, Inc. +.\" +.Dd Oct 4, 2014 +.Dt CTFDIFF 1 +.Os +.Sh NAME +.Nm ctfdiff +.Nd compare two CTF containers +.Sh SYNOPSIS +.Nm ctfdiff +.Op Fl afIloqt +.Op Fl F Ar function +.Op Fl O Ar object +.Op Fl p Ar parent1 +.Op Fl p Ar parent2 +.Op Fl T Ar type +.Ar file1 file2 +.Sh DESCRIPTION +The +.Nm +utility identifies differences between the contents of the +.Sy CTF +containers found in +.Em file1 +and +.Em file2 . +.Lp +.Nm +can find differences between two +.Sy CTF +container's +.Sy labels , +.Sy functions , +.Sy objects , +and +.Sy types . +When no options are specified, +.Nm +will only consider +.Sy functions , +.Sy objects, +and +.Sy types . +.Lp +Two +.Sy labels +are considered the same, if they have the same name. Two +.Sy objects +are considered the same if they have the same name and the type of the +object is the same. Two +.Sy functions +are considered the same if they have the same, the same return type, the +same number of arguments, and the types of their arguments are the same. +.Lp +Two +.Sy types +are considered the same if they have the same, they represent the same +kind of thing, and the contents of the type are the same. This varies +for each specific kind, for example, two structs are the same if they +have the same members whose types, offsets, and names are all the same. +For more information on the specifics for what we look at for each kind +of type, and the kinds themselves, see the information we use to encode +them in +.Xr ctf 4 . If the option +.Fl I +is specified, then the names of basic integer types are ignored. For an +example of where this makes sense, see +.Sy Example 4 . +.Lp +If the +.Sy CTF +container found inside of either +.Em file1 +or +.Em file2 +has been uniquified (see +.Xr ctf 4 +for more on uniquification), then the parent +.Sy CTF +container is also required for the diff to complete. +.Sh OPTIONS +The following options are supported: +.Bl -hang -width Ds +.It Fl a +.Bd -filled -compact +Diff +.Sy labels , +.Sy types , +.Sy objects , +and +.Sy functions . +.Ed +.It Fl f +.Bd -filled -compact +Diff +.Sy function +type argument information. +.Ed +.It Fl F Ar function +.Bd -filled -compact +When diffing +.Sy functions , +only consider the function +.Em function . +This option requires that the option +.Fl -f +be specified and can be repeated multiple times. +.Ed +.It Fl I +.Bd -filled -compact +Ignore the names of integral types. This option is useful when comparing +types between two +.Sy CTF +containers that have different programming models. In this case, when +comparing integers, the name of the type is not considered. This means +that the ILP32 type long which is a 32-bit wide signed integer is the +same as the LP64 type int which is a 32-bit wide signed integer, even +though they have different names. +.Ed +.It Fl l +.Bd -filled -compact +Diff the +.Sy labels +contained inside the +.Sy CTF +containers. +.Ed +.It Fl o +.Bd -filled -compact +Diff type information for +.Sy objects . +.Ed +.It Fl O Ar object +.Bd -filled -compact +When diffing type information for +.Sy objects , +only compare if the object is name +.Em object . This option requires +.Fl o +to be specified and can be repeated multiple times. +.Ed +.It Fl p Ar parent1 +.Bd -filled -compact +Specifies the path of file that is the parent of the +.Sy CTF +container inside of +.Em file1 +is +.Em parent1 . +This option is required if +.Em file1 +has been uniquified. For more information on uniquification, see +.Xr ctf 4 . +.Ed +.It Fl P Ar parent2 +.Bd -filled -compact +Specifies the path of file that is the parent of the +.Sy CTF +container inside of +.Em file2 is +.Em parent2 . +This option is required if +.Em file1 +has been uniquified. For more information on uniquification, see +.Xr ctf 4 . +.Ed +.It Fl q +.Bd -filled -compact +Enables quiet mode. Standard output from the diff will not be emitted. +However, diagnostics messages will still be emitted to standard error. +.Ed +.It Fl t +.Bd -filled -compact +Diff the +.Sy type +information sections in the +.Sy CTF +containers. +.Ed +.It Fl T Ar type +.Bd -filled -compact +When diffing the +.Sy types +section, only consider it if the type is name +.Em type . +Types specified here do not impact the diffing of +.Sy objects +or +.Sy functions . +Even with +.Fl -T +specified, other types will be diffed as necessary for the evaluation of +the named types; however, the results of those intermediate differences +will not impact the results of +.Nm , +only named types are considered when evaluating the exit status of +.Nm . +.Ed +.El +.Sh EXIT STATUS +.Bl -inset +.It Sy 0 +.Bd -filled -offset indent -compact +Execution completed successfully, no differences were detected +between +.Em file1 +and +.Em file2 . +.Ed +.It Sy 1 +.Bd -filled -offset indent -compact +Execution completed successfully, but differences were detected +between +.Em file1 +and +.Em file2 . +.Ed +.It Sy 2 +.D1 Invalid command line options were specified. +.It Sy 3 +.D1 A fatal error occured. +.El +.Sh EXAMPLES +.Sy Example 1 +Diffing Two +.Sy CTF +Containers +.Lp +The following example compares two +.Sy CTF +containers using the default set +of comparisons: +.Sy objects , +.Sy functions , +and +.Sy types . +.Bd -literal -offset 6n +$ ctfdiff /usr/lib/libc.so.1 /usr/lib/libdtrace.so.1 +ctf container /usr/lib/libc.so.1 type 37 is different +ctf container /usr/lib/libc.so.1 type 38 is different +ctf container /usr/lib/libc.so.1 type 39 is different +ctf container /usr/lib/libc.so.1 type 40 is different +ctf container /usr/lib/libc.so.1 type 41 is different +ctf container /usr/lib/libc.so.1 type 42 is different +ctf container /usr/lib/libc.so.1 type 43 is different +ctf container /usr/lib/libc.so.1 type 47 is different +ctf container /usr/lib/libc.so.1 type 48 is different +ctf container /usr/lib/libc.so.1 type 49 is different +\&... +.Ed +.Sy Example 2 +Diffing Types Between Two +.Sy CTF +Containers with Parents +.Lp +The following example compares two +.Sy CTF +containers +.Sy /ws/rm/zlan/proto/kernel/drv/amd64/vnd +and +.Sy /ws/rm/zlan/proto/kernel/drv/amd64/overlay +that have been uniquified against the same container +.Sy /ws/rm/zlan/proto/kernel/amd64/genunix . +.Bd -literal -offset 6n +$ ctfdiff -t -p /ws/rm/zlan/proto/kernel/amd64/genunix \\ + -P /ws/rm/zlan/proto/kernel/amd64/genunix \\ + /ws/rm/zlan/proto/kernel/drv/amd64/vnd \\ + /ws/rm/zlan/proto/kernel/drv/amd64/overlay +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32769 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32770 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32771 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32772 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32774 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32775 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32776 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32777 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32778 is different +ctf container /ws/rm/zlan/proto/kernel/drv/amd64/vnd type 32779 is different +\&... +.Ed +.Lp +.Sy Example 3 +Diffing a Specific Function in Two +.Sy CTF +Containers +.Lp +This example shows us looking for differences in the function +.Sy libzfs_core_init +in two different version of the library +.Sy libzfs_core.so.1 . +.Bd -literal -offset 6n +$ ctfdiff -f -F libzfs_core_init /usr/lib/libzfs_core.so.1 \\ + /ws/rm/ctf/proto/usr/lib/libzfs_core.so.1 +$ echo $? +.Ed +.Lp +.Sy Example 4 +Diffing Types to Find Differences Between Different Data Models. +.Lp +This example looks for differences between structures used in an ioctl +that the kernel wants to be bitness neutral by comparing a 32-bit and +64-bit library that consumes it. In this example, we'll use the library +.Sy libvnd.so.1 +and the types +.Sy vnd_ioc_attach_t , +.Sy vnd_ioc_link_t , +.Sy vnd_ioc_unlink_t , +.Sy vnd_ioc_buf_t , +and +.Sy vnd_ioc_info_t . +.Bd -literal -offset 6n +$ ctfdiff -t -I -T vnd_ioc_attach_t -T vnd_ioc_link_t \\ + -T vnd_ioc_unlink_t -T vnd_ioc_buf_t -T vnd_ioc_info_t \\ + i386/libvnd.so.1 amd64/libvnd.so.1 +$ echo $? +0 +.Ed +.Sh INTERFACE STABILITY +The command syntax is +.Sy Committed . +The output format is +.Sy Uncommitted . +.Sh SEE ALSO +.Xr ctfdump 1 , +.Xr diff 1 , +.Xr ctf 4 diff --git a/usr/src/man/man1/ctfdump.1 b/usr/src/man/man1/ctfdump.1 new file mode 100644 index 0000000000..d502352c8a --- /dev/null +++ b/usr/src/man/man1/ctfdump.1 @@ -0,0 +1,214 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2015, Joyent, Inc. +.\" +.Dd Oct 4, 2014 +.Dt CTFDUMP 1 +.Os +.Sh NAME +.Nm ctfdump +.Nd dump parts of ctf data from files +.Sh SYNOPSIS +.Nm ctfdump +.Op Fl dfhlsSt +.Op Fl p Ar parent +.Op Fl u Ar outfile +.Ar file +.Sh DESCRIPTION +The +.Nm +utility dumps and decodes the +.Sy CTF +data contained inside of +.Sy ELF +objects and raw +.Sy CTF +files. +.Lp +.Nm +can dump information about the +.Sy CTF header , +the +.Sy labels +encoded in the +.Sy CTF +container, +the types of +.Sy data objects , +the internal +.Sy string +table, +the types of the return function and the arguments for +.Sy functions , +and of course, it displays information about the +.Sy types +defined in the +.Sy CTF +container. +.Lp +.Nm +can also be used to dump out the raw +.Sy CTF +data and send it to another file. When writing out data, it always +ensures that the +.Sy CTF +data is decompressed. In this form, the +.Sy CTF +data can be inspected using +.Nm +and other tools such as +.Xr mdb 1 . +.Lp +When no options are specified, +.Nm +displays all information. However, when the +.Fl u +option is used, then no information is displayed by default, unless +requested through the the appropriate option. +.Sh OPTIONS +The following options are supported: +.Bl -hang -width Ds +.It Fl d +.Bd -filled -compact +Dump the types of symbols that correspond to objects. +.Ed +.It Fl f +.Bd -filled -compact +Dump the types of the return values and arguments of the functions. +.Ed +.It Fl h +.Bd -filled -compact +Dump the +.Sy CTF +header +.Ed +.It Fl l +.Bd -filled -compact +Dump all +.Sy CTF +labels associated with the file. +.Ed +.It Fl p Ar parent +.Bd -filled -compact +Use the type information in +.Em parent +to supplement output. This is useful when a +.Nm CTF +container has been +.Sy uniquified +against +.Em parent . +This allows +.Nm +to use the names of types when used with +.Fl t . +.Ed +.It Fl s +.Bd -filled -compact +Dump the internal +.Sy CTF +string table +.Ed +.It Fl S +.Bd -filled -compact +Displays statistics about the +.Sy CTF +container. +.Ed +.It Fl t +.Bd -filled -compact +Dump the type information contained in the +.Sy CTF +conatiner. +.Ed +.It Fl u Ar outfile +.Bd -filled -compact +Copies the uncompressed +.Sy CTF +data to the file specified by +.Em outfile . +This can be used to make it easier to inspect the raw +.Sy CTF +data. +.Ed +.El +.Sh EXIT STATUS +.Bl -inset +.It Sy 0 +.Dl Execution completed successfully. +.It Sy 1 +.Dl A fatal error occured. +.It Sy 2 +.Dl Invalid command line options were specified. +.El +.Sh EXAMPLES +.Sy Example 1 +Displaying the Type Section of a Single File +.Lp +The following example dumps the type section of the file +.Sy /usr/lib/libc.so.1 . +.Bd -literal -offset 6n +$ ctfdump -t /usr/lib/libc.so.1 +- Types ---------------------------------------------------- + + <1> int encoding=SIGNED offset=0 bits=32 + <2> long encoding=SIGNED offset=0 bits=32 + <3> typedef pid_t refers to 2 + <4> unsigned int encoding=0x0 offset=0 bits=32 + <5> typedef uid_t refers to 4 + <6> typedef gid_t refers to 5 + <7> typedef uintptr_t refers to 4 +\&... +.Ed +.Lp +.Sy Example 2 +Dumping the CTF data to Another File +.Lp +The following example dumps the entire CTF data from the file +.Sy /usr/lib/libc.so.1 +and places it into the file +.Sy ctf.out . +This then shows how you can use the +.Xr mdb 1 +to inspect its contents. +.Bd -literal -offset 6n +$ ctfdump -u ctf.out /usr/lib/libc.so.1 +$ mdb ./ctf.out +> ::typedef -r /usr/lib/libctf.so.1 +> 0::print ctf_header_t +{ + cth_preamble = { + ctp_magic = 0xcff1 + ctp_version = 0x2 + ctp_flags = 0 + } + cth_parlabel = 0 + cth_parname = 0 + cth_lbloff = 0 + cth_objtoff = 0x8 + cth_funcoff = 0x5e0 + cth_typeoff = 0x7178 + cth_stroff = 0x12964 + cth_strlen = 0x7c9c +} +.Ed +.Sh INTERFACE STABILITY +The command syntax is +.Sy Committed . +The output format is +.Sy Uncommitted . +.Sh SEE ALSO +.Xr ctfdiff 1 , +.Xr dump 1 , +.Xr elfdump 1 , +.Xr mdb 1 , +.Xr ctf 4 diff --git a/usr/src/man/man1/ld.1 b/usr/src/man/man1/ld.1 index fdddea7ece..4ebe033dce 100644 --- a/usr/src/man/man1/ld.1 +++ b/usr/src/man/man1/ld.1 @@ -24,7 +24,7 @@ ld \- link-editor for object files [\fB-z\fR combreloc | nocombreloc ] [\fB-z\fR defs | nodefs] [\fB-z\fR direct | nodirect] [\fB-z\fR endfiltee] [\fB-z\fR fatal-warnings | nofatal-warnings ] [\fB-z\fR finiarray=\fIfunction\fR] -[\fB-z\fR globalaudit] [\fB-z\fR groupperm | nogroupperm] +[\fB-z\fR globalaudit] [\fB-z\fR groupperm | nogroupperm] [\fB-z\fR help ] [\fB-z\fR guidance[=\fIid1\fR,\fIid2\fR...] [\fB-z\fR help ] [\fB-z\fR ignore | record] [\fB-z\fR initarray=\fIfunction\fR] [\fB-z\fR initfirst] [\fB-z\fR interpose] [\fB-z\fR lazyload | nolazyload] diff --git a/usr/src/man/man1/ld.so.1.1 b/usr/src/man/man1/ld.so.1.1 index 4b14ca4f1a..19afbbf3d6 100644 --- a/usr/src/man/man1/ld.so.1.1 +++ b/usr/src/man/man1/ld.so.1.1 @@ -1,9 +1,10 @@ '\" .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH LD.SO.1 1 "Oct 5, 2012" +.TH LD.SO.1 1 "May 8, 2014" .SH NAME ld.so.1 \- runtime linker for dynamic objects .SH SYNOPSIS @@ -574,6 +575,24 @@ aid debugging. See also the \fBRTLD_DI_SETSIGNAL\fR request to .RE .sp +.ne 2 +.na +.BR LD_TOXIC_PATH, +.BR LD_TOXIC_PATH_32, +.BR LD_TOXIC_PATH_64, +.ad +.sp .6 +.RS 4n +The toxic path refers to a set of paths where by, if +.B ld.so.1 +were to load a dependency on that path, rather than loading it, it +should kill the process. This is useful when having built libraries that +while matching the native architecture of the system, are not suitable +to be used, for example, libraries that that correspond to an alternate +release of an operating system. +.RE + +.sp .LP Notice that environment variable names beginning with the characters '\fBLD_\fR' are reserved for possible future enhancements to \fBld\fR(1) and diff --git a/usr/src/man/man1/machid.1 b/usr/src/man/man1/machid.1 new file mode 100644 index 0000000000..cb95fa36b6 --- /dev/null +++ b/usr/src/man/man1/machid.1 @@ -0,0 +1,25 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 1999, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" Copyright 2015, Joyent, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH MACHID 1 "Feb 27, 2015" +.SH NAME +machid, sun, i286, i386, i486, sparc \- get processor type truth value + +.SH DESCRIPTION +.sp +.LP +These commands are obsolete and may be removed in a future version of the +software. +.sp +.ne 2 +.na +.SH NOTES +.sp +.LP +The \fBmachid\fR family of commands is obsolete. Use \fBuname\fR \fB-p\fR and +\fBuname\fR \fB-m\fR instead. diff --git a/usr/src/man/man1/nawk.1 b/usr/src/man/man1/nawk.1 index 425db5d299..2c27e1baa0 100644 --- a/usr/src/man/man1/nawk.1 +++ b/usr/src/man/man1/nawk.1 @@ -15,6 +15,12 @@ nawk \- pattern scanning and processing language .SH SYNOPSIS .LP .nf +\fB/usr/bin/awk\fR [\fB-F\fR \fIERE\fR] [\fB-v\fR \fIassignment\fR] \fI\&'program'\fR | \fB-f\fR \fIprogfile\fR... + [\fIargument\fR]... +.fi + +.LP +.nf \fB/usr/bin/nawk\fR [\fB-F\fR \fIERE\fR] [\fB-v\fR \fIassignment\fR] \fI\&'program'\fR | \fB-f\fR \fIprogfile\fR... [\fIargument\fR]... .fi @@ -28,7 +34,8 @@ nawk \- pattern scanning and processing language .SH DESCRIPTION .sp .LP -The \fB/usr/bin/nawk\fR and \fB/usr/xpg4/bin/awk\fR utilities execute +The \fB/usr/bin/awk\fR, \fB/usr/bin/nawk\fR and \fB/usr/xpg4/bin/awk\fR +utilities execute \fIprogram\fRs written in the \fBnawk\fR programming language, which is specialized for textual data manipulation. A \fBnawk\fR \fIprogram\fR is a sequence of patterns and corresponding actions. The string specifying diff --git a/usr/src/man/man1/pmadvise.1 b/usr/src/man/man1/pmadvise.1 index 93d3b45576..1210155f6c 100644 --- a/usr/src/man/man1/pmadvise.1 +++ b/usr/src/man/man1/pmadvise.1 @@ -79,6 +79,7 @@ free access_lwp access_many access_default +purge .fi .in -2 .sp @@ -127,7 +128,7 @@ from the other advice within the same group: .in +2 .nf MADV_NORMAL, MADV_RANDOM, MADV_SEQUENTIAL -MADV_WILLNEED, MADV_DONTNEED, MADV_FREE +MADV_WILLNEED, MADV_DONTNEED, MADV_FREE, MADV_PURGE MADV_ACCESS_DEFAULT, MADV_ACCESS_LWP, MADV_ACCESS_MANY .fi .in -2 diff --git a/usr/src/man/man1/proc.1 b/usr/src/man/man1/proc.1 index cd20e215e3..bf0e588012 100644 --- a/usr/src/man/man1/proc.1 +++ b/usr/src/man/man1/proc.1 @@ -2,10 +2,11 @@ .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved .\" Portions Copyright 2008 Chad Mynhier .\" Copyright 2012 DEY Storage Systems, Inc. All rights reserved. +.\" Copyright 2013 (c) Joyent, Inc. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PROC 1 "Oct 23, 2012" +.TH PROC 1 "Apr 01, 2013" .SH NAME proc, pflags, pcred, pldd, psig, pstack, pfiles, pwdx, pstop, prun, pwait, ptime \- proc tools @@ -72,7 +73,7 @@ ptime \- proc tools .LP .nf -\fB/usr/bin/ptime\fR [\fB-Fm\fR] [\fB-p\fR] \fIpid\fR... +\fB/usr/bin/ptime\fR [\fB-Fm\fR] \fB-p pidlist\fR .fi .LP @@ -215,8 +216,10 @@ Time the \fIcommand\fR, like \fBtime\fR(1), but using microstate accounting for reproducible precision. Unlike \fBtime\fR(1), children of the command are not timed. .sp -If the \fB-p\fR \fIpid\fR version is used, display a snapshot of timing -statistics for the specified \fIpid\fR. +If the \fB-p\fR \fIpidlist\fR version is used, display a snapshot of timing +statistics for the specified processes. The \fIpidlist\fR may either be a comma +delineated list or a space delineated list. Space delineated lists must be +properly quoted to assure that they are in a single argument. .RE .SH OPTIONS diff --git a/usr/src/man/man1/ps.1 b/usr/src/man/man1/ps.1 index 7ff574f12b..2b0d435c44 100644 --- a/usr/src/man/man1/ps.1 +++ b/usr/src/man/man1/ps.1 @@ -38,6 +38,9 @@ displayed is controlled by the options. Some options accept lists as arguments. Items in a list can be either separated by commas or else enclosed in quotes and separated by commas or spaces. Values for \fIproclist\fR and \fIgrplist\fR must be numeric. +.sp +.LP +The \fBps\fR command also accepts BSD-style options. See \fBps\fR(1b). .SH OPTIONS .sp .LP @@ -1311,7 +1314,8 @@ Standard See \fBstandards\fR(5). .sp .LP \fBkill\fR(1), \fBlgrpinfo\fR(1), \fBnice\fR(1), \fBpagesize\fR(1), -\fBpmap\fR(1), \fBpriocntl\fR(1), \fBwho\fR(1), \fBgetty\fR(1M), \fBproc\fR(4), +\fBpmap\fR(1), \fBpriocntl\fR(1), \fBps\fR(1b), \fBwho\fR(1), \fBgetty\fR(1M), +\fBproc\fR(4), \fBttysrch\fR(4), \fBattributes\fR(5), \fBenviron\fR(5), \fBresource_controls\fR(5), \fBstandards\fR(5), \fBzones\fR(5) .SH NOTES diff --git a/usr/src/man/man1/sed.1 b/usr/src/man/man1/sed.1 index 126402343c..cd805bd841 100644 --- a/usr/src/man/man1/sed.1 +++ b/usr/src/man/man1/sed.1 @@ -1,8 +1,6 @@ .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" -.\" Copyright 2011 Nexenta Systems, Inc. All rights reserved. -.\" .\" This code is derived from software contributed to Berkeley by .\" the Institute of Electrical and Electronics Engineers, Inc. .\" @@ -44,7 +42,8 @@ [\fB\-Ealnr\fP] [\fB\-e\fP \fIcommand\fP] [\fB\-f\fP \fIcommand_file\fP] -[\fB\-I\fP[\fIextension\fP] | \fB\-i\fP[\fIextension\fP]] +[\fB\-I\fP \fIextension\fP] +[\fB\-i\fP \fIextension\fP] [\fIfile ...\fP] .SH DESCRIPTION The @@ -97,11 +96,16 @@ Append the editing commands found in the file to the list of commands. The editing commands should each be listed on a separate line. .TP -\fB\-I\fP[\fIextension\fP] -Edit files in-place, saving backups if \fIextension\fP was specified. -It is not recommended to omit saving backups when in-place editing files, -as you risk corruption or partial content in situations where disk -space is exhausted, etc. +\fB\-I\fP \fIextension\fP +Edit files in-place, saving backups with the specified +\fIextension\fP. +If a zero-length +\fIextension\fP +is given, no backup will be saved. +It is not recommended to give a zero-length +\fIextension\fP +when in-place editing files, as you risk corruption or partial content +in situations where disk space is exhausted, etc. Note that in-place editing with \fB\-I\fP @@ -119,7 +123,7 @@ where using \fB\-i\fP is desired. .TP -\fB\-i\fP[\fIextension\fP] +\fB\-i\fP \fIextension\fP Edit files in-place similarly to \fB\-I\fP, but treat each file independently from other files. diff --git a/usr/src/man/man1/zlogin.1 b/usr/src/man/man1/zlogin.1 index 7c99eb6cb1..476faab86f 100644 --- a/usr/src/man/man1/zlogin.1 +++ b/usr/src/man/man1/zlogin.1 @@ -13,43 +13,43 @@ .\" Portions Copyright [yyyy] [name of copyright owner] .\" Copyright 2013 DEY Storage Systems, Inc. .\" Copyright (c) 2014 Gary Mills +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved. -.TH ZLOGIN 1 "Mar 17, 2015" +.TH ZLOGIN 1 "Mar 30, 2015" .SH NAME zlogin \- enter a zone .SH SYNOPSIS .LP .nf -\fBzlogin\fR [\fB-dCEQ\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR +\fBzlogin\fR [\fB-dCEINQ\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR .fi .LP .nf -\fBzlogin\fR [\fB-nEQS\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR \fIutility\fR +\fBzlogin\fR [\fB-inEQS\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR \fIutility\fR [\fIargument\fR]... .fi .SH DESCRIPTION -.sp .LP The \fBzlogin\fR utility is used by the administrator to enter an operating system zone. Only a superuser operating in the global system zone can use this utility. .sp .LP -\fBzlogin\fR operates in one of three modes: +\fBzlogin\fR operates in one of four modes: .sp .ne 2 .na \fBInteractive Mode\fR .ad .RS 24n -If no utility argument is given and the stdin file descriptor for the -\fBzlogin\fR process is a tty device, \fBzlogin\fR operates in \fBinteractive -mode\fR. In this mode, \fBzlogin\fR creates a new pseudo terminal for use -within the login session. Programs requiring a tty device, for example, -\fBvi\fR(1), work properly in this mode. In this mode, \fBzlogin\fR invokes -\fBlogin\fR(1) to provide a suitable login session. +If no utility argument is given or if the \fB-i\fR option is specified, and the +stdin file descriptor for the \fBzlogin\fR process is a tty device, \fBzlogin\fR +operates in \fBinteractive mode\fR. In this mode, \fBzlogin\fR creates a new +pseudo terminal for use within the login session. Programs requiring a tty +device, for example, \fBvi\fR(1), work properly in this mode. In this mode, +\fBzlogin\fR invokes \fBlogin\fR(1) to provide a suitable login session. .RE .sp @@ -58,11 +58,12 @@ within the login session. Programs requiring a tty device, for example, \fBNon-Interactive Mode\fR .ad .RS 24n -If a utility is specified, \fBzlogin\fR operates in \fBnon-interactive mode\fR. -This mode can be useful for script authors since stdin, stdout, and stderr are -preserved and the exit status of \fIutility\fR is returned upon termination. In -this mode, \fBzlogin\fR invokes \fBsu\fR(1M) in order to set up the user's -environment and to provide a login environment. +If a utility is specified and the \fB-i\fR option is not specified, \fBzlogin\fR +operates in \fBnon-interactive mode\fR. This mode can be useful for script +authors since stdin, stdout, and stderr are preserved and the exit status of +\fIutility\fR is returned upon termination. In this mode, \fBzlogin\fR invokes +\fBsu\fR(1M) in order to set up the user's environment and to provide a login +environment. .sp The specified command is passed as a string and interpreted by a shell running in the non-global zone. See \fBrsh\fR(1). @@ -80,8 +81,17 @@ available once the zone is in the installed state. Connections to the console are persistent across reboot of the zone. .RE -.SH OPTIONS .sp +.ne 2 +.na +\fBStandalone-processs Interactive Mode\fR +.ad +.RS 24n +If the \fB-I\fR option is specified the user is connected to the zone's stdin, +stdout and stderr \fBzfd(7D)\fR devices. +.RE + +.SH OPTIONS .LP The following options are supported: .sp @@ -127,6 +137,25 @@ login by using the escape sequence character. .sp .ne 2 .na +\fB\fB-i\fR\fR +.ad +.RS 15n +Forces interactive mode when a utility argument is specified. +.RE + +.sp +.ne 2 +.na +\fB\fB-I\fR\fR +.ad +.RS 15n +Connects to the zone's \fBzfd(7D)\fR devices. +.RE + +.sp +.sp +.ne 2 +.na \fB\fB-l\fR \fIusername\fR\fR .ad .RS 15n @@ -149,6 +178,17 @@ and the shell which invokes \fBzlogin\fR both read from standard input. .sp .ne 2 .na +\fB-N\fR +.ad +.RS 15n +Nohup. This may only be used with the -I option to avoid sending EOF to the zfd +device when zlogin's stdin receives EOF. It can also be toggled by sending +\fBSIGUSR1\fR to an attached zlogin process. +.RE + +.sp +.ne 2 +.na \fB-Q\fR .ad .RS 15n @@ -172,7 +212,6 @@ other forms of login have become impossible. .RE .SS "Escape Sequences" -.sp .LP Lines that you type that start with the tilde character (\fB~\fR) are "escape sequences". The escape character can be changed using the \fB-e\fR option. @@ -187,12 +226,10 @@ host breaks the connection with no warning to the zone's end. .RE .SH SECURITY -.sp .LP Once a process has been placed in a zone other than the global zone, the process cannot change zone again, nor can any of its children. .SH OPERANDS -.sp .LP The following operands are supported: .sp @@ -223,7 +260,6 @@ Arguments passed to the utility. .RE .SH EXIT STATUS -.sp .LP In interactive and non-interactive modes, the \fBzlogin\fR utility exits when the command or shell in the non-global zone exits. In non-interactive mode, the @@ -268,7 +304,6 @@ mode. .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -284,12 +319,10 @@ Interface Stability Evolving .TE .SH SEE ALSO -.sp .LP \fBlogin\fR(1), \fBrsh\fR(1), \fBvi\fR(1), \fBsu\fR(1M), \fBzoneadm\fR(1M), \fBzonecfg\fR(1M), \fBattributes\fR(5), \fBzones\fR(5) .SH NOTES -.sp .LP \fBzlogin\fR fails if its open files or any portion of its address space corresponds to an NFS file. This includes the executable itself or the shared diff --git a/usr/src/man/man1m/Makefile b/usr/src/man/man1m/Makefile index ddeddbafd5..779f1d8a31 100644 --- a/usr/src/man/man1m/Makefile +++ b/usr/src/man/man1m/Makefile @@ -13,9 +13,10 @@ # Copyright 2011, Richard Lowe # Copyright (c) 2012, Joyent, Inc. All rights reserved. # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright (c) 2014 Joyent, Inc. All rights reserved. # -include $(SRC)//Makefile.master +include $(SRC)//Makefile.master MANSECT= 1m @@ -488,8 +489,6 @@ _MANFILES= 6to4relay.1m \ soconfig.1m \ sppptun.1m \ spray.1m \ - ssh-keysign.1m \ - sshd.1m \ statd.1m \ stmfadm.1m \ stmsboot.1m \ @@ -551,7 +550,10 @@ _MANFILES= 6to4relay.1m \ uucleanup.1m \ uusched.1m \ uuxqt.1m \ + vfsstat.1m \ vmstat.1m \ + vndadm.1m \ + vndstat.1m \ volcopy.1m \ volcopy_ufs.1m \ vscanadm.1m \ diff --git a/usr/src/man/man1m/dladm.1m b/usr/src/man/man1m/dladm.1m index c8b2dd8e3e..9120023170 100644 --- a/usr/src/man/man1m/dladm.1m +++ b/usr/src/man/man1m/dladm.1m @@ -1,6 +1,6 @@ '\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved -.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. .\" The Institute of Electrical and Electronics Engineers 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 Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical @@ -9,14 +9,14 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH DLADM 1M "Dec 03, 2014" +.TH DLADM 1M "Apr 09, 2015" .SH NAME dladm \- administer data links .SH SYNOPSIS .LP .nf \fBdladm show-link\fR [\fB-P\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [[\fB-p\fR] \fB-o\fR \fIfield\fR[,...]] [\fIlink\fR] -\fBdladm rename-link\fR [\fB-R\fR \fIroot-dir\fR] \fIlink\fR \fInew-link\fR +\fBdladm rename-link\fR [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fIlink\fR \fInew-link\fR .fi .LP @@ -99,9 +99,11 @@ dladm \- administer data links .LP .nf -\fBdladm set-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIlink\fR -\fBdladm reset-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-p\fR \fIprop\fR[,...]] \fIlink\fR -\fBdladm show-linkprop\fR [\fB-P\fR] [[\fB-c\fR] \fB-o\fR \fIfield\fR[,...]] [\fB-p\fR \fIprop\fR[,...]] [\fIlink\fR] +\fBdladm set-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] + \fIlink\fR +\fBdladm reset-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] [\fB-p\fR \fIprop\fR[,...]] \fIlink\fR +\fBdladm show-linkprop\fR [\fB-P\fR] [\fB-z\fR \fIzonename\fR] [[\fB-c\fR] \fB-o\fR \fIfield\fR[,...]] + [\fB-p\fR \fIprop\fR[,...]] [\fIlink\fR] .fi .LP @@ -116,9 +118,9 @@ dladm \- administer data links \fBdladm create-vnic\fR [\fB-t\fR] \fB-l\fR \fIlink\fR [\fB-R\fR \fIroot-dir\fR] [\fB-m\fR \fIvalue\fR | auto | {factory \fB-n\fR \fIslot-identifier\fR]} | {random [\fB-r\fR \fIprefix\fR]}] [\fB-v\fR \fIvlan-id\fR] [\fB-p\fR \fIprop\fR=\fIvalue\fR[,...]] \fIvnic-link\fR -\fBdladm delete-vnic\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fIvnic-link\fR +\fBdladm delete-vnic\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fIvnic-link\fR \fBdladm show-vnic\fR [\fB-pP\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [\fB-o\fR \fIfield\fR[,...]] - [\fB-l\fR \fIlink\fR] [\fIvnic-link\fR] + [\fB-l\fR \fIlink\fR] [\fB-z\fR \fIzonename\fR] [\fIvnic-link\fR] .fi .LP @@ -139,6 +141,14 @@ dladm \- administer data links .LP .nf +\fBdladm create-overlay\fR [\fB-t\fR] \fB-e\fR \fIencap\fR \fB-s\fR \fIsearch\fR \fB-v\fR \fIvnetid\fR [\fB-p\fR \fIprop\fR=\fIvalue\fR[,...]] \fIoverlay\fR +\fBdladm delete-overlay\fR \fIoverlay\fR +\fBdladm modify-overlay\fR \fB-d\fR \fImac\fR | \fB-f\fR | \fB-s\fR \fImac=ip:port\fR \fIoverlay\fR +\fBdladm show-overlay\fR [ \fB-f\fR | \fB-t\fR ] [[\fB-p\fR] \fB-o\fR \fIfield\fR[,...]] [\fIoverlay\fR] +.fi + +.LP +.nf \fBdladm show-usage\fR [\fB-a\fR] \fB-f\fR \fIfilename\fR [\fB-p\fR \fIplotfile\fR \fB-F\fR \fIformat\fR] [\fB-s\fR \fItime\fR] [\fB-e\fR \fItime\fR] [\fIlink\fR] .fi @@ -226,9 +236,9 @@ A WiFi datalink. .ad .sp .6 .RS 4n -A virtual network interface created on a link or an \fBetherstub\fR. It is a -pseudo device that can be treated as if it were an network interface card on a -machine. +A virtual network interface created on a link, an \fBetherstub\fR, or \fBan +overlay\fR. It is a pseudo device that can be treated as if it were an network +interface card on a machine. .RE .sp @@ -296,6 +306,20 @@ use any alphanumeric characters, as well as underscore (\fB_\fR), period characters. .RE +.sp +.ne 2 +.na +.B overlay +.ad +.sp .6 +.RS 4n +An overlay instance, identified by an administratively-chosen name. An overlay +can be used to create or join an existing software defined network. +VNICs created on an overlay will appear to be connected by a local virtual +switch and will also be connected to interfaces on matching overlays provided by +other hosts. For more information on overlay devices, see \fBoverlay\fR(5). +.RE + .SS "Options" .LP Each \fBdladm\fR subcommand has its own set of options. However, many of the @@ -568,8 +592,7 @@ will be displayed only once. .sp .ne 2 .na -\fB\fBdladm rename-link\fR [\fB-R\fR \fIroot-dir\fR] \fIlink\fR -\fInew-link\fR\fR +\fB\fBdladm rename-link\fR [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fIlink\fR \fInew-link\fR\fR .ad .sp .6 .RS 4n @@ -587,6 +610,16 @@ examples of how this subcommand is used. See "Options," above. .RE +.sp +.ne 2 +.na +\fB\fB-z\fR \fIzonename\fR +.ad +.sp .6 +.RS 4n +A link assigned to a zone can only be renamed while the zone is in the ready state. +.RE + .RE .sp @@ -3192,8 +3225,7 @@ Extended output is displayed for \fBPTYPE\fR values of \fBcurrent\fR, .sp .ne 2 .na -\fB\fBdladm set-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-p\fR -\fIprop\fR=\fIvalue\fR[,...] \fIlink\fR\fR +\fB\fBdladm set-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIlink\fR\fR .ad .sp .6 .RS 4n @@ -3225,6 +3257,16 @@ See "Options," above. .sp .ne 2 .na +\fB\fB-z\fR \fIzonenme\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + +.sp +.ne 2 +.na \fB\fB-p\fR \fIprop\fR=\fIvalue\fR[,...], \fB--prop\fR \fIprop\fR=\fIvalue\fR[,...]\fR .ad @@ -3244,8 +3286,7 @@ same value. .sp .ne 2 .na -\fB\fBdladm reset-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-p\fR -\fIprop\fR,...] \fIlink\fR\fR +\fB\fBdladm reset-linkprop\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] [\fB-p\fR \fIprop\fR,...] \fIlink\fR\fR .ad .sp .6 .RS 4n @@ -3277,6 +3318,16 @@ See "Options," above. .sp .ne 2 .na +\fB\fB-z\fR \fIzonenme\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + +.sp +.ne 2 +.na \fB\fB-p\fR \fIprop, ...\fR, \fB--prop\fR=\fIprop, ...\fR\fR .ad .sp .6 @@ -3291,8 +3342,7 @@ the same value. .sp .ne 2 .na -\fB\fBdladm show-linkprop\fR [\fB-P\fR] [[\fB-c\fR] \fB-o\fR -\fIfield\fR[,...]][\fB-p\fR \fIprop\fR[,...]] [\fIlink\fR]\fR +\fB\fBdladm show-linkprop\fR [\fB-P\fR] [\fB-z\fR \fIzonename\fR] [[\fB-c\fR] \fB-o\fR \fIfield\fR[,...]][\fB-p\fR \fIprop\fR[,...]] [\fIlink\fR]\fR .ad .sp .6 .RS 4n @@ -3410,6 +3460,16 @@ Display persistent link property information .sp .ne 2 .na +\fB\fB-z\fR \fIzonenme\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + +.sp +.ne 2 +.na \fB\fB-p\fR \fIprop, ...\fR, \fB--prop\fR=\fIprop, ...\fR\fR .ad .sp .6 @@ -3727,8 +3787,7 @@ A comma-separated list of properties to set to the specified values. .sp .ne 2 .na -\fB\fBdladm delete-vnic\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] -\fIvnic-link\fR\fR +\fB\fBdladm delete-vnic\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fIvnic-link\fR\fR .ad .sp .6 .RS 4n @@ -3754,13 +3813,22 @@ next reboot. See "Options," above. .RE +.sp +.ne 2 +.na +\fB\fB-z\fR \fIzonenme\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + .RE .sp .ne 2 .na -\fB\fBdladm show-vnic\fR [\fB-pP\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] -[\fB-o\fR \fIfield\fR[,...]] [\fB-l\fR \fIlink\fR] [\fIvnic-link\fR]\fR +\fB\fBdladm show-vnic\fR [\fB-pP\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [\fB-o\fR \fIfield\fR[,...]] [\fB-l\fR \fIlink\fR] [\fB-z\fR \fIzonename\fR] [\fIvnic-link\fR]\fR .ad .sp .6 .RS 4n @@ -3903,6 +3971,16 @@ will be displayed only once. Display information for all VNICs on the named link. .RE +.sp +.ne 2 +.na +\fB\fB-z\fR \fIzonenme\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + .RE .sp @@ -4320,6 +4398,348 @@ The tunnel destination address. .sp .ne 2 .na +\fBdladm create-overlay\fR \fB-e\fR \fIencap\fR \fB-s\fR \fIsearch\fR +\fB-v\fR \fIvnetid\fR [\fB-p\fR \fIprop\fR=\fIvalue\fR[,...]] \fIoverlay\fR +.ad +.sp .6 +.RS 4n +Create an overlay device named \fIoverlay\fR. +.sp +Overlay devices are similar to etherstubs. VNICs can be created on top +of them. However, unlike an etherstub which is local to the system, an +overlay device can be configured to communicate to remote hosts, +providing a means for network virtualization. The way in which it does +this is described by the encapsulation module and the search plugin. For +more information on these, see \fBoverlay\fR(5). +.sp +An overlay device has a series of required and optional properties. These +properties vary based upon the search and encapsulation modules and are fully +specified in \fBoverlay\fR(5). Not every property needs to be specified - some +have default values which will be used if nothing specific is specified. For +example, the default port for VXLAN comes from its IANA standard. If a +required property is missing, the command will fail and inform you of the +missing properties. +.sp +.ne 2 +.na +\fB\fB-t\fR, \fB--temporary\fR\fR +.ad +.sp .6 +.RS 4n +Specifies that the overlay is temporary. Temporary overlays last until +the next reboot. +.RE + +.sp +.ne 2 +.na +\fB-e\fR \fIencap\fR, \fB--encap\fR=\fIencap\fR +.ad +.sp .6 +.RS 4n +Use \fIencap\fR as the encapsulation plugin for the overlay device +\fIoverlay\fR. The encapsulation plugin determines how packets are transformed +before being put on the wire. +.RE + +.sp +.ne 2 +.na +\fB-s\fR \fIsearch\fR, \fB--search\fR=\fIsearch\fR +.ad +.sp .6 +.RS 4n +Use \fIsearch\fR as the search plugin for \fIoverlay\fR. The search plugin +determines how non-local targets are found and where packets are directed to. +.RE + +.sp +.ne 2 +.na +\fB\fB-p\fR \fIprop\fR=\fIvalue\fR,..., \fB--prop\fR +\fIprop\fR=\fIvalue\fR,...\fR +.ad +.sp .6 +.RS 4n +A comma-separated list of properties to set to the specified values. +.RE + +.sp +.ne 2 +.na +\fB-v\fR \fIvnetid\fR, \fB--vnetid\fR=\fIvnetid\fR +.ad +.sp .6 +.RS 4n +Sets the virtual networking identfier to \fIvnetid\fR. A virtual network +identifier determines is similar to a VLAN identifier, in that it identifies a +unique virtual network. All overlay devices on the system share the same space +for the virtual network idenfifiter. However, the valid range of identifiers is +determined by the encapsulation plugin specified by \fB-e\fR. +.RE + +.RE + +.sp +.ne 2 +.na +\fBdladm delete-overlay\fR \fIoverlay\fR +.ad +.sp .6 +.RS 4n +Delete the specified overlay. This will fail if there are VNICs on top of the +device. +.RE + +.sp +.ne 2 +.na +\fBdladm modify-overlay\fR \fB-d\fR \fImac\fR | \fB-f\fR | \fB-s\fR \fImac=ip:port\fR \fIoverlay\fR +.ad +.sp .6 +.RS 4n +Modifies the target tables for the specified overlay. +.sp +The different options allow for different ways of modifying the target table. +One of \fB-d\fR, \fB-f\fR, and \fB-s\fR is required. This is not applicable for +all kinds of overlay devices. For more information, see \fBoverlay\fR(5). +.sp +.ne 2 +.na +\fB-d\fR \fImac\fR, \fB--delete-entry\fR=\fImac\fR +.ad +.sp .6 +.RS 4n +Deletes the entry for \fImac\fR from the target table for \fIoverlay\fR. Note, +if a lookup is pending or outstanding, this does not cancel it or stop it from +updating the value. +.RE + +.sp +.ne 2 +.na +\fB-f\fR, \fB--flush-table\fR +.ad +.sp .6 +.RS 4n +Flushes all values in the target table for \fIoverlay\fR. +.RE + +.sp +.ne 2 +.na +\fB-s\fR \fImac\fR=\fIvalue\fR, \fB--set-entry\fR=\fImac\fR=\fIvalue\fR +.ad +.sp .6 +.RS 4n +Sets the value of \fIoverlay\fR's target table entry for \fImac\fR to the +specified value. The specified value varies upon the encapsulation plugin. The +value may be a combination of a MAC address, IP adress, and port. Generall, this +looks like [\fImac\fR,][\fIIP\fR:][\fIport\fR]. If a component is the last one, +then there is no need for a separator. eg. if just the MAC address or IP is +needed, it would look like \fImac\fR and \fIIP\fR respectively. +.RE + +.RE + +.sp +.ne 2 +.na +\fBdladm show-overlay\fR [ \fB-f\fR | \fB-t\fR ] [[\fB-p\fR] \fB-o\fR \fIfield\fR[,...]] [\fIoverlay\fR] +.ad +.sp .6 +.RS 4n +Shows overlay configuration (the default), internal target tables (\fB-t\fR), or +the FMA state (\fB-f\fR), either for all overlays or the specified overlay. +.sp +By default (with neither \fB-f\fR or \fB-t\fR specified), the following fields +will be displayed: +.sp +.ne 2 +.na +\fB\fBLINK\fR\fR +.ad +.sp .6 +.RS 4n +The name of the overlay. +.RE + +.sp +.ne 2 +.na +\fB\fBPROPERTY\fR\fR +.ad +.sp .6 +.RS 4n +The name of the property. +.RE + +.sp +.ne 2 +.na +\fB\fBPERM\fR\fR +.ad +.sp .6 +.RS 4n +The read/write permissions of the property. The value shown is one of \fBr-\fR +or \fBrw\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBVALUE\fR\fR +.ad +.sp .6 +.RS 4n +The current property value. If the value is not set, it is shown as \fB--\fR. +If it is unknown, the value is shown as \fB?\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBDEFAULT\fR\fR +.ad +.sp .6 +.RS 4n +The default value of the property. If the property has no default value, +\fB--\fR is shown. +.RE + +.sp +.ne 2 +.na +\fB\fBPOSSIBLE\fR\fR +.ad +.sp .6 +.RS 4n +A comma-separated list of the values the property can have. If the values span +a numeric range, \fImin\fR - \fImax\fR might be shown as shorthand. If the +possible values are unknown or unbounded, \fB--\fR is shown. +.RE + +.sp +When the \fB-f\fR option is displayed, the following fields will be displayed: +.sp +.ne 2 +.na +\fB\fBLINK\fR\fR +.ad +.sp .6 +.RS 4n +The name of the overlay. +.RE + +.sp +.ne 2 +.na +\fB\fBSTATUS\fR\fR +.ad +.sp .6 +.RS 4n +Either \fBONLINE\fR or \fBDEGRADED\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBDETAILS\fR\fR +.ad +.sp .6 +.RS 4n +When the \fBoverlay\fR's status is \fBONLINE\fR, then this has the value +\fB--\fR. Otherwise, when it is \fBDEGRADED\fR, this field provides a more +detailed explanation as to why it's degraded. +.RE + +.sp +When the \fB-t\fR option is displayed, the following fields will be displayed: +.sp +.ne 2 +.na +\fB\fBLINK\fR\fR +.ad +.sp .6 +.RS 4n +The name of the overlay. +.RE + +.sp +.ne 2 +.na +\fB\fBTARGET\fR\fR +.ad +.sp .6 +.RS 4n +The target MAC address of a table entry. +.RE + +.sp +.ne 2 +.na +\fB\fBDESTINATION\fR\fR +.ad +.sp .6 +.RS 4n +The address that an encapsulated packet will be sent to when a packet has the +address specified by \fBTARGET\fR. +.RE + +The \fBshow-overlay\fR command supports the following options: + +.sp +.ne 2 +.na +\fB-f\fR, \fB--fma\fR +.ad +.sp .6 +.RS 4n +Displays information about an overlay device's FMA state. For more +information on the target table, see \fBoverlay\fR(5). +.RE + +.sp +.ne 2 +.na +\fB\fB-o\fR \fIfield\fR[,...], \fB--output\fR=\fIfield\fR\fR +.ad +.sp .6 +.RS 4n +A case-insensitive, comma-separated list of output fields to display. The field +name must be one of the fields listed above, or the special value \fBall\fR, to +display all fields. The fields applicable to the \fB-o\fR option are limited to +those listed under each output mode. For example, if using \fB-L\fR, only the +fields listed under \fB-L\fR, above, can be used with \fB-o\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB-p\fR, \fB--parseable\fR\fR +.ad +.sp .6 +.RS 4n +Display using a stable machine-parseable format. The \fB-o\fR option is +required with \fB-p\fR. See "Parseable Output Format", below. +.RE + +.sp +.ne 2 +.na +\fB-t\fR, \fB--target\fR +.ad +.sp .6 +.RS 4n +Displays information about an overlay device's target table. For more +information on the target table, see \fBoverlay\fR(5). +.RE + +.RE + +.sp +.ne 2 +.na \fB\fBdladm show-usage\fR [\fB-a\fR] \fB-f\fR \fIfilename\fR [\fB-p\fR \fIplotfile\fR \fB-F\fR \fIformat\fR] [\fB-s\fR \fItime\fR] [\fB-e\fR \fItime\fR] [\fIlink\fR]\fR @@ -5480,7 +5900,7 @@ Interface Stability Committed .LP \fBacctadm\fR(1M), \fBautopush\fR(1M), \fBifconfig\fR(1M), \fBipsecconf\fR(1M), \fBndd\fR(1M), \fBpsrset\fR(1M), \fBwpad\fR(1M), \fBzonecfg\fR(1M), -\fBattributes\fR(5), \fBieee802.3\fR(5), \fBdlpi\fR(7P) +\fBattributes\fR(5), \fBieee802.3\fR(5), \fBoverlay\fR(5), \fBdlpi\fR(7P) .SH NOTES .LP The preferred method of referring to an aggregation in the aggregation diff --git a/usr/src/man/man1m/flowadm.1m b/usr/src/man/man1m/flowadm.1m index b12ce6af96..c9d5b846d5 100644 --- a/usr/src/man/man1m/flowadm.1m +++ b/usr/src/man/man1m/flowadm.1m @@ -1,5 +1,6 @@ '\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2011, Joyent, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] @@ -11,14 +12,14 @@ services, containers, and virtual machines .LP .nf \fBflowadm show-flow\fR [\fB-pP\fR] [\fB-S\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [\fB-l\fR \fIlink\fR] - [\fB-o\fR \fIfield\fR[,...]] [\fIflow\fR] + [\fB-o\fR \fIfield\fR[,...]] [\fB-z\fR \fIzonename\fR] [\fIflow\fR] .fi .LP .nf -\fBflowadm add-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-l\fR \fIlink\fR \fB-a\fR \fIattr\fR=\fIvalue\fR[,...] - \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR -\fBflowadm remove-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] {\fB-l\fR \fIlink\fR | \fIflow\fR} +\fBflowadm add-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-l\fR \fIlink\fR + \fB-a\fR \fIattr\fR=\fIvalue\fR[,...] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR +\fBflowadm remove-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] {\fB-l\fR \fIlink\fR | \fIflow\fR} .fi .LP @@ -77,8 +78,7 @@ The following subcommands are supported: .sp .ne 2 .na -\fB\fBflowadm show-flow\fR [\fB-pP\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] -[\fB-o\fR \fIfield\fR[,...]] [\fB-l\fR \fIlink\fR] [\fIflow\fR]\fR +\fB\fBflowadm show-flow\fR [\fB-pP\fR] [\fB-s\fR [\fB-i\fR \fIinterval\fR]] [\fB-o\fR \fIfield\fR[,...]] [\fB-l\fR \fIlink\fR] [\fB-z\fR \fIzonename\fR] [\fIflow\fR]\fR .ad .sp .6 .RS 4n @@ -223,14 +223,22 @@ Display information for all flows on the named link or information for the named flow. .RE +.sp +.ne 2 +.na +\fB\fB-z\fR \fIzonename\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + .RE .sp .ne 2 .na -\fB\fBflowadm add-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-l\fR -\fIlink\fR \fB-a\fR \fIattr\fR=\fIvalue\fR[,...] \fB-p\fR -\fIprop\fR=\fIvalue\fR[,...] \fIflow\fR\fR +\fB\fBflowadm add-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-l\fR \fIlink\fR \fB-a\fR \fIattr\fR=\fIvalue\fR[,...] \fB-p\fR \fIprop\fR=\fIvalue\fR[,...] \fIflow\fR\fR .ad .sp .6 .RS 4n @@ -268,6 +276,16 @@ persistent creation. .sp .ne 2 .na +\fB\fB-z\fR \fIzonename\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + +.sp +.ne 2 +.na \fB\fB-l\fR \fIlink\fR, \fB--link\fR=\fIlink\fR\fR .ad .sp .6 @@ -300,8 +318,7 @@ A comma-separated list of properties to be set to the specified values. .sp .ne 2 .na -\fB\fBflowadm remove-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] \fB-l\fR -{\fIlink\fR | \fIflow\fR}\fR +\fB\fBflowadm remove-flow\fR [\fB-t\fR] [\fB-R\fR \fIroot-dir\fR] [\fB-z\fR \fIzonename\fR] \fB-l\fR {\fIlink\fR | \fIflow\fR}\fR .ad .sp .6 .RS 4n @@ -331,6 +348,16 @@ persistent removal. .sp .ne 2 .na +\fB\fB-z\fR \fIzonename\fR +.ad +.sp .6 +.RS 4n +Operate on a link that has been delegated to the specified zone. +.RE + +.sp +.ne 2 +.na \fB\fB-l\fR \fIlink\fR | \fIflow\fR, \fB--link\fR=\fIlink\fR | \fIflow\fR\fR .ad .sp .6 diff --git a/usr/src/man/man1m/ipf.1m b/usr/src/man/man1m/ipf.1m index 57a3f4bb9a..e61bfba39c 100644 --- a/usr/src/man/man1m/ipf.1m +++ b/usr/src/man/man1m/ipf.1m @@ -2,7 +2,7 @@ .\" To view license terms, attribution, and copyright for IP Filter, the default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Solaris operating environment has been installed anywhere other than the default, modify the given path to access the file at the installed .\" location. .\" Portions Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved. -.\" Portions Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2015, Joyent, Inc. .TH IPF 1M "Oct 7, 2014" .SH NAME ipf \- alter packet filtering lists for IP packet input and output @@ -54,7 +54,7 @@ Configure system and services' firewall policies. See \fBsvc.ipfd\fR(1M) and .TP 3. (Optional) Create a network address translation (NAT) configuration file. -See \fBipnat.conf\fR(4). +See \fBipnat\fR(4). .RE .RS +4 .TP @@ -542,7 +542,7 @@ Interface Stability Committed .SH SEE ALSO .LP \fBipfstat\fR(1M), \fBipmon\fR(1M), \fBipnat\fR(1M), \fBippool\fR(1M), -\fBsvcadm\fR(1M), \fBsvc.ipfd\fR(1M), \fBipf\fR(4), \fBipnat.conf\fR(4), +\fBsvcadm\fR(1M), \fBsvc.ipfd\fR(1M), \fBipf\fR(4), \fBipnat\fR(4), \fBippool\fR(4), \fBattributes\fR(5), \fBipfilter\fR(5), \fBzones(5)\fR .sp .LP diff --git a/usr/src/man/man1m/mount_tmpfs.1m b/usr/src/man/man1m/mount_tmpfs.1m index a4f38d3b1f..7ea64130bd 100644 --- a/usr/src/man/man1m/mount_tmpfs.1m +++ b/usr/src/man/man1m/mount_tmpfs.1m @@ -1,9 +1,10 @@ '\" te .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 2015 Joyent, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH MOUNT_TMPFS 1M "Nov 24, 2003" +.TH MOUNT_TMPFS 1M "Mar 18, 2015" .SH NAME mount_tmpfs \- mount tmpfs file systems .SH SYNOPSIS @@ -13,7 +14,6 @@ mount_tmpfs \- mount tmpfs file systems .fi .SH DESCRIPTION -.sp .LP \fBtmpfs\fR is a memory based file system which uses kernel resources relating to the \fBVM\fR system and page cache as a file system. @@ -26,13 +26,13 @@ remain hidden until the file system is once again unmounted. The attributes (mode, owner, and group) of the root of the \fBtmpfs\fR filesystem are inherited from the underlying \fImount_point\fR, provided that those attributes are determinable. If not, the root's attributes are set to their default -values. +values. The mode may also be overriden by the \fBmode\fR mount option, which +takes precedence if set. .sp .LP The \fIspecial\fR argument is usually specified as \fBswap\fR but is in fact disregarded and assumed to be the virtual memory resources within the system. .SH OPTIONS -.sp .ne 2 .na \fB\fB-o\fR \fIspecific_options\fR\fR @@ -45,13 +45,40 @@ available: .sp .ne 2 .na +\fB\fBremount\fR\fR +.ad +.sp .6 +.RS 19n +Remounts a file system with a new size. A size not explicitly +set with \fBremount\fR reverts to no limit. +.RE + +.sp +.ne 2 +.na +\fBmode=\fIoctalmode\fR\fR +.ad +.RS 19n +The \fImode\fR argument controls the permissions of the \fBtmpfs\fR mount +point. The argument must be an octal number, of the form passed to +\fBchmod\fR(1). Only the access mode, setuid, setgid, and sticky bits (a mask +of \fB07777\fR) may be set. If this option is not provided then the default +mode behaviour, as described above, applies. +.RE + +.sp +.sp +.ne 2 +.na \fBsize=\fIsz\fR\fR .ad .RS 19n The \fIsz\fR argument controls the size of this particular \fBtmpfs\fR file system. If the argument is has a `k' suffix, the number will be interpreted as a number of kilobytes. An `m' suffix will be interpreted as a number of -megabytes. No suffix is interpreted as bytes. In all cases, the actual size of +megabytes. A `g' suffix will be interpreted as a number of gigabytes. A `%' +suffix will be interpreted as a percentage of the swap space available to the +zone. No suffix is interpreted as bytes. In all cases, the actual size of the file system is the number of bytes specified, rounded up to the physical pagesize of the system. .RE @@ -82,7 +109,6 @@ producing the error\f(CWdevice busy\fR. .RE .SH FILES -.sp .ne 2 .na \fB\fB/etc/mnttab\fR\fR @@ -92,13 +118,11 @@ Table of mounted file systems .RE .SH SEE ALSO -.sp .LP \fBmount\fR(1M), \fBmkdir\fR(2), \fBmount\fR(2), \fBopen\fR(2), \fBumount\fR(2), \fBmnttab\fR(4), \fBattributes\fR(5), \fBfsattr\fR(5), \fBtmpfs\fR(7FS) .SH NOTES -.sp .LP If the directory on which a file system is to be mounted is a symbolic link, the file system is mounted on the directory to which the symbolic link refers, diff --git a/usr/src/man/man1m/prstat.1m b/usr/src/man/man1m/prstat.1m index a5f02621cf..08e2ce9907 100644 --- a/usr/src/man/man1m/prstat.1m +++ b/usr/src/man/man1m/prstat.1m @@ -1,6 +1,7 @@ '\" te .\" Copyright (c) 2013 Gary Mills .\" Copyright (c) 2006, 2009 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] @@ -10,10 +11,10 @@ prstat \- report active process statistics .SH SYNOPSIS .LP .nf -\fBprstat\fR [\fB-acHJLmRrtTvWZ\fR] [\fB-d\fR u | d] [\fB-C\fR \fIpsrsetlist\fR] [\fB-h\fR \fIlgrplist\fR] +\fBprstat\fR [\fB-acHJLmRrtTvVWZ\fR] [\fB-d\fR u | d] [\fB-C\fR \fIpsrsetlist\fR] [\fB-h\fR \fIlgrplist\fR] [\fB-j\fR \fIprojlist\fR] [\fB-k\fR \fItasklist\fR] [\fB-n\fR \fIntop\fR[,\fInbottom\fR]] [\fB-p\fR \fIpidlist\fR] [\fB-P\fR \fIcpulist\fR] [\fB-s\fR \fIkey\fR | \fB-S\fR \fIkey\fR ] - [\fB-u\fR \fIeuidlist\fR] [\fB-U\fR \fIuidlist\fR] [\fB-z\fR \fIzoneidlist\fR] + [\fB-u\fR \fIeuidlist\fR] [\fB-U\fR \fIuidlist\fR] [\fB-z\fR \fIzoneidlist\fR] [\fB-Z\fR] [\fIinterval\fR [\fIcount\fR]] .fi @@ -366,6 +367,18 @@ with the \fB-\fR sign. .sp .ne 2 .na +\fB\fB-V\fR\fR +.ad +.sp .6 +.RS 4n +Report accurate aggregated SWAP and RSS values when used with the \fB-J\fR, +\fB-t\fR, \fB-T\fR or \fB-Z\fR options. This uses an accurate, but more expensive, +calculation to determine the aggregated values for the specified grouping. +.RE + +.sp +.ne 2 +.na \fB\fB-W\fR\fR .ad .sp .6 @@ -447,9 +460,11 @@ devices, in kilobytes (\fBK\fR), megabytes (\fBM\fR), or gigabytes (\fBG\fR). .RS 4n The resident set size of the process (\fBRSS\fR), in kilobytes (\fBK\fR), megabytes (\fBM\fR), or gigabytes (\fBG\fR). The RSS value is an estimate -provided by \fBproc\fR(4) that might underestimate the actual resident set -size. Users who want to get more accurate usage information for capacity -planning should use the \fB-x\fR option to \fBpmap\fR(1) instead. +provided by \fBproc\fR(4) that might underestimate the actual +per-process resident set size and usually overestimates the aggregated +resident set size. Users who want to get more accurate usage information for +capacity planning should use either the \fB-V\fR option or, for per-process +results, the \fB-x\fR option to \fBpmap\fR(1) instead. .RE .sp diff --git a/usr/src/man/man1m/prtconf.1m b/usr/src/man/man1m/prtconf.1m index d8ad9e72ba..ff62a01992 100644 --- a/usr/src/man/man1m/prtconf.1m +++ b/usr/src/man/man1m/prtconf.1m @@ -10,7 +10,7 @@ prtconf \- print system configuration .SH SYNOPSIS .LP .nf -\fB/usr/sbin/prtconf\fR [\fB-V\fR] | [\fB-F\fR] | [\fB-x\fR] | [\fB-bpv\fR] | [\fB-acdDPv\fR] +\fB/usr/sbin/prtconf\fR [\fB-V\fR] | [\fB-F\fR] | [\fB-m\fr] | [\fB-x\fR] | [\fB-bpv\fR] | [\fB-acdDPv\fR] [\fIdev_path\fR] .fi @@ -100,6 +100,16 @@ console frame buffer on a SUNW,Ultra-30 is \fBffb\fR, the command returns: .sp .ne 2 .na +\fB\fB-m\fR\fR +.ad +.RS 6n +Displays the amount system memory in megabytes. +This flag must be used by itself. +.RE + +.sp +.ne 2 +.na \fB\fB-p\fR\fR .ad .RS 6n diff --git a/usr/src/man/man1m/reboot.1m b/usr/src/man/man1m/reboot.1m index 1ff92b6f33..8eadedf18d 100644 --- a/usr/src/man/man1m/reboot.1m +++ b/usr/src/man/man1m/reboot.1m @@ -144,8 +144,7 @@ This option is currently available only on x86 systems. The \fB-p\fR and .ad .sp .6 .RS 4n -Quick. Reboot quickly and ungracefully, without shutting down running processes -first. +Quick. Reboot quickly without halting running zones first. .RE .SH OPERANDS diff --git a/usr/src/man/man1m/snoop.1m b/usr/src/man/man1m/snoop.1m index ca969e22b4..4184c66e10 100644 --- a/usr/src/man/man1m/snoop.1m +++ b/usr/src/man/man1m/snoop.1m @@ -1,9 +1,10 @@ '\" te .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH SNOOP 1M "Feb 18, 2009" +.TH SNOOP 1M "Feb 24, 2014" .SH NAME snoop \- capture and inspect network packets .SH SYNOPSIS @@ -12,7 +13,7 @@ snoop \- capture and inspect network packets \fBsnoop\fR [\fB-aqrCDINPSvV\fR] [\fB-t\fR [r | a | d]] [\fB-c\fR \fImaxcount\fR] [\fB-d\fR \fIdevice\fR] [\fB-i\fR \fIfilename\fR] [\fB-n\fR \fIfilename\fR] [\fB-o\fR \fIfilename\fR] [\fB-p\fR \fIfirst\fR [, \fIlast\fR]] [\fB-s\fR \fIsnaplen\fR] [\fB-x\fR \fIoffset\fR [, \fIlength\fR]] - [\fIexpression\fR] + [\fB-z\fR \fIzonename\fR] [\fIexpression\fR] .fi .SH DESCRIPTION @@ -298,6 +299,22 @@ the whole packet, use an \fIoffset\fR of 0. If a \fIlength\fR value is not provided, the rest of the packet is displayed. .RE +.sp +.ne 2 +.na +.BI -z zonename +.ad +.sp .6 +.RS 4n +Open an earlier datalink specified via +.B -d +or +.B -I +in the specified zone \fIzonename\fR. +This option is only meaningful in the global zone and +allows the global zone to inspect datalinks of non-global zones. +.RE + .SH OPERANDS .sp .ne 2 diff --git a/usr/src/man/man1m/svc.startd.1m b/usr/src/man/man1m/svc.startd.1m index 7c80c35e23..103c6b5fec 100644 --- a/usr/src/man/man1m/svc.startd.1m +++ b/usr/src/man/man1m/svc.startd.1m @@ -4,7 +4,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH SVC.STARTD 1M "Mar 18, 2011" +.TH SVC.STARTD 1M "Aug 23, 2012" .SH NAME svc.startd \- Service Management Facility master restarter .SH SYNOPSIS @@ -372,10 +372,13 @@ properties listed below in the \fBstartd\fR property group. .RS 4n The \fBcritical_failure_count\fR and \fBcritical_failure_period\fR properties together specify the maximum number of service failures allowed in a given -time interval before \fBsvc.startd\fR transitions the service to maintenance. +number of seconds before \fBsvc.startd\fR transitions the service to +maintenance. If the number of failures exceeds \fBcritical_failure_count\fR in any period of \fBcritical_failure_period\fR seconds, \fBsvc.startd\fR will transition the -service to maintenance. +service to maintenance. The \fBcritical_failure_count\fR value is limited +to the range 1-10 and defaults to 10. The \fBcritical_failure_period\fR +defaults to 600 seconds. .RE .sp diff --git a/usr/src/man/man1m/tunefs.1m b/usr/src/man/man1m/tunefs.1m index 7f522f43fa..0b849f2dd7 100644 --- a/usr/src/man/man1m/tunefs.1m +++ b/usr/src/man/man1m/tunefs.1m @@ -3,7 +3,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TUNEFS 1M "Dec 5, 2003" +.TH TUNEFS 1M "Sep 19, 2013" .SH NAME tunefs \- tune an existing UFS file system .SH SYNOPSIS @@ -120,3 +120,9 @@ encountering files greater than or equal to 2 Gbyte ( 2^31 bytes). .sp .LP \fBmkfs_ufs\fR(1M), \fBnewfs\fR(1M), \fBattributes\fR(5), \fBlargefile\fR(5) + +.\" Take this out and a Unix Demon will dog your steps from now until +.\" the time_t's wrap around. +.SH BUGS +.sp +You can tune a file system, but you can't tune a fish. diff --git a/usr/src/man/man1m/vfsstat.1m b/usr/src/man/man1m/vfsstat.1m new file mode 100644 index 0000000000..aef8431a09 --- /dev/null +++ b/usr/src/man/man1m/vfsstat.1m @@ -0,0 +1,213 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" Copyright 2014 Joyent, Inc. All rights reserved. +.\" +.TH "VFSSTAT" "1m" "May 1, 2014" "" "" +. +.SH "NAME" +\fBvfsstat\fR \-\- Report VFS read and write activity +. +.SH "SYNOPSIS" +. +.nf +vfsstat [\-hIMrzZ] [interval [count]] +. +.fi +. +.SH "DESCRIPTION" +The vfsstat utility reports a summary of VFS read and write +activity per zone\. It first prints all activity since boot, then +reports activity over a specified interval\. +. +.P +When run from a non\-global zone (NGZ), only activity from that NGZ +can be observed\. When run from a the global zone (GZ), activity +from the GZ and all other NGZs can be observed\. +. +.P +This tool is convenient for examining I/O performance as +experienced by a particular zone or application\. Other tools +which examine solely disk I/O do not report reads and writes which +may use the filesystem\'s cache\. Since all read and write system +calls pass through the VFS layer, even those which are satisfied +by the filesystem cache, this tool is a useful starting point when +looking at a potential I/O performance problem\. The vfsstat +command reports the most accurate reading of I/O performance as +experienced by an application or zone\. +. +.P +One additional feature is that ZFS zvol performance is also reported +by this tool, even though zvol I/O does not go through the VFS +layer\. This is done so that this single tool can be used to monitor +I/O performance and because its not unreasonable to think of zvols +as being included along with other ZFS filesystems\. +. +.P +The calculations and output fields emulate those from iostat(1m) +as closely as possible\. When only one zone is actively performing +disk I/O, the results from iostat(1m) in the global zone and +vfsstat in the local zone should be almost identical\. Note that +many VFS read operations may be handled by the filesystem cache, +so vfsstat and iostat(1m) will be similar only when most +operations require a disk access\. +. +.P +As with iostat(1m), a result of 100% for VFS read and write +utilization does not mean that the VFS layer is fully saturated\. +Instead, that measurement just shows that at least one operation +was pending over the last interval of time examined\. Since the +VFS layer can process more than one operation concurrently, this +measurement will frequently be 100% but the VFS layer can still +accept additional requests\. +. +.SH "OUTPUT" +The vfsstat utility reports the following information: +. +.IP "" 4 +. +.nf +r/s +.RS +reads per second +.RE + +w/s +.RS +writes per second +.RE + +kr/s +.RS +kilobytes read per second +.RE + +kw/s +.RS +kilobytes written per second +.RE + +ractv +.RS +average number of read operations actively being serviced by the VFS layer +.RE + +wactv +.RS +average number of write operations actively being serviced by the VFS layer +.RE + +read_t +.RS +average VFS read latency, in microseconds +.RE + +writ_t +.RS +average VFS write latency, in microseconds +.RE + +%r +.RS +percent of time there is a VFS read operation pending +.RE + +%w +.RS +percent of time there is a VFS write operation pending +.RE + +d/s +.RS +VFS operations per second delayed by the ZFS I/O throttle +.RE + +del_t +.RS +average ZFS I/O throttle delay, in microseconds +.RE +. +.fi +. +.IP "" 0 +. +.SH "OPTIONS" +The following options are supported: +. +.P +\-h +.RS +Show help message and exit +.RE +. +.P +\-I +.RS +Print results per interval, rather than per second (where applicable) +.RE +. +.P +\-M +.RS +Print results in MB/s instead of KB/s +.RE +. +.P +\-r +.RS +Show results in a comma\-separated format +.RE +. +.P +\-z +.RS +Hide zones with no VFS activity +.RE +. +.P +\-Z +.RS +Print results for all zones, not just the current zone +.RE +. +.SH "OPERANDS" +interval +. +.P +Specifies the length in seconds to pause between each interval +report\. If not specified, vfsstat will print a summary since boot +and exit\. +. +.P +count +. +.P +Specifies the number of intervals to report\. Defaults to +unlimited if not specified\. +. +.SH "SEE ALSO" +. +.nf +iostat(1m), ziostat(1m), mpstat(1m) +. +.fi +. +.SH "NOTES" +This command does not examine readdir or any other VFS operations, +only read and write operations\. +. +.P +This command does not look at network I/O, only I/O operations to +or from a file\. +. +.P +The output format from vfsstat may change over time; use the +comma\-separated output for a stable output format\. diff --git a/usr/src/man/man1m/vndadm.1m b/usr/src/man/man1m/vndadm.1m new file mode 100644 index 0000000000..253518a88a --- /dev/null +++ b/usr/src/man/man1m/vndadm.1m @@ -0,0 +1,651 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VNDADM 1M "Mar 06, 2014" +.SH NAME +vndadm \- administer vnd devices + +.SH SYNOPSIS + +.nf +vndadm create [-z zonename] [-l datalink] device +vndadm destroy [-z zonename] device... +vndadm list [-p] [-d delim] [-o field,...] [-z zonename] [device]... +vndadm get [-p] [-d delim] [-z zonename] device [prop]... +vndadm set [-z zonename] device prop=val... +.fi + +.SH DESCRIPTION +.sp +.LP +The vndadm command is used to administer vnd devices. A vnd device is +similar to an IP network interface, except that the vnd device operates +at layer two. A vnd device is created over a data link (see dladm(1M)) +and its address is that of the underlying data link. For ethernet based +devices, that address would be the MAC address of the data link. vnd +devices are character devices which may be used to send and receive +layer two packets. When reading or writing to a vnd device, the full +frame must be present. This is useful for working with virtual machines, +or other environments where you need to manipulate the entire layer two +frame. + +.sp +.LP +Every command takes a device as an argument. To specify a vnd device, +you just use the name of the device. Devices are scoped to zones. If no +zone is specified, the current zone is assumed. A device name can be any +series of alphanumeric ascii characters which typically match the name +of the underlying data link. A given vnd device name must be unique in a +given zone, but the same name can be used across zones. +.sp +.SH OPTIONS +.sp +.LP +All vndadm subcommands have the following common option: +.sp +.ne 2 +.na +-z zonename +.ad +.sp .6 +.RS 4n +Operate in the context of the specified zone. When creating a vnd +device, the named device is created in the specified zone. All other +operations scope the device lookup to the specified zone. If the user is +not in the global zone, the use of -z will not work. + +.sp +.LP +When -z is used and multiple devices are specified, then +the use of -z applies to all of the devices. +.RE + +.SH SUBCOMMANDS +.sp +.ne 2 +.na +vndadm create [-z zonename] [-l datalink] device +.ad +.sp +.RS 4n +Creates a vnd device with the specified name device. If -l datalink is +not specified, it is assumed that the data link and the device share the +same name. The created device will exist for as long as the zone exists +or until a call to vndadm destroy. vnd devices do not persist across +system reboots. Note, if an IP interface or another libdlpi(3LIB) +consumer is already using the data link, then vnd will fail. + +.sp +The maximum length of the name of device is 31 characters. The allowed +set of characters is alphanumberic characters, ':', \'-', and \'_'. The +names 'zone' and 'ctl' are reserved and may not be used. + +.sp +.ne 2 +.na +-l datalink +.ad +.sp .6 +.RS 4n +Specifies the name of the data link to create the device over. This +allows the vnd device name to be different from the data link's name. +.RE +.sp +.ne 2 +.na +-z zonename +.ad +.sp .6 +.RS 4n +See OPTIONS above. +.RE + +.RE + +.sp +.ne 2 +.na +vndadm destroy [-z zonename] device... +.ad +.sp +.RS 4n +Destroys the specified device. The destruction is analogous to +unlink(2). If the device is still open and used by applications, the +device will continue to exist, but it will no longer be accessible by +the name device. +.sp +.ne 2 +.na +-z zonename +.ad +.sp .6 +.RS 4n +See OPTIONS above. +.RE +.RE + +.sp +.ne 2 +.na +vndadm list [-p] [-d delim] [-o field,...] [-z zonename] [device]... +.ad +.sp +.RS 4n +Lists active vnd devices. By default, vnadm list lists all devices in +every zone that the caller is allowed to see; the current zone if in the +non-global zone, and all zones in the global zone. If device is +specified one or more times, then output will be limited to the +specified devices. +.sp +.ne 2 +.na +-o field[,...] +.ad +.sp .6 +.RS 4n +A case-insensitive, comma-separated list of output fields. When -o is +not used, all of the fields listed below are shown. The field name must +be one of the following fields: + +.sp +.ne 2 +.na +NAME +.ad +.sp .6 +.RS 4n +The name of the vnd device. +.RE + +.sp +.ne 2 +.na +DATALINK +.ad +.sp .6 +.RS 4n +The name of the data link the vnd device was created over. +.RE + +.sp +.ne 2 +.na +ZONENAME +.ad +.sp .6 +.RS 4n +The name of the zone that the vnd device exists in. +.RE +.RE + +.sp +.ne 2 +.na +-p +.ad +.sp .6 +.RS 4n +Display the output in a stable machine parseable format. The -o option +is required with the -p option. See "Parseable Output Format" below. +.RE + +.sp +.ne 2 +.na +-d delim +.ad +.sp .6 +.RS 4n +Change the delimiter used in conjunction with generating parseable +output. This option may only be specified when -p is also specified. +.RE + +.sp +.ne 2 +.na +-z zonename +.ad +.sp .6 +.RS 4n +See OPTIONS above. +.RE + +.RE + + +.sp +.ne 2 +.na +vndadm get [-p] [-d delim] [-z zonename] device [prop]... +.ad +.sp +.RS 4n +Displays the properties for the specified device. By default, all +properties of a given device are displayed. If prop is specified one or +more times, then only the specified properties will be displayed for +device. For a list of properties, see the section "Properties" below. +The property output consists of the following four columns: +.sp +.ne 2 +.na +LINK +.ad +.sp .6 +.RS 4n +The name of the device +.RE + +.sp +.ne 2 +.na +PROPERTY +.ad +.sp .6 +.RS 4n +The name of the property. Note that some properties that are private to +the implementation may be displayed. Those properties begin with a +leading underscore. +.RE + +.sp +.ne 2 +.na +PERM +.ad +.sp .6 +.RS 4n +Describes whether the property is read-only or +if it is read-write. This field does not +indicate if the current user has permission, but +lists permissions for a privileged user. +.RE + +.sp +.ne 2 +.na +VALUE +.ad +.sp .6 +.RS 4n +The value of the property. +.RE + +.sp +.ne 2 +.na +-p +.ad +.sp .6 +.RS 4n +Display the output in a stable machine parseable format. See "Parseable +Output Format" below. +.RE + +.sp +.ne 2 +.na +-d delim +.ad +.sp .6 +.RS 4n +Change the delimiter used in conjunction with generating parseable +output. This option may only be specified when -p is also specified. +.RE + +.sp +.ne 2 +.na +-z zonename +.ad +.sp .6 +.RS 4n +See OPTIONS above. +.RE +.RE + +.sp +.ne 2 +.na +vndadm set [-z zonename] device prop=val... +.ad +.sp +.RS 4n +Sets properties on the named device. Setting a property takes effect for +all operations on the device, after the program returns. Multiple +properties can be set at once; however, properties are applied one at a +time to the device. Property names and values must be separated with an +equals sign. Additional property and value pairs should be separated by +white space. For a list of properties, see the section "Properties" +below. + +.sp +.ne 2 +.na +-z zonename +.ad +.sp .6 +.RS 4n +See OPTIONS above. +.RE +.RE + +.SS Parseable Output Format +.sp +.LP +The default output for parseable data is to be separated with a single +ascii space character. The delimiter may be changed with the -d +option. When parseable output is requested, no numbers that represent +sizes will be displayed in human readable form, they will be fully +expanded. eg. the number 42K will instead be 43008. + +.SS Properties +.sp +.LP +The following are supported and stable properties. Note that any +properties that starts with a leading underscore are not a stable +property and may be removed at any time. + +.sp +.ne 2 +.na +rxbuf +.ad +.sp .6 +.RS 4n +A read/write property that controls the size of the receive buffer for +the device. All received data enters the receive buffer until a consumer +consumes it. If adding a received frame would exceed the size of the +receive buffer, then that frame will be dropped. The maximum size of the +buffer is limited by the 'maxsize' property. The minimum size of the +buffer is the value of the 'maxtu' property. The property's value may be +anything between that maximum and minimum. When setting this property, +standard size suffixes such as 'K' and 'M' may be used. +.RE + +.sp +.ne 2 +.na +txbuf +.ad +.sp .6 +.RS 4n +A read/write property that controls the size of the transmit buffer. All +in-flight transmitted data must be able to fit into the transmit buffer +to account for potential flow control events. If there is not enough +space in the transmit buffer, transmit related I/O operations will +either block or fail based on whether the file has been put into +non-blocking mode by setting O_NONBLOCK or O_NDELAY with fcntl(2). The +maximum size of the buffer is limited by the 'maxsize' property. The +minimum size of the buffer is the value of the 'maxtu' property. The +property's value may be anything between that maximum and minimum. When +setting this property, standard size suffixes such as 'K' and 'M' may be +used. + +.RE + +.sp +.ne 2 +.na +maxsize +.ad +.sp .6 +.RS 4n +A read-only property that describes the maximum size of buffers in the +system. Properties such as rxbuf and txbuf cannot be set beyond this. +.RE + +.sp +.ne 2 +.na +mintu +.ad +.sp .6 +.RS 4n +A read-only property that describes the minimum size of a frame +transmitted to the underlying data link. Note that the minimum listed +here may be less than the size of a valid layer two frame and therefore +may be dropped. A frame smaller than this value will be rejected by vnd. +.RE + +.sp +.ne 2 +.na +maxtu +.ad +.sp .6 +.RS 4n +A read-only property that describes the maximum size of a frame +transmitted to the underlying data link. A frame larger than this value +will be rejected by vnd. +.RE + +.SH EXAMPLES +.LP +Example 1 Creating a vnd device +.sp +.LP +To create a vnd device over the VNIC named net0, enter the following +command: + +.sp +.in +2 +.nf +# vndadm create net0 +.fi +.in -2 +.sp + +.LP +Example 2 Creating a vnd device in another zone +.sp +.LP + +To create a vnd device over the VNIC named net1 in the zone +1b7155a4-aef9-e7f0-d33c-9705e4b8b525, enter the following command: + +.sp +.in +2 +.nf +# vndadm create -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 net1 +.fi +.in -2 +.sp + +.LP +Example 3 Destroying a vnd device +.sp +.LP + +To destroy the vnd device named net0, enter the following command: + +.sp +.in +2 +.nf +# vndadm destroy net0 +.fi +.in -2 +.sp + +.LP +Example 4 Destroying a vnd device in another zone +.sp +.LP + +To destroy the vnd device named net1 in the zone +1b7155a4-aef9-e7f0-d33c-9705e4b8b525, enter the following command: + +.sp +.in +2 +.nf +# vndadm destroy -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 net1 +.fi +.in -2 +.sp + +.LP +Example 5 List all vnd devices +.sp +.LP + +To list all devices, run the following command: + +.sp +.in +2 +.nf +# vndadm list +NAME DATALINK ZONENAME +net0 net0 global +net0 net0 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 +.fi +.in -2 +.sp + +.LP +Example 6 Listing devices in a specific zone +.sp +.LP + +To list devices in a specific zone, run the following command: + +.sp +.in +2 +.nf +# vndadm list -z 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 + +NAME DATALINK ZONENAME +net0 net0 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 +.fi +.in -2 +.sp + +.LP +Example 7 List all devices in a parseable format +.sp +.LP + +To list all devices in a parseable format with the delimiter of ':', run +the following command: + +.sp +.in +2 +.nf +# vndadm list -p -d: -o name,datalink,zone +net0:net0:global +net0:net0:1b7155a4-aef9-e7f0-d33c-9705e4b8b525 +.fi +.in -2 +.sp + +.LP +Example 8 Retrieving all properties for a device +.sp +.LP + +To retrieve all of the properties for the vnd device foo0, run the +following command: + +.sp +.in +2 +.nf +# vndadm get foo0 +LINK PROPERTY PERM VALUE +foo0 rxbuf rw 65536 +foo0 txbuf rw 65536 +foo0 maxsize r- 4194304 +foo0 mintu r- 0 +foo0 maxtu r- 1518 +foo0 _nflush rw 10 +foo0 _burstsz rw 10 +.fi +.in -2 +.sp + +.LP +Example 9 Retrieving specific properties for a device +.sp +.LP + +To retrieve just the rxbuf and txbuf properties for the vnd device foo0, +run the following command: + +.sp +.in +2 +.nf +# vndadm get foo0 rxbuf txbuf +LINK PROPERTY PERM VALUE +foo0 rxbuf rw 65536 +foo0 txbuf rw 65536 +.fi +.in -2 +.sp + +.LP +Example 10 Retrieving properties for a device in a parseable format +.sp +.LP + +To retrieve all properties for the vnd device foo0 in a parseable +format, run the following command: + +.sp +.in +2 +.nf +# vndadm get -p foo0 +foo0 rxbuf rw 65536 +foo0 txbuf rw 65536 +foo0 maxsize r- 4194304 +foo0 mintu r- 0 +foo0 maxtu r- 1518 +foo0 _nflush rw 10 +foo0 _burstsz rw 10 +.fi +.in -2 +.sp + +.LP +Example 11 Setting a property on a device +.sp +.LP + +To set the receive buffer size to one megabyte on the device foo0, run +the following command: + +.sp +.in +2 +.nf +# vndadm set foo0 rxbuf=1M +.fi +.in -2 +.sp + +.LP +Example 12 Setting multiple properties on a device +.sp +.LP + +To set the transmit buffer to 300 Kb and the receive buffer to 1 Mb, run +the following command: + +.sp +.in +2 +.nf +# vndadm set foo0 rxbuf=300K txbuf=1M +.fi +.in -2 +.sp + +.SH SEE ALSO + +dladm(1M), ipadm(1M), fcntl(2), fcntl.h(3HEAD), libvnd(3LIB), +vndstat(1M), vnd(7D) diff --git a/usr/src/man/man1m/vndstat.1m b/usr/src/man/man1m/vndstat.1m new file mode 100644 index 0000000000..a7f843e228 --- /dev/null +++ b/usr/src/man/man1m/vndstat.1m @@ -0,0 +1,163 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VNDSTAT 1M "Mar 06, 2014" +.SH NAME +vndstat \- report vnd activity + +.SH SYNOPSIS + +vndstat [interval [count]] + +.SH DESCRIPTION +.sp +.LP +The vndstat command reports a summary of per-device vnd +activity. Once per interval it prints a table of statistics per +device. In the global zone, vndstat reports on all devices in the +system. From the non-global zone, it only reports on devices that are +present in that zone. vndstat reports on all vnd devices +that exist, including anonymous devices which are not linked into the +file system. +.sp +.LP +The vndstat command's output includes the following information: +.sp +.ne 2 +.na +.B name +.ad +.RS 14n +The name of the device, if bound. If a given vnd device is not +bound into the file system, hence considered anonymous, then there will +be no name for the device. +.RE + +.sp +.ne 2 +.na +.B rx B/s +.ad +.RS 14n +The number of bytes received by the device during interval. +.RE + +.sp +.ne 2 +.na +.B tx B/s +.ad +.RS 14n +The number of bytes transmitted by the device during interval. +.RE + +.sp +.ne 2 +.na +.B drops +.ad +.RS 14n +The number of packets and messages which have been dropped. This +includes all drops due to insufficient buffer space, IP hooks, and +unknown or malformed DLPI messages. +.RE + +.sp +.ne 2 +.na +.B txfc +.ad +.RS 14n +The number of flow control events that have occurred. A flow control +event occurs when the layers below vnd request that all transmits +be paused until a future call resumes the flow. This statistic is +incremented when the flow is resumed. It is not incremented when it is +first paused. +.RE + +.sp +.ne 2 +.na +.B zone +.ad +.RS 14n +The name of the zone the device is located in. +.RE + +.SH OPTIONS + +.sp +.ne 2 +.na +interval +.ad +.RS 13n +Report once each interval seconds. interval may not be +fractional. +.RE + +.sp +.ne 2 +.na +count +.ad +.RS 13n +Only print count reports, then exit. +.RE +.sp +.LP +When no arguments are given to vndstat, it will always print at an +interval of one second. Reports will continue until vndstat +is terminated. + +.SH EXAMPLES +.LP +Example 1 Print five seconds of data + +.sp +.in +2 +.nf +example% vndstat 1 5 + name | rx B/s | tx B/s | drops txfc | zone + net0 | 1.45MB/s | 14.1KB/s | 0 0 | 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 + net0 | 3.50MB/s | 19.5KB/s | 0 0 | 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 + net0 | 2.83MB/s | 30.8KB/s | 0 0 | 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 + net0 | 3.08MB/s | 30.6KB/s | 0 0 | 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 + net0 | 3.21MB/s | 30.6KB/s | 0 0 | 1b7155a4-aef9-e7f0-d33c-9705e4b8b525 +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability See below. +.TE + +.sp +.LP +Invocation is evolving. Human readable output is unstable. +.SH SEE ALSO + +dlstat(1M), nicstat(1M), vndadm(1M), vnd(7M) diff --git a/usr/src/man/man1m/zfs.1m b/usr/src/man/man1m/zfs.1m index 1e19be84f6..6ccfa39f86 100644 --- a/usr/src/man/man1m/zfs.1m +++ b/usr/src/man/man1m/zfs.1m @@ -23,7 +23,7 @@ .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org> .\" Copyright (c) 2011, 2014 by Delphix. All rights reserved. .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. -.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" Copyright (c) 2015, Joyent, Inc. All rights reserved. .\" Copyright (c) 2014 by Adam Stevko. All rights reserved. .\" Copyright 2015 Nexenta Systems, Inc. All Rights Reserved. .\" diff --git a/usr/src/man/man1m/zoneadm.1m b/usr/src/man/man1m/zoneadm.1m index 6006e53b65..f7aafb809c 100644 --- a/usr/src/man/man1m/zoneadm.1m +++ b/usr/src/man/man1m/zoneadm.1m @@ -1,6 +1,7 @@ '\" te .\" Copyright 2014 Nexenta Systems, Inc. All rights reserved. .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2011 Joyent, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] @@ -128,12 +129,14 @@ Use the following command to attach a zone: .sp .ne 2 .na -\fB\fBboot\fR [\fB--\fR \fIboot_options\fR]\fR +\fB\fBboot\fR [\fB-X\fR] [\fB--\fR \fIboot_options\fR]\fR .ad .sp .6 .RS 4n Boot (or activate) the specified zones. .sp +The \fI-X\fR option enables debug for the zone's brand while booting. +.sp The following \fIboot_options\fR are supported: .sp .ne 2 @@ -248,12 +251,25 @@ The source zone must be halted before this subcommand can be used. .sp .ne 2 .na -\fB\fBhalt\fR\fR +\fB\fBhalt [\fB-X\fR]\fR\fR .ad .sp .6 .RS 4n Halt the specified zones. \fBhalt\fR bypasses running the shutdown scripts inside the zone. It also removes run time resources of the zone. +.sp +The \fI-X\fR option enables debug for the zone's brand while halting. +.sp +Use: +.sp +.in +2 +.nf +zlogin \fIzone\fR shutdown +.fi +.in -2 +.sp + +to cleanly shutdown the zone by running the shutdown scripts. .RE .sp @@ -403,24 +419,28 @@ and normal restrictions for \fIzonepath\fR apply. .sp .ne 2 .na -\fB\fBready\fR\fR +\fB\fBready [\fB-X\fR]\fR\fR .ad .sp .6 .RS 4n Prepares a zone for running applications but does not start any user processes in the zone. +.sp +The \fI-X\fR option enables debug for the zone's brand while readying. .RE .sp .ne 2 .na -\fB\fBreboot\fR\ [\fB--\fR \fIboot_options\fR]]\fR +\fB\fBreboot\fR\ [\fB-X\fR] [\fB--\fR \fIboot_options\fR]]\fR .ad .sp .6 .RS 4n Restart the zones. This is equivalent to a \fBhalt\fR \fBboot\fR sequence. This subcommand fails if the specified zones are not active. See \fIboot\fR subcommand for the boot options. +.sp +The \fI-X\fR option enables debug for the zone's brand while rebooting. .RE .sp diff --git a/usr/src/man/man1m/zonecfg.1m b/usr/src/man/man1m/zonecfg.1m index f7a491ceee..c7d1ace8e5 100644 --- a/usr/src/man/man1m/zonecfg.1m +++ b/usr/src/man/man1m/zonecfg.1m @@ -10,17 +10,17 @@ zonecfg \- set up zone configuration .SH SYNOPSIS .LP .nf -\fBzonecfg\fR \fB-z\fR \fIzonename\fR +\fBzonecfg\fR {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR} .fi .LP .nf -\fBzonecfg\fR \fB-z\fR \fIzonename\fR \fIsubcommand\fR +\fBzonecfg\fR {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR} \fIsubcommand\fR .fi .LP .nf -\fBzonecfg\fR \fB-z\fR \fIzonename\fR \fB-f\fR \fIcommand_file\fR +\fBzonecfg\fR {\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR} \fB-f\fR \fIcommand_file\fR .fi .LP @@ -43,7 +43,8 @@ The following synopsis of the \fBzonecfg\fR command is for interactive usage: .sp .in +2 .nf -zonecfg \fB-z\fR \fIzonename subcommand\fR +{\fB-z\fR \fIzonename\fR | \fB-u\fR \fIuuid\fR} +zonecfg {\fB-z\fR \fIzonename | \fB-u\fR \fIuuid} subcommand\fR .fi .in -2 .sp @@ -337,6 +338,16 @@ The following properties are supported: .sp .ne 2 .na +\fB(global)\fR +.ad +.sp .6 +.RS 4n +\fBzfs-io-priority\fR +.RE + +.sp +.ne 2 +.na \fB\fBfs\fR\fR .ad .sp .6 @@ -351,7 +362,7 @@ The following properties are supported: .ad .sp .6 .RS 4n -\fBaddress\fR, \fBphysical\fR, \fBdefrouter\fR +\fBaddress\fR, \fBallowed-address\fR, \fBdefrouter\fR, \fBglobal-nic\fR, \fBmac-addr\fR, \fBphysical\fR, \fBproperty\fR, \fBvlan-id\fR .RE .sp @@ -614,7 +625,17 @@ Values needed to determine how, where, and so forth to mount file systems. See .sp .ne 2 .na -\fB\fBnet\fR: address, physical, defrouter\fR +\fB\fBinherit-pkg-dir\fR: dir\fR +.ad +.sp .6 +.RS 4n +The directory path. +.RE + +.sp +.ne 2 +.na +\fB\fBnet\fR: address, allowed-address, defrouter, global-nic, mac-addr, physical, property, vlan-id\fR .ad .sp .6 .RS 4n @@ -653,6 +674,10 @@ zone. However, if the interface is not used by the global zone, it should be configured \fBdown\fR in the global zone, and the default router for the interface should be specified here. .sp +The global-nic is used for exclusive stack zones which will use a VNIC on-demand. When the zone boots, a VNIC named using the physical property will be created on the global NIC. If provided, the mac-addr and vlan-id will be set on this VNIC. +.sp +The \fBproperty\fR setting is a resource which can be used to set arbitrary name/value pairs on the network. These name/value pairs are made available to the zone's brand, which can use them as needed to set up the network interface. +.sp For an exclusive-IP zone, the physical property must be set and the address and default router properties cannot be set. .RE @@ -884,6 +909,16 @@ is not supported. .RE .sp +.ne 2 +.na +\fBglobal: \fBzfs-io-priority\fR\fR +.ad +.sp .6 +.RS 4n +Specifies a priority for this zone's ZFS I/O. The priority is used by the ZFS I/O scheduler as in input to determine how to schedule I/O across zones. By default all zones have a priority of 1. The value can be increased for zones whose I/O is more critical. This property is the preferred way to set the \fBzone.zfs-io-priority\fR rctl. +.RE + +.sp .LP The following table summarizes resources, property-names, and types: .sp @@ -906,13 +941,22 @@ resource property-name type (global) max-shm-ids simple (global) max-shm-memory simple (global) scheduling-class simple +(global) zfs-io-priority simple fs dir simple special simple raw simple type simple options list of simple net address simple + allowed-address simple + defrouter simple + global-nic simple + mac-addr simple physical simple + property list of complex + name simple + value simple + vlan-id simple device match simple rctl name simple value list of complex @@ -1125,6 +1169,16 @@ name \fBglobal\fR and all names beginning with \fBSUNW\fR are reserved and cannot be used. .RE +.sp +.ne 2 +.na +\fB\fB-u\fR \fIuuid\fR\fR +.ad +.sp .6 +.RS 4n +Specify the uuid of a zone instead of the Zone name. +.RE + .SH SUBCOMMANDS .sp .LP @@ -1215,8 +1269,7 @@ correct to be committed, this operation automatically does a verify. .sp .ne 2 .na -\fB\fBcreate [\fR\fB-F\fR\fB] [\fR \fB-a\fR \fIpath\fR |\fB-b\fR \fB|\fR -\fB-t\fR \fItemplate\fR\fB]\fR\fR +\fB\fBcreate [\fR\fB-F\fR\fB] [\fR \fB-a\fR \fIpath\fR |\fB-b\fR \fB|\fR \fB-t\fR \fItemplate\fR\fB] [\fR\fB-X\fR\fB]\fR\fR .ad .sp .6 .RS 4n @@ -1238,6 +1291,8 @@ configured, it should be installed using the "\fBzoneadm attach\fR" command .sp Use the \fB-b\fR option to create a blank configuration. Without arguments, \fBcreate\fR applies the Sun default settings. +.sp +Use the \fB-X\fR option to facilitate creating a zone whose XML definition already exists on the host. The zone will be atomically added to the zone index file. .RE .sp @@ -1314,18 +1369,21 @@ which is currently being added or modified. .sp .ne 2 .na -\fB\fBremove\fR \fIresource-type\fR\fB{\fR\fIproperty-name\fR\fB=\fR\fIproperty --value\fR\fB}\fR(global scope)\fR +\fB\fBremove\fR [\fR\fB-F\fR\fB] \fIresource-type\fR\fB [\fR\fIproperty-name\fR\fB=\fR\fIproperty-value\fR\fB]* \fR(global scope)\fR +.br +\fB\fBremove\fR \fR\fIproperty-name\fR\fB \fR\fIproperty-value\fR\fB \fR(resource scope)\fR .ad .sp .6 .RS 4n In the global scope, removes the specified resource. The \fB[]\fR syntax means -0 or more of whatever is inside the square braces. If you want only to remove a +0 or more property name-value pairs. If you want to only remove a single instance of the resource, you must specify enough property name-value pairs for the resource to be uniquely identified. If no property name-value pairs are specified, all instances will be removed. If there is more than one -pair is specified, a confirmation is required, unless you use the \fB-F\fR -option. +pair specified, a confirmation is required, unless you use the \fB-F\fR +option. Likewise, the \fB-F\fR option can be used to remove a resource that +does not exist (that is, no error will occur). In the resource scope, remove +the specified name-value pair. .RE .sp diff --git a/usr/src/man/man1m/zpool.1m b/usr/src/man/man1m/zpool.1m index fbfd393579..e14a72b7e3 100644 --- a/usr/src/man/man1m/zpool.1m +++ b/usr/src/man/man1m/zpool.1m @@ -1,5 +1,6 @@ '\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved. .\" Copyright 2011, Nexenta Systems, Inc. All Rights Reserved. .\" Copyright (c) 2013 by Delphix. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development @@ -1608,7 +1609,7 @@ the pool, in addition to the pool-wide statistics. .sp .ne 2 .na -\fB\fBzpool list\fR [\fB-T\fR \fBu\fR | \fBd\fR] [\fB-Hv\fR] [\fB-o\fR \fIprops\fR[,...]] [\fIpool\fR] ... +\fB\fBzpool list\fR [\fB-T\fR \fBu\fR | \fBd\fR] [\fB-Hvp\fR] [\fB-o\fR \fIprops\fR[,...]] [\fIpool\fR] ... [\fIinterval\fR[\fIcount\fR]]\fR .ad .sp .6 @@ -1670,6 +1671,15 @@ Verbose statistics. Reports usage statistics for individual \fIvdevs\fR within the pool, in addition to the pool-wise statistics. .RE +.sp +.ne 2 +.na +\fB\fB-p\fR\fR +.ad +.RS 12n +Display numbers in parseable (exact) values. +.RE + .RE .sp diff --git a/usr/src/man/man2/fcntl.2 b/usr/src/man/man2/fcntl.2 index c7d769f874..2e9685d0a6 100644 --- a/usr/src/man/man2/fcntl.2 +++ b/usr/src/man/man2/fcntl.2 @@ -1,4 +1,5 @@ '\" te +.\" Copyright 2015 Joyent, Inc. .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All rights reserved. .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T @@ -10,7 +11,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH FCNTL 2 "Apr 19, 2013" +.TH FCNTL 2 "Feb 16, 2015" .SH NAME fcntl \- file control .SH SYNOPSIS @@ -227,20 +228,25 @@ results are unspecified. .sp .LP -The following commands are available for advisory record locking. Record -locking is supported for regular files, and may be supported for other files. +The following commands are available for POSIX advisory or mandatory record +locking. POSIX record locking is supported for regular files, and may be +supported for other files. See the FILE LOCKING section of this manual page for +information about the types of file locks available and their interaction. .sp .ne 2 .na \fB\fBF_GETLK\fR\fR .ad .RS 14n -Get the first lock which blocks the lock description pointed to by the third -argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, defined in -<\fBfcntl.h\fR>. The information retrieved overwrites the information passed to -\fBfcntl()\fR in the structure \fBflock\fR. If no lock is found that would -prevent this lock from being created, then the structure will be left unchanged -except for the lock type which will be set to \fBF_UNLCK\fR. +Get the first lock which blocks the POSIX lock description pointed to by the +third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, +defined in <\fBfcntl.h\fR>. The information retrieved overwrites the +information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is +found that would prevent this lock from being created, then the structure will +be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR. +If multiple locks exist that would prevent this lock from being created, which +one is returned is unspecified. If the blocking lock is an OFD-style lock, +\fB\(mi1\fR\& will be returned for the lock's pid value. .RE .sp @@ -250,7 +256,7 @@ except for the lock type which will be set to \fBF_UNLCK\fR. .ad .RS 14n Equivalent to \fBF_GETLK\fR, but takes a \fBstruct flock64\fR argument rather -than a \fBstruct flock\fR argument. +than a \fBstruct flock\fR argument. See \fBlf64\fR(5). .RE .sp @@ -259,7 +265,7 @@ than a \fBstruct flock\fR argument. \fB\fBF_SETLK\fR\fR .ad .RS 14n -Set or clear a file segment lock according to the lock description pointed to +Set or clear a POSIX record lock according to the lock description pointed to by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, defined in <\fBfcntl.h\fR>. \fBF_SETLK\fR is used to establish shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks (\fBF_WRLCK\fR), @@ -276,7 +282,7 @@ return value of \fB\(mi1\fR\&. .ad .RS 14n Equivalent to \fBF_SETLK\fR, but takes a \fBstruct flock64\fR argument rather -than a \fBstruct flock\fR argument. +than a \fBstruct flock\fR argument. See \fBlf64\fR(5). .RE .sp @@ -300,22 +306,194 @@ set to \fBEINTR\fR, and the lock operation will not be done. .ad .RS 14n Equivalent to \fBF_SETLKW\fR, but takes a \fBstruct flock64\fR argument rather -than a \fBstruct flock\fR argument. +than a \fBstruct flock\fR argument. See \fBlf64\fR(5). +.RE + +.sp +.LP +The following commands are available for OFD (open file description) advisory +record locking. OFD record locking is supported for regular files, and may be +supported for other files. See the FILE LOCKING section of this manual page for +information about the types of file locks available and their interaction. +OFD-style record locks are currently limited to spanning the entire file and +these locks are currently not supported over remote file systems (e.g. +\fBnfs\fR(4)) which use the Network Lock Manager. +.sp +.ne 2 +.na +\fB\fBF_OFD_GETLK\fR\fR +.ad +.RS 14n +Get the first lock which blocks the OFD lock description pointed to by the +third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, +defined in <\fBfcntl.h\fR>. The information retrieved overwrites the +information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is +found that would prevent this lock from being created, then the structure will +be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR. +If multiple locks exist that would prevent this lock from being created, which +one is returned is unspecified. If the blocking lock is an OFD-style lock, +\fB\(mi1\fR\& will be returned for the lock's pid value. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_GETLK64\fR\fR +.ad +.RS 14n +Equivalent to \fBF_OFD_GETLK\fR, but takes a \fBstruct flock64\fR argument +rather than a \fBstruct flock\fR argument. See \fBlf64\fR(5). This command +exists solely to allow the use of OFD locks with the transitional 64-bit file +interfaces. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLK\fR\fR +.ad +.RS 14n +Set or clear a OFD record lock according to the lock description pointed to +by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct +flock\fR, defined in <\fBfcntl.h\fR>. \fBF_OFD_SETLK\fR is used to establish +shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks +(\fBF_WRLCK\fR), as well as to remove either type of lock (\fBF_UNLCK\fR). +\fBF_RDLCK\fR, \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>. +If a shared or exclusive lock cannot be set, \fBfcntl()\fR will return +immediately with a return value of \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLK64\fR\fR +.ad +.RS 14n +Equivalent to \fBF_OFD_SETLK\fR, but takes a \fBstruct flock64\fR argument +rather than a \fBstruct flock\fR argument. See \fBlf64\fR(5). This command +exists solely to allow the use of OFD locks with the transitional 64-bit file +interfaces. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLKW\fR\fR +.ad +.RS 14n +This command is the same as \fBF_OFD_SETLK\fR except that if a shared or +exclusive lock is blocked by other locks, the process will wait until the +request can be satisfied. If a signal that is to be caught is received while +\fBfcntl()\fR is waiting for a region, \fBfcntl()\fR will be interrupted. Upon +return from the process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR +with \fBerrno\fR set to \fBEINTR\fR, and the lock operation will not be done. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLKW64\fR\fR +.ad +.RS 14n +Equivalent to \fBF_OFD_SETLKW\fR, but takes a \fBstruct flock64\fR argument +rather than a \fBstruct flock\fR argument. See \fBlf64\fR(5). This command +exists solely to allow the use of OFD locks with the transitional 64-bit file +interfaces. +.RE + +.sp +.LP +The following values for \fIcmd\fR are used for file share reservations. A +share reservation is placed on an entire file to allow cooperating processes to +control access to the file. See the SHARE RESERVATIONS section of this manual +page below for additional information. +.sp +.ne 2 +.na +\fB\fBF_SHARE\fR\fR +.ad +.RS 13n +Sets a share reservation on a file with the specified access mode and +designates which types of access to deny. +.RE + +.sp +.ne 2 +.na +\fB\fBF_UNSHARE\fR\fR +.ad +.RS 13n +Remove an existing share reservation. .RE +.SH FILE LOCKING .sp .LP -When a shared lock is set on a segment of a file, other processes will 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 will fail if the file descriptor -was not opened with read access. +Two types of file locks are supported: POSIX-style and OFD-style. OFD-style +locks are associated with the open file description (not descriptor) instead +of with a process. Either type is advisory by default, but POSIX-style locks +can be mandatory if, and only if, mandatory locking has been enabled on the +file being locked. Each type of lock may be created through two different +interfaces. POSIX-style locks are created via the \fBF_SETLK\fR, +\fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR commands to this system +call or by use of the \fBlockf\fR(3C) routine. There is no difference between +locks created via one mechanism or the other. Likewise, OFD-style locks are +created via the \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or +\fBF_OFD_SETLKW64\fR commands to this system call or by use of the +Linux/BSD-compatible \fBflock\fR(3C) routine. Note that this system call +supports the creation of range-specified OFD-style file locks, while +\fBflock\fR(3C) does not. However, the current implementation of OFD-style +locking is limited to locking the entire file. This limitation might be +removed in the future. .sp .LP -An exclusive lock will 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 will fail if the file descriptor was not opened with write -access. +The essential distinction between POSIX-style locks and OFD-style locks lie +in how ownership of a lock is scoped. POSIX locks are scoped to a process. All +POSIX locks associated with a file for a given process are removed when any +file descriptor for that file is closed by that process or the process holding +that file descriptor terminates. POSIX-style locks are not inherited by a child +process created using \fBfork\fR(2). An OFD-style lock is scoped to the file +description for a file, not the process or open file descriptor. Thus all file +descriptors referring to the same description (i.e. those created via the +\fBF_DUPFD\fR, \fBF_DUP2FD\fR, \fBF_DUPFD_CLOEXEC\fR, or \fBF_DUP2FD_CLOEXEC\fR +commands to the \fBfcntl\fR(2) system call, or those created via the +\fBdup\fR(2) system call, or those inherited by a child process created via +\fBfork\fR(2)) reference the same lock, but a file descriptor obtained via a +separate \fBopen\fR(2) call on the same file will reference a different lock. +A lock is removed only on the last \fBclose\fR(2) of the description, or when +the lock is explicitly unlocked. +.sp +.LP +Locks of both styles are compatible. A file that has been locked with one +style of lock will be regarded as locked when creation of a lock of either +style is attempted, and information about the lock will be provided via +any of the \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or +\fBF_OFD_GETLK64\fR commands to this system call if that lock would conflict +with an attempt to create the specified lock regardless of whether the +specified lock is of the same style as the conflicting extant lock. +Because ownership of OFD-style locks is scoped to the open description rather +than the calling process, the \fBl_pid\fR field of a lock descriptor for any +such lock will always be set to \fB\(mi1\fR\&. +.sp +.LP +When a shared lock is set on a segment of a file, other callers (regardless +of whether in the same or different process and of whether referenced via the +same open file) will be able to set shared locks on that segment or a portion +of it. A POSIX-style shared lock prevents any other process from setting an +exclusive lock on any portion of the protected area. A OFD-style shared lock +prevents any caller (even callers in the same process) from setting an +exclusive lock on any portion of the protected area, unless the caller makes +the request against a file descriptor referencing the same open file against +which the shared lock was created, in which case the lock will be downgraded +to a shared lock with respect to the specified region. A request for a shared +lock of either style will fail if the file descriptor was not opened with +read access. +.sp +.LP +A POSIX-style exclusive lock will prevent any other process from setting a +shared lock or an exclusive lock (of either style) on any portion of the +protected area. A request for an exclusive lock will fail if the file +descriptor was not opened with write access. .sp .LP The \fBflock\fR structure contains at least the following elements: @@ -340,13 +518,17 @@ be measured from the start of the file, current position or end of the file, respectively. The value of \fBl_len\fR is the number of consecutive bytes to be locked. The value of \fBl_len\fR may be negative (where the definition of \fBoff_t\fR permits negative values of \fBl_len\fR). After a successful -\fBF_GETLK\fR or \fBF_GETLK64\fR request, that is, one in which a lock was -found, the value of \fBl_whence\fR will be \fBSEEK_SET\fR. +\fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or \fBF_OFD_GETLK64\fR +request, that is, one in which a lock was found, the value of \fBl_whence\fR +will be \fBSEEK_SET\fR. .sp .LP The \fBl_pid\fR and \fBl_sysid\fR fields are used only with \fBF_GETLK\fR or \fBF_GETLK64\fR to return the process \fBID\fR of the process holding a -blocking lock and to indicate which system is running that process. +POSIX-style blocking lock and to indicate which system is running that process, +or \fB\(mi1\fR\& if it is an OFD-style lock. These fields must both be +initialized to 0 prior to issuing a OFD-style locking command +(\fBF_OFD_GETLK\fR or \fBF_OFD_GETLK64\fR). .sp .LP If \fBl_len\fR is positive, the area affected starts at \fBl_start\fR and ends @@ -359,61 +541,48 @@ to the largest possible value of the file offset for that file by setting \fBl_whence\fR is set to \fBSEEK_SET\fR, the whole file will be locked. .sp .LP -If a process has an existing lock in which \fBl_len\fR is 0 and which includes -the last byte of the requested segment, and an unlock (\fBF_UNLCK\fR) request -is made in which \fBl_len\fR 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\fR, then -the \fBF_UNLCK\fR request will be treated as a request to unlock from the start +If a lock exists for which \fBl_len\fR is 0 and which includes the last byte of +the requested segment, and an unlock (\fBF_UNLCK\fR) request is made in which +\fBl_len\fR 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\fR, then the +\fBF_UNLCK\fR request will be treated as a request to unlock from the start of the requested segment with an \fBl_len\fR equal to 0. Otherwise, the request will attempt to unlock only the requested segment. .sp .LP -There will be at most one type of lock set for each byte in the file. Before a -successful return from an \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or -\fBF_SETLKW64\fR 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 will be replaced by the new lock type. As -specified above under the descriptions of shared locks and exclusive locks, an -\fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request -will (respectively) 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. +There will be at most one type of lock set for each byte in the +file. Before a successful return from an \fBF_SETLK\fR, \fBF_SETLK64\fR, +\fBF_SETLKW\fR, or \fBF_SETLKW64\fR request when the calling process has +previously existing POSIX-style locks on bytes in the region specified by the +request, the previous POSIX-style lock type for each byte in the specified +region will be replaced by the new lock type. As specified above under the +descriptions of shared locks and exclusive locks, an \fBF_SETLK\fR, +\fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request will +(respectively) fail or block when locks exist on bytes in the specified region +and the type of any of those locks conflicts with the type specified in the +request. .sp .LP -All locks associated with a file for a given process are 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 created -using \fBfork\fR(2). +Similarly, before a successful return from an \fBF_OFD_SETLK\fR, +\fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR request when +previously-created OFD-style locks associated with the open file apply to +bytes in the region specified by the request, the previous OFD-style lock type +for each byte in the specified region will be replaced by the new lock type. +As specified above under the descriptions of shared locks and exclusive locks, +an \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or +\fBF_OFD_SETLKW64\fR request will (respectively) fail or block when locks exist +on bytes in the specified region and the type of any of those locks conflicts +with the type specified in the request. .sp .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, -\fBfcntl()\fR will fail with an \fBEDEADLK\fR error. -.sp -.LP -The following values for \fIcmd\fR are used for file share reservations. A -share reservation is placed on an entire file to allow cooperating processes to -control access to the file. -.sp -.ne 2 -.na -\fB\fBF_SHARE\fR\fR -.ad -.RS 13n -Sets a share reservation on a file with the specified access mode and -designates which types of access to deny. -.RE - -.sp -.ne 2 -.na -\fB\fBF_UNSHARE\fR\fR -.ad -.RS 13n -Remove an existing share reservation. -.RE +\fBfcntl()\fR will fail with an \fBEDEADLK\fR error. This deadlock detection +and error value apply only to POSIX-style locks. No deadlock detection is +performed when attempting to set an OFD-style lock. +.SH SHARE RESERVATIONS .sp .LP File share reservations are an advisory form of access control among @@ -608,6 +777,60 @@ The return value will not be negative. .sp .ne 2 .na +\fB\fBF_OFD_GETLK\fR\fR +.ad +.RS 14n +Value other then \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_GETLK64\fR\fR +.ad +.RS 14n +Value other then \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLK\fR\fR +.ad +.RS 14n +Value other then \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLK64\fR\fR +.ad +.RS 14n +Value other then \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLKW\fR\fR +.ad +.RS 14n +Value other then \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBF_OFD_SETLKW64\fR\fR +.ad +.RS 14n +Value other then \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.na \fB\fBF_SETFD\fR\fR .ad .RS 14n @@ -700,12 +923,13 @@ The \fBfcntl()\fR function will fail if: \fB\fBEAGAIN\fR\fR .ad .RS 13n -The \fIcmd\fR argument is \fBF_SETLK\fR or \fBF_SETLK64\fR, the type of lock -\fB(l_type)\fR is a shared (\fBF_RDLCK\fR) or exclusive (\fBF_WRLCK\fR) 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. +The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_OFD_SETLK\fR, +or \fBF_OFD_SETLK64\fR, the type of lock \fB(l_type)\fR is a shared +(\fBF_RDLCK\fR) or exclusive (\fBF_WRLCK\fR) lock, and the segment of a file +to be locked is already exclusive-locked by another process or open file; 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 or open +file. .sp The \fIcmd\fR argument is \fBF_FREESP\fR, the file exists, mandatory file/record locking is set, and there are outstanding record locks on the file; @@ -724,8 +948,9 @@ existing \fBf_deny\fR share reservation. .ad .RS 13n The \fIfildes\fR argument is not a valid open file descriptor; or the \fIcmd\fR -argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or -\fBF_SETLKW64\fR, the type of lock, \fBl_type\fR, is a shared lock +argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, +\fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or +\fBF_OFD_SETLKW64\fR, the type of lock, \fBl_type\fR, is a shared lock (\fBF_RDLCK\fR), and \fIfildes\fR is not a valid file descriptor open for reading; or the type of lock \fBl_type\fR is an exclusive lock (\fBF_WRLCK\fR) and \fIfildes\fR is not a valid file descriptor open for writing. @@ -752,11 +977,10 @@ reading. .ad .RS 13n The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_SETLK\fR, -\fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, or \fBF_FREESP\fR and the +\fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, +\fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, +\fBF_OFD_SETLKW64\fB, \fBF_SHARE\fR, \fBF_UNSHARE\fR, or \fBF_FREESP\fR and the \fIarg\fR argument points to an illegal address. -.sp -The \fIcmd\fR argument is \fBF_SHARE\fR or \fBF_UNSHARE\fR and \fIarg\fR points -to an illegal address. .RE .sp @@ -765,8 +989,8 @@ to an illegal address. \fB\fBEINTR\fR\fR .ad .RS 13n -The \fIcmd\fR argument is \fBF_SETLKW\fR or \fBF_SETLKW64\fR and the function -was interrupted by a signal. +The \fIcmd\fR argument is \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLKW\fR, +or \fBF_OFD_SETLKW64\fR, and the function was interrupted by a signal. .RE .sp @@ -778,9 +1002,11 @@ was interrupted by a signal. The \fIcmd\fR argument is invalid or not supported by the file system; or the \fIcmd\fR argument is \fBF_DUPFD\fR and \fIarg\fR is negative or greater than or equal to \fBOPEN_MAX\fR; or the \fIcmd\fR argument is \fBF_GETLK\fR, -\fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or -\fBF_SETLKW64\fR and the data pointed to by \fIarg\fR is not valid; or -\fIfildes\fR refers to a file that does not support locking. +\fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, +\fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, +\fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and the data +pointed to by \fIarg\fR is not valid; or \fIfildes\fR refers to a file that +does not support locking. .sp The \fIcmd\fR argument is \fBF_UNSHARE\fR and a reservation with this \fBf_id\fR for this process does not exist. @@ -815,9 +1041,11 @@ greater than or equal to \fIarg\fR are available. \fB\fBENOLCK\fR\fR .ad .RS 13n -The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or -\fBF_SETLKW64\fR and satisfying the lock or unlock request would result in the -number of locked regions in the system exceeding a system-imposed limit. +The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, +\fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, +or \fBF_OFD_SETLKW64\fR, and satisfying the lock or unlock request would +result in the number of locked regions in the system exceeding a +system-imposed limit. .RE .sp @@ -839,12 +1067,14 @@ file is on a remote machine, and the link to that machine is no longer active. .RS 13n One of the values to be returned cannot be represented correctly. .sp -The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_SETLK\fR, or \fBF_SETLKW\fR and +The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_SETLK\fR, \fBF_SETLKW\fR, +\fBF_OFD_GETLK\fR, \fBF_OFD_SETLK\fR, or \fBF_OFD_SETLKW\fR, and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in the requested segment cannot be represented correctly in an object of type \fBoff_t\fR. .sp -The \fIcmd\fR argument is \fBF_GETLK64\fR, \fBF_SETLK64\fR, or \fBF_SETLKW64\fR +The \fIcmd\fR argument is \fBF_GETLK64\fR, \fBF_SETLK64\fR, \fBF_SETLKW64\fR, +\fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK64\fR, or \fBF_OFD_SETLKW64\fR, and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in the requested segment cannot be represented correctly in an object of type \fBoff64_t\fR. @@ -859,8 +1089,9 @@ The \fBfcntl()\fR function may fail if: \fB\fBEAGAIN\fR\fR .ad .RS 11n -The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or -\fBF_SETLKW64\fR, and the file is currently being mapped to virtual memory +The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, +\fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, +or \fBF_OFD_SETLKW64\fR and the file is currently being mapped to virtual memory using \fBmmap\fR(2). .RE @@ -903,7 +1134,8 @@ MT-Level Async-Signal Safe \fBlockd\fR(1M), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBexec\fR(2), \fBfork\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBpipe\fR(2), \fBread\fR(2), \fBsigaction\fR(2), \fBwrite\fR(2), \fBdup2\fR(3C), -\fBfcntl.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) +\fBflock\fR(3C), \fBlockf\fR(3C), \fBfcntl.h\fR(3HEAD), \fBattributes\fR(5), +\fBlf64\fR(5), \fBstandards\fR(5) .sp .LP \fIProgramming Interfaces Guide\fR diff --git a/usr/src/man/man2/meminfo.2 b/usr/src/man/man2/meminfo.2 index e606865486..a0c696d36e 100644 --- a/usr/src/man/man2/meminfo.2 +++ b/usr/src/man/man2/meminfo.2 @@ -1,9 +1,10 @@ '\" te .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2015, Joyent, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH MEMINFO 2 "Feb 21, 2003" +.TH MEMINFO 2 "Mar 10, 2015" .SH NAME meminfo \- provide information about memory .SH SYNOPSIS @@ -151,6 +152,11 @@ lgrp of \fIn\fRth physical replica of specified virtual address locality group of specified physical address .RE +.sp +.LP +All but \fBMEMINFO_VLGRP\fR and \fBMEMINFO_VPAGESIZE\fR require the +\fBPRIV_PROC_MEMINFO\fR privilege. + .SH RETURN VALUES .sp .LP @@ -265,4 +271,4 @@ MT-Level Async-Signal-Safe .LP \fBmemcntl\fR(2), \fBmmap\fR(2), \fBgethomelgroup\fR(3C), \fBgetpagesize\fR(3C), \fBmadvise\fR(3C), \fBsysconf\fR(3C), -\fBattributes\fR(5) +\fBattributes\fR(5), \fBprivileges\fR(5) diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile index a31d024d15..975c56e921 100644 --- a/usr/src/man/man3c/Makefile +++ b/usr/src/man/man3c/Makefile @@ -110,6 +110,9 @@ MANFILES= __fbufsize.3c \ enable_extended_FILE_stdio.3c \ encrypt.3c \ end.3c \ + epoll_create.3c \ + epoll_ctl.3c \ + epoll_wait.3c \ err.3c \ euclen.3c \ eventfd.3c \ @@ -128,6 +131,7 @@ MANFILES= __fbufsize.3c \ fgetpos.3c \ fgetwc.3c \ floating_to_decimal.3c \ + flock.3c \ flockfile.3c \ fmtmsg.3c \ fnmatch.3c \ @@ -202,6 +206,9 @@ MANFILES= __fbufsize.3c \ imaxdiv.3c \ index.3c \ initgroups.3c \ + inotify_init.3c \ + inotify_add_watch.3c \ + inotify_rm_watch.3c \ insque.3c \ is_system_labeled.3c \ isaexec.3c \ @@ -408,6 +415,7 @@ MANFILES= __fbufsize.3c \ sigfpe.3c \ siginterrupt.3c \ signal.3c \ + signalfd.3c \ sigqueue.3c \ sigsetops.3c \ sigstack.3c \ @@ -470,6 +478,7 @@ MANFILES= __fbufsize.3c \ timer_delete.3c \ timer_settime.3c \ timeradd.3c \ + timerfd_create.3c \ tmpfile.3c \ tmpnam.3c \ toascii.3c \ @@ -733,6 +742,8 @@ MANLINKS= FD_CLR.3c \ endusershell.3c \ endutent.3c \ endutxent.3c \ + epoll_create1.3c \ + epoll_pwait.3c \ erand48.3c \ errno.3c \ errx.3c \ @@ -1581,6 +1592,9 @@ _etext.3c := LINKSRC = end.3c edata.3c := LINKSRC = end.3c etext.3c := LINKSRC = end.3c +epoll_create1.3c := LINKSRC = epoll_create.3c +epoll_pwait.3c := LINKSRC = epoll_wait.3c + errx.3c := LINKSRC = err.3c verr.3c := LINKSRC = err.3c verrx.3c := LINKSRC = err.3c diff --git a/usr/src/man/man3c/epoll_create.3c b/usr/src/man/man3c/epoll_create.3c new file mode 100644 index 0000000000..3dd9abf5f7 --- /dev/null +++ b/usr/src/man/man3c/epoll_create.3c @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH EPOLL_CREATE 3C "Apr 17, 2014" +.SH NAME +epoll_create, epoll_create1 \- create an epoll instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> + +\fBint\fR \fBepoll_create\fR(\fBint\fR \fIsize\fR); +.fi + +.LP +.nf +\fBint\fR \fBepoll_create1\fR(\fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBepoll_create()\fR and \fBepoll_create1()\fR functions both create an +\fBepoll\fR(5) instance that can be operated upon via \fBepoll_ctl\fR(3C), +\fBepoll_wait\fR(3C) and \fBepoll_pwait\fR(3C). \fBepoll\fR instances are +represented as file descriptors, and should be closed via \fBclose\fR(2). + +The only difference between the two functions is their signature; +\fBepoll_create()\fR takes a size argument that +is vestigal and is only meaningful in as much as it must be greater than +zero, while \fBepoll_create1()\fR takes a flags argument that can have +any of the following values: + +.sp +.ne 2 +.na +\fBEPOLL_CLOEXEC\fR +.ad +.RS 12n +Instance should be closed upon an +\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno +is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBepoll_create()\fR and \fBepoll_create1()\fR functions will fail if: +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +Either the \fIsize\fR is zero (\fBepoll_create()\fR) or the \fIflags\fR +are invalid (\fBepoll_create1()\fR). +.RE + +.sp +.ne 2 +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling +process. +.RE + +.sp +.ne 2 +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR(5) facility is implemented for purposes of offering +compatibility for Linux-borne applications; native +applications should continue to prefer using event ports via the +\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) +interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBepoll_ctl\fR(3C), \fBepoll_wait\fR(3C), \fBepoll\fR(5) diff --git a/usr/src/man/man3c/epoll_ctl.3c b/usr/src/man/man3c/epoll_ctl.3c new file mode 100644 index 0000000000..ccf3139396 --- /dev/null +++ b/usr/src/man/man3c/epoll_ctl.3c @@ -0,0 +1,300 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH EPOLL_CTL 3C "Apr 17, 2014" +.SH NAME +epoll_ctl \- control an epoll instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> + +\fBint\fR \fBepoll_ctl\fR(\fBint\fR \fIepfd\fR, \fBint\fR \fIop\fR, \fBint\fR \fIfd\fR, \fBstruct epoll_event *\fR\fIevent\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBepoll_ctl()\fR function executes the operation specified by +\fIop\fR (as parameterized by \fIevent\fR) on the \fIepfd\fR epoll instance. +Valid values for \fIop\fR: + +.sp +.ne 2 +.na +\fBEPOLL_CTL_ADD\fR +.ad +.RS 12n +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, +associate the file descriptor specified by \fIfd\fR with the event specified +by \fIevent\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLL_CTL_DEL\fR +.ad +.RS 12n +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, +remove all event associations for the file descriptor specified by \fIfd\fR. +\fIevent\fR is ignored, and may be NULL. +.RE + +.sp +.ne 2 +.na +\fBEPOLL_CTL_MOD\fR +.ad +.RS 12n +For the \fBepoll\fR(5) instance specified by \fIepfd\fR, modify the event +association for the file descriptor specified by \fIfd\fR to be that +specified by \fIevent\fR. + +.RE + +The \fIevent\fR parameter has the following structure: + +.in +4 +.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_data_t data; +}; +.fi +.in -4 + +The \fIdata\fR field specifies the datum to +be associated with the event and +will be returned via \fBepoll_wait\fR(3C). +The \fIevents\fR field denotes both the desired events (when specified via +\fBepoll_ctl()\fR) and the events that have occurred (when returned via +\fBepoll_wait\fR(3C)). +In either case, the +\fIevents\fR field is a bitmask constructed by a logical \fBOR\fR operation +of any combination of the following event flags: + +.sp +.ne 2 +.na +\fBEPOLLIN\fR +.RS 14n +Data other than high priority data may be read without blocking. For streams, +this flag is set in the returned \fIevents\fR even if the message is of +zero length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLPRI\fR +.RS 14n +Normal data (priority band equals 0) may be read without blocking. For streams, +this flag is set in the returned \fIevents\fR even if the message is of zero +length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLOUT\fR +.RS 14n +Normal data (priority band equals 0) may be written without blocking. +.RE + +.sp +.ne 2 +.na +\fBEPOLLRDNORM\fR +.RS 14n +Normal data (priority band equals 0) may be read without blocking. For streams, +this flag is set in the returned \fIrevents\fR even if the message is of +zero length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLRDBAND\fR +.RS 14n +Data from a non-zero priority band may be read without blocking. For streams, +this flag is set in the returned \fIrevents\fR even if the message is of +zero length. +.RE + +.sp +.ne 2 +.na +\fBEPOLLWRNORM\fR +.RS 14n +The same as \fBEPOLLOUT\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLLWRBAND\fR +.RS 14n +Priority data (priority band > 0) may be written. This event only examines +bands that have been written to at least once. +.RE + +.sp +.ne 2 +.na +\fBEPOLLMSG\fR +.RS 14n +This exists only for backwards binary and source compatibility with Linux; +it has no meaning and is ignored. +.RE + +.sp +.ne 2 +.na +\fBEPOLLERR\fR +.RS 14n +An error has occurred on the device or stream. This flag is only valid in the +returned \fIevents\fR field. +.RE + +.sp +.ne 2 +.na +\fBEPOLLHUP\fR +.RS 14n +A hangup has occurred on the stream. This event and \fBEPOLLOUT\fR are mutually +exclusive; a stream can never be writable if a hangup has occurred. However, +this event and \fBEPOLLIN\fR, \fBEPOLLRDNORM\fR, \fBEPOLLRDBAND\fR, +\fBEPOLLRDHUP\fR or +\fBEPOLLPRI\fR are not mutually exclusive. This flag is only valid in the +the \fIevents\fR field returned from \fBepoll_wait\fR(3C); it is not used +in the \fIevents\fR field specified via \fBepoll_ctl()\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLLRDHUP\fR +.RS 14n +The stream socket peer shutdown the writing half of the connection and no +further data will be readable via the socket. This event is not mutually +exclusive with \fBEPOLLIN\fR. +.RE + +.sp +.ne 2 +.na +\fBEPOLLWAKEUP\fR +.RS 14n +This exists only for backwards binary and source compatibility with Linux; +it has no meaning and is ignored. +.RE + +.sp +.ne 2 +.na +\fBEPOLLONESHOT\fR +.RS 14n +Sets the specified event to be in one-shot mode, whereby the event association +with the \fBepoll\fR(5) instance specified by \fIepfd\fR is removed atomically +as the event is returned via \fBepoll_wait\fR(3C). Use of this mode allows +for resolution of some of the +races inherent in multithreaded use of \fBepoll_wait\fR(3C). +.RE + +.sp +.ne 2 +.na +\fBEPOLLET\fR +.RS 14n +Sets the specified event to be edge-triggered mode instead of the default +mode of level-triggered. In this mode, events will be induced by +transitions on an event source rather than the state of the event source. +While perhaps superficially appealing, this mode introduces several new +potential failure modes for user-level software and should be used +with caution. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, \fBepoll_ctl()\fR returns 0. +If an error occurs, -1 is returned and errno is set to indicate +the error. + +.SH ERRORS +.sp +.LP +\fBepoll_ctl()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +\fIepfd\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +The memory associated with \fIevent\fR was not mapped. +.RE + +.sp +.ne 2 +.na +\fB\fBEEXIST\fR\fR +.ad +.RS 10n +The operation specified was \fBEPOLL_CTL_ADD\fR and the specified file +descriptor is already associated with an event for the specified +\fBepoll\fR(5) instance. +.RE + +.sp +.ne 2 +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +The operation specified was \fBEPOLL_CTL_MOD\fR or \fBEPOLL_CTL_DEL\fR and +the specified file descriptor is not associated with an event for the +specified \fBepoll\fR(5) instance. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR(5) facility is implemented for purposes of offering +compatibility for Linux-borne applications; native +applications should continue to prefer using event ports via the +\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) +interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBepoll_create\fR(3C), \fBepoll_wait\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBepoll\fR(5) diff --git a/usr/src/man/man3c/epoll_wait.3c b/usr/src/man/man3c/epoll_wait.3c new file mode 100644 index 0000000000..670eebe89c --- /dev/null +++ b/usr/src/man/man3c/epoll_wait.3c @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH EPOLL_WAIT 3C "Apr 17, 2014" +.SH NAME +epoll_wait, epoll_pwait \- wait for epoll events +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> + +\fBint\fR \fBepoll_wait\fR(\fBint\fR \fIepfd\fR, \fBstruct epoll_event *\fR\fIevents\fR, + \fBint\fR \fImaxevents\fR, \fBint\fR \fItimeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBepoll_pwait\fR(\fBint\fR \fIepfd\fR, \fBstruct epoll_event *\fR\fIevents\fR, + \fBint\fR \fImaxevents\fR, \fBint\fR \fItimeout\fR, + \fBconst sigset_t *\fR\fIsigmask\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBepoll_wait()\fR function waits for events on the \fBepoll\fR(5) +instance specified by \fIepfd\fR. The \fIevents\fR parameter must point to +an array of \fImaxevents\fR \fIepoll_event\fR structures to be +filled in with pending events. The \fItimeout\fR argument specifies the +number of milliseconds to wait for an event if none is pending. A +\fItimeout\fR of -1 denotes an infinite timeout. + +The \fBepoll_pwait()\fR is similar to \fBepoll_wait()\fR, but takes an +additional \fIsigmask\fR argument that specifies the desired signal mask +when \fBepoll_pwait()\fR is blocked. It is equivalent to atomically +setting the signal mask, calling \fBepoll_wait()\fR, and restoring the +signal mask upon return, and is therefore similar to the relationship +between \fBselect\fR(3C) and \fBpselect\fR(3C). + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBepoll_wait()\fR and \fBepoll_pwait()\fR return +the number of events, or 0 if none was pending and \fItimeout\fR milliseconds +elapsed. If an error occurs, -1 is returned and errno is set to indicate +the error. + +.SH ERRORS +.sp +.LP +The \fBepoll_wait()\fR and \fBepoll_pwait()\fR functions will fail if: +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +\fIepfd\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +The memory associated with \fIevents\fR was not mapped or was not writable. +.RE + +.sp +.ne 2 +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +A signal was received during the \fBepoll_wait()\fR or \fBepoll_pwait()\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +Either \fIepfd\fR is not a valid \fBepoll\fR(5) instance or \fImaxevents\fR +is not greater than zero. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR(5) facility is implemented for purposes of offering +compatibility for Linux-borne applications; native +applications should continue to prefer using event ports via the +\fBport_create\fR(3C), \fBport_associate\fR(3C) and \fBport_get\fR(3C) +interfaces. See \fBepoll\fR(5) for compatibility details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBepoll_create\fR(3C), \fBepoll_ctl\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBpselect\fR(3C), \fBepoll\fR(5) diff --git a/usr/src/man/man3c/flock.3c b/usr/src/man/man3c/flock.3c new file mode 100644 index 0000000000..a0953f67f9 --- /dev/null +++ b/usr/src/man/man3c/flock.3c @@ -0,0 +1,209 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 1989 AT&T +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Copyright 2015 Joyent, Inc. +.\" +.TH FLOCK 3C "Feb 16, 2015" +.SH NAME +flock \- OFD(open file description)-style file locking +.SH SYNOPSIS +.LP +.nf +#include <sys/file.h> + +\fBint\fR \fBflock\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIoperation\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBflock()\fR function allows advisory locks to be applied to and removed +from a file. Calls to \fBflock()\fR from callers that attempt to lock +the locked file section via a different open file handle will either return an +error value or be put to sleep until the resource becomes unlocked. +See \fBfcntl\fR(2) for more information about record locking. Locks created or +removed via this function will apply to the entire file, including any future +growth in the file's length. +.sp +.LP +The \fIfildes\fR argument is an open file descriptor. A lock can be established +without regard for the mode with which the file was opened. +.sp +.LP +The \fIoperation\fR argument is a control value that specifies the action to be +taken. The permissible values for \fIoperation\fR are defined in +<\fBsys/file.h\fR> as follows: +.sp +.in +2 +.nf +#define LOCK_SH 1 /* shared file lock */ +#define LOCK_EX 2 /* exclusive file lock */ +#define LOCK_NB 4 /* do not block when attempting to create lock */ +#define LOCK_UN 8 /* remove existing file lock */ +.fi +.in -2 + +.sp +.LP +To create a lock, either \fBLOCK_SH\fR or \fBLOCK_EX\fR should be specified, +optionally bitwise-ored with \fBLOCK_NB\fR. To remove a lock, \fBLOCK_UN\fR +should be specified. All other values of \fIoperation\fR are reserved for +future extensions and will result in an error if not implemented. +.sp +.LP +This function creates, upgrades, downgrades, or removes either shared or +exclusive OFD-style locks. Locks created by this function are owned by open +files, not file descriptors. That is, file descriptors duplicated through +\fBdup\fR(2), \fBfork\fR(2), or \fBfcntl\fR(2) do not result in multiple +instances of a lock, but rather multiple references to the same lock. If a +process holding a lock on a file forks and the child explicitly unlocks the +file, the parent will lose its lock. See \fBfcntl\fR(2) for more information +about file locking and the interaction between locks created by this function +and those created by other mechanisms. These locks are currently not supported +over remote file systems (e.g. \fBnfs\fR(4)) which use the Network Lock +Manager. +.sp +.LP +Sleeping on a resource is interrupted with any signal. The \fBalarm\fR(2) +function may be used to provide a timeout facility in applications that require +this facility. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBflock()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 20n +The \fIfildes\fR argument is not a valid open file descriptor; or +\fIoperation\fR contains \fBLOCK_SH\fR and \fIfiledes\fR is not open for +reading; or \fIoperation\fR contains \fBLOCK_EX\fR and \fIfiledes\fR is not +open for writing. +.RE + +.sp +.ne 2 +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 20n +The \fIoperation\fR argument contains \fBLOCK_NB\fR and a conflicting lock +exists. +.RE + +.sp +.ne 2 +.na +\fB\fBEINTR\fR\fR +.ad +.RS 20n +A signal was caught during execution of the function. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 20n +The \fIoperation\fR argument does not contain one of \fBLOCK_SH\fR, +\fBLOCK_EX\fR, or \fBLOCK_UN\fR; or the \fIoperation\fR argument contains +\fBLOCK_UN\fR and \fBLOCK_NB\fR; or the \fIoperation\fR argument contains +any bits other than those set by \fBLOCK_SH\fR, \fBLOCK_EX\fR, \fBLOCK_NB\fR, +and \fBLOCK_UN\fR. +.RE + +.sp +.LP +The \fBflock()\fR function may fail if: +.sp +.ne 2 +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 24n +The \fIoperation\fR argument contains \fBLOCK_SH\fR or \fBLOCK_EX\fR and the +file is mapped with \fBmmap\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBENOLCK\fR\fR +.ad +.RS 20n +The number of locked file regions in the system would exceed a system-imposed +limit. +.RE + +.sp +.ne 2 +.na +\fB\fBEOPNOTSUPP\fR +.ad +.RS 24n +The locking of files of the type indicated by the \fIfildes\fR argument is not +supported. +.RE + +.SH USAGE +.sp +.LP +File-locking should not be used in combination with the \fBfopen\fR(3C), +\fBfread\fR(3C), \fBfwrite\fR(3C) and other \fBstdio\fR functions. Instead, +the more primitive, non-buffered functions (such as \fBopen\fR(2)) 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 +\fBstdio\fR functions are the most common source of unexpected buffering. +.sp +.LP +The \fBalarm\fR(2) function may be used to provide a timeout facility in +applications requiring it. +.sp +.LP +Locks created by this facility conflict with those created by the +\fBlockf\fR(3C) and \fBfcntl\fR(2) facilities. This facility creates and +removed OFD-style locks; see \fBfcntl\fR(2) for information about the +interaction between OFD-style and POSIX-style file locks. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Standard +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), +\fBfcntl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/inotify_add_watch.3c b/usr/src/man/man3c/inotify_add_watch.3c new file mode 100644 index 0000000000..4f79e03c82 --- /dev/null +++ b/usr/src/man/man3c/inotify_add_watch.3c @@ -0,0 +1,120 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH INOTIFY_ADD_WATCH 3C "Sep 17, 2014" +.SH NAME +inotify_add_watch \- add a watch to an inotify instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> + +\fBint\fR \fBinotify_add_watch\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIpathname\fR, \fBuint32_t\fR \fImask\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinotify_add_watch()\fR function adds a watch for the file or +directory specified by \fIpathname\fR to the inotify instance +specified by \fIfd\fR for the events specified by \fImask\fR. See +\fBinotify\fR(5) for details on the meaning of \fImask\fR, how +it affects the interpretation of \fIpathname\fR, and how +events for the watched file or directory are subsequently +retrieved via \fBread\fR(2). + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, \fBinotify_add_watch()\fR returns the +watch descriptor associated with the new watch. +If an error occurs, -1 is returned and errno is set to indicate +the error. + +.SH ERRORS +.sp +.LP +\fBinotify_add_watch()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +\fIpathname\fR could not be opened for reading. +.RE + +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +The \fIfd\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +The memory associated with \fIpathname\fR was not mapped. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIfd\fR argument does not correspond to an +\fBinotify\fR(5) instance as initialized with +\fBinotify_init\fR(3C) or \fBinotify_init1\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +The number of watches on the specified instance would exceed the +maximum number of watches per \fBinotify\fR(5) instance. +.RE + +.sp +.ne 2 +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 10n +\fIpathname\fR does not correspond to a directory and +\fBIN_ONLYDIR\fR was specified in \fImask\fR. +.RE + +.sp +.SH NOTES +.sp +.LP + +While the \fBinotify\fR(5) facility is implemented for purposes of +offering compatibility for Linux-borne applications, native +applications may opt to use it instead of (or in addition to) the +\fBPORT_SOURCE_FILE\fR capability of event ports. See +\fBinotify\fR(5) for details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBinotify\fR(5) diff --git a/usr/src/man/man3c/inotify_init.3c b/usr/src/man/man3c/inotify_init.3c new file mode 100644 index 0000000000..551a2ca798 --- /dev/null +++ b/usr/src/man/man3c/inotify_init.3c @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH INOTIFY_INIT 3C "Sep 17, 2014" +.SH NAME +inotify_init, inotify_init1 \- initialize an inotify instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> + +\fBint\fR \fBinotify_init\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBinotify_init1\fR(\fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinotify_init()\fR and \fBinotify_init1()\fR functions both create an +\fBinotify\fR(5) instance that can be operated upon via +\fBinotify_add_watch\fR(3C), \fBinotify_rm_watch\fR(3C) and \fBread\fR(2). +\fBinotify\fR instances are +represented as file descriptors, and should be closed via \fBclose\fR(2). + +The only difference between the two functions is their signature; +\fBinotify_init()\fR takes no arguments, +while \fBinotify_init1()\fR takes a \fIflags\fR argument that can have +any of the following values: + +.sp +.ne 2 +.na +\fBIN_CLOEXEC\fR +.ad +.RS 12n +Instance should be closed upon an +\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR. +.RE + +.sp +.ne 2 +.na +\fBIN_NONBLOCK\fR +.ad +.RS 12n +Instance will be set to be non-blocking. A \fBread\fR(2) on an +\fBinotify\fR instance that has been initialized with +\fBIN_NONBLOCK\fR will return \fBEAGAIN\fR if there are +no events enqueued in lieu of blocking. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno +is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBinotify_init()\fR and \fBinotify_init1()\fR functions will fail if: +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIflags\fR are invalid (\fBinotify_init1()\fR). +.RE + +.sp +.ne 2 +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling +process, or the maximum number of \fBinotify\fR instances for the user +would be exceeded. +.RE + +.sp +.SH NOTES +.sp +.LP + +While the \fBinotify\fR(5) facility is implemented for purposes of +offering compatibility for Linux-borne applications, native +applications may opt to use it instead of (or in addition to) the +\fBPORT_SOURCE_FILE\fR capability of event ports. See +\fBinotify\fR(5) for details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBinotiy_add_watch\fR(3C), \fBinotify_rm_watch\fR(3C), \fBinotify\fR(5) diff --git a/usr/src/man/man3c/inotify_rm_watch.3c b/usr/src/man/man3c/inotify_rm_watch.3c new file mode 100644 index 0000000000..de568f8e24 --- /dev/null +++ b/usr/src/man/man3c/inotify_rm_watch.3c @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH INOTIFY_RM_WATCH 3C "Sep 17, 2014" +.SH NAME +inotify_rm_watch \- remove a watch from an inotify instance +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> + +\fBint\fR \fBinotify_rm_watch\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIwd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinotify_rm_watch()\fR function removes the watch specified +by \fIwd\fR from the inotify instance associated with \fIfd\fR. +Removing a watch will induce an \fBIN_IGNORED\fR event; see +\fBinotify\fR(5) for details. + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, \fBinotify_add_watch()\fR returns the +watch descriptor associated with the new watch. +If an error occurs, -1 is returned and errno is set to indicate +the error. + +.SH ERRORS +.sp +.LP +\fBinotify_rm_watch()\fR will fail if: +.sp +.ne 2 +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +The \fIfd\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIfd\fR argument does not correspond to an +\fBinotify\fR(5) instance as initialized with +\fBinotify_init\fR(3C) or \fBinotify_init1\fR(3C), or +\fIwd\fR is not a valid watch for the specified inotify +instance. +.RE + +.sp +.SH NOTES +.sp +.LP + +While the \fBinotify\fR(5) facility is implemented for purposes of +offering compatibility for Linux-borne applications, native +applications may opt to use it instead of (or in addition to) the +\fBPORT_SOURCE_FILE\fR capability of event ports. See +\fBinotify\fR(5) for details and restrictions. + +.SH SEE ALSO +.sp +.LP +\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_get\fR(3C), +\fBinotify\fR(5) diff --git a/usr/src/man/man3c/lockf.3c b/usr/src/man/man3c/lockf.3c index 3b698f60a7..818dab24a2 100644 --- a/usr/src/man/man3c/lockf.3c +++ b/usr/src/man/man3c/lockf.3c @@ -1,4 +1,5 @@ '\" te +.\" Copyright 2015 Joyent, Inc. .\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. @@ -7,9 +8,9 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH LOCKF 3C "May 27, 2014" +.TH LOCKF 3C "Feb 16, 2015" .SH NAME -lockf \- record locking on files +lockf \- POSIX-style record locking on files .SH SYNOPSIS .LP .nf @@ -22,7 +23,7 @@ lockf \- record locking on files .sp .LP The \fBlockf()\fR function allows sections of a file to be locked; advisory or -mandatory write locks depending on the mode bits of the file (see +mandatory write locks depending on the mode bits of the file (see \fBchmod\fR(2)). Calls to \fBlockf()\fR from other threads that attempt to lock the locked file section will either return an error value or be put to sleep until the resource becomes unlocked. All the locks for a process are removed @@ -54,10 +55,10 @@ All other values of \fIfunction\fR are reserved for future extensions and will result in an error if not implemented. .sp .LP -\fBF_TEST\fR is used to detect if a lock by another process is present on the -specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock a section of a file -if the section is available. \fBF_ULOCK\fR removes locks from a section of the -file. +\fBF_TEST\fR is used to detect if a lock by another process or open file handle +is present on the specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock +a section of a file if the section is available. \fBF_ULOCK\fR removes locks +from a section of the file. .sp .LP The \fIsize\fR argument is the number of contiguous bytes to be locked or diff --git a/usr/src/man/man3c/madvise.3c b/usr/src/man/man3c/madvise.3c index dd2a72823b..91305f6fe6 100644 --- a/usr/src/man/man3c/madvise.3c +++ b/usr/src/man/man3c/madvise.3c @@ -22,7 +22,10 @@ The \fBmadvise()\fR function advises the kernel that a region of user mapped memory in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) will be accessed following a type of pattern. The kernel uses this information to optimize the procedure for manipulating and maintaining the resources associated with the -specified mapping range. +specified mapping range. In general (and true to the name of the function), +the advice is merely advisory, and the only user-visible ramifications +are in terms of performance, not semantics. Note that +\fBMADV_PURGE\fR is an exception to this; see below for details. .sp .LP Values for \fIadvice\fR are defined in <\fBsys/mman.h\fR> as: @@ -38,6 +41,7 @@ Values for \fIadvice\fR are defined in <\fBsys/mman.h\fR> as: #define MADV_ACCESS_DEFAULT 0x6 /* default access */ #define MADV_ACCESS_LWP 0x7 /* next LWP to access heavily */ #define MADV_ACCESS_MANY 0x8 /* many processes to access heavily */ +#define MADV_PURGE 0x9 /* contents will be purged */ .fi .in -2 @@ -99,6 +103,12 @@ kernel would need to read in from the file. .RS 23n Tell the kernel that the specified address range is no longer needed, so the system starts to free the resources associated with the address range. +While the semantics of \fBMADV_DONTNEED\fR are similar to other systems, +they differ signifcantly from the semantics on Linux, where +\fBMADV_DONTNEED\fR will actually synchronously purge the address range, +and subsequent faults will load from either backing store or be +zero-filled on demand. If the peculiar Linux semantics are +desired, \fBMADV_PURGE\fR should be used in lieu of \fBMADV_DONTNEED\fR. .RE .sp @@ -122,6 +132,26 @@ This value cannot be used on mappings that have underlying file objects. .sp .ne 2 .na +\fB\fBMADV_PURGE\fR\fR +.ad +.RS 23n +Tell the kernel to purge the specified address range. The mapping will +be retained, but the pages themselves will be destroyed; subsequent +faults on the range will result in the page being read from backing +store (if file-backed) or being zero-filled on demand (if anonymous). Note +that these semantics are generally inferior to \fBMADV_FREE\fR, which gives the +system more flexibility and results in better performance +when pages are, in fact, reused by the caller. Indeed, \fBMADV_PURGE\fR only +exists to provide an equivalent to the unfortunate +\fBMADV_DONTNEED\fR semantics found in Linux, upon which some programs +have (regretably) come to depend. In de novo applications, +\fBMADV_PURGE\fR should be avoided; \fBMADV_FREE\fR should always be +preferred. +.RE + +.sp +.ne 2 +.na \fB\fBMADV_ACCESS_LWP\fR\fR .ad .RS 23n diff --git a/usr/src/man/man3c/priv_addset.3c b/usr/src/man/man3c/priv_addset.3c index 7537cacde6..a695b87bcc 100644 --- a/usr/src/man/man3c/priv_addset.3c +++ b/usr/src/man/man3c/priv_addset.3c @@ -6,8 +6,9 @@ .TH PRIV_ADDSET 3C "Jan 28, 2005" .SH NAME priv_addset, priv_allocset, priv_copyset, priv_delset, priv_emptyset, -priv_fillset, priv_freeset, priv_intersect, priv_inverse, priv_isemptyset, -priv_isequalset, priv_isfullset, priv_ismember, priv_issubset, priv_union \- +priv_basicset, priv_fillset, priv_freeset, priv_intersect, priv_inverse, +priv_isemptyset, priv_isequalset, priv_isfullset, priv_ismember, +priv_issubset, priv_union \- privilege set manipulation functions .SH SYNOPSIS .LP @@ -39,6 +40,11 @@ privilege set manipulation functions .LP .nf +\fBvoid\fR \fBpriv_basicset\fR(\fBpriv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf \fBvoid\fR \fBpriv_fillset\fR(\fBpriv_set_t *\fR\fIsp\fR); .fi @@ -114,6 +120,9 @@ The \fBpriv_delset()\fR function removes the named privilege \fIpriv\fR from The \fBpriv_emptyset()\fR function clears all privileges from \fIsp\fR. .sp .LP +The \fBpriv_basicset()\fR function copies the basic privilege set to \fIsp\fR. +.sp +.LP The \fBpriv_fillset()\fR function asserts all privileges in \fIsp\fR, including the privileges not currently defined in the system. .sp diff --git a/usr/src/man/man3c/psignal.3c b/usr/src/man/man3c/psignal.3c index 655dedb022..a977fb6df4 100644 --- a/usr/src/man/man3c/psignal.3c +++ b/usr/src/man/man3c/psignal.3c @@ -1,16 +1,17 @@ '\" te .\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. .\" Copyright 2015 Circonus, Inc. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PSIGNAL 3C "Mar 31, 2005" +.TH PSIGNAL 3C "Aug 14, 2014" .SH NAME psignal, psiginfo \- system signal messages .SH SYNOPSIS .LP .nf -#include <siginfo.h> +#include <signal.h> \fBvoid\fR \fBpsignal\fR(\fBint\fR \fIsig\fR, \fBconst char *\fR\fIs\fR); .fi @@ -28,7 +29,9 @@ that may have been passed as the first argument to a signal handler. The \fIpinfo\fR argument is a pointer to a \fBsiginfo\fR structure that may have been passed as the second argument to an enhanced signal handler. See \fBsigaction\fR(2). The argument string \fIs\fR is printed first, followed by a -colon and a blank, followed by the message and a \fBNEWLINE\fR character. +colon and a blank, followed by the message and a \fBNEWLINE\fR character. If +\fBs\fR is the value \fBNULL\fR or an empty string, then nothing is printed for +the user's string and the colon and blank are omitted. .SH USAGE .LP Messages printed from these functions are in the native language specified by diff --git a/usr/src/man/man3c/signalfd.3c b/usr/src/man/man3c/signalfd.3c new file mode 100644 index 0000000000..43699a50a5 --- /dev/null +++ b/usr/src/man/man3c/signalfd.3c @@ -0,0 +1,192 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" Copyright 2015, Joyent, Inc. +.\" +.Dd "Jun 15, 2015" +.Dt SIGNALFD 3C +.Os +.Sh NAME +.Nm signalfd +.Nd create or modify a file descriptor for signal handling +.Sh SYNOPSIS +.In sys/signalfd.h +. +.Ft int +.Fo signalfd +.Fa "int fd" +.Fa "const sigset_t *mask" +.Fa "int flags" +.Fc +. +.Sh DESCRIPTION +The +.Fn signalfd +function returns a file descriptor that can be used +for synchronous consumption of signals. The file descriptor can be operated +upon via +.Xr read 2 +and the facilities that notify of file descriptor activity (e.g. +.Xr poll 2 , +.Xr port_get 3C , +.Xr epoll_wait 3C +). To dispose of the instance +.Xr close 2 +should be called on the file descriptor. +.Pp +If the +.Va fd +argument is -1, a new signalfd file descriptor will be +returned, otherwise the +.Va fd +argument should be an existing signalfd file descriptor whose signal mask will +be updated. +.Pp +The +.Va mask +argument specifies the set of signals that are relevant to the file descriptor. +It may be manipulated with the standard signal set manipulation functions +documented in +.Xr sigsetops 3C . +Signals in the mask which cannot be caught (e.g. +.Fa SIGKILL ) +are ignored. +.Pp +The +.Va flags +argument specifies additional parameters for the instance, and can have any of +the following values: +.Bl -tag -width Dv +.It Sy SFD_CLOEXEC +Instance will be closed upon an +.Xr exec 2 ; +see description for +.Fa O_CLOEXEC +in +.Xr open 2 . +.It Sy SFD_NONBLOCK +Instance will be set to be non-blocking. A +.Xr read 2 +on a signalfd instance that has been initialized with +.Fa SFD_NONBLOCK , +or made non-blocking in other ways, will return +.Er EAGAIN +in lieu of blocking if there are no signals from the +.Va mask +that are pending. +.El +.Pp +As with +.Xr sigwait 2 , +reading a signal from the file descriptor will consume the signal. The signals +used with signalfd file descriptors are normally first blocked so that their +handler does not run when a signal arrives. If the signal is not blocked the +behavior matches that of +.Xr sigwait 2 ; +if a +.Xr read 2 +is pending then the signal is consumed by the read, otherwise the signal is +consumed by the handler. +.Pp +The following operations can be performed upon a signalfd file descriptor: +.Bl -tag -width Dv +.It Sy read(2) +Reads and consumes one or more of the pending signals that match the file +descriptor's +.Va mask . +The read buffer must be large enough to hold one or more +.Vt signalfd_siginfo +structures, which is described below. +.Xr read 2 +will block if there are no matching signals pending, or return +.Er EAGAIN +if the instance was created with +.Fa SFD_NONBLOCK . +After a +.Xr fork 2 , +if the child reads from the descriptor it will only consume signals from itself. +.It Sy poll(2) +Provide notification when one of the signals from the +.Va mask +arrives. +.Fa POLLIN +and +.Fa POLLRDNORM +will be set. +.It Sy close(2) +Closes the desriptor. +.El +.Pp +The +.Vt signalfd_siginfo +structure returned from +.Xr read 2 +is a fixed size 128 byte structure defined as follows: +.Bd -literal +typedef struct signalfd_siginfo { + uint32_t ssi_signo; /* signal from signal.h */ + int32_t ssi_errno; /* error from errno.h */ + int32_t ssi_code; /* signal code */ + uint32_t ssi_pid; /* PID of sender */ + uint32_t ssi_uid; /* real UID of sender */ + int32_t ssi_fd; /* file descriptor (SIGIO) */ + uint32_t ssi_tid; /* unused */ + uint32_t ssi_band; /* band event (SIGIO) */ + uint32_t ssi_overrun; /* unused */ + uint32_t ssi_trapno; /* trap number that caused signal */ + int32_t ssi_status; /* exit status or signal (SIGCHLD) */ + int32_t ssi_int; /* unused */ + uint64_t ssi_ptr; /* unused */ + uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */ + uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */ + uint64_t ssi_addr; /* address that generated signal */ + uint8_t ssi_pad[48]; /* pad size to 128 bytes */ +} signalfd_siginfo_t; +.Ed +.Sh RETURN VALUES +Upon succesful completion, a file descriptor associated with the instance +is returned. Otherwise, -1 is returned and errno is set to indicate the error. +When +.Va fd +is not -1 and there is no error, the value of +.Va fd +is returned. +.Sh ERRORS +The +.Fn signalfd function +will fail if: +.Bl -tag -width Er +.It Er EBADF +The +.Va fd +descriptor is invalid. +.It Er EFAULT +The +.Va mask +address is invalid. +.It Er EINVAL +The +.Va fd +descriptor is not a signalfd descriptor or the +.Va flags +are invalid. +.It Er EMFILE +There are currently +.Va OPEN_MAX +file descriptors open in the calling process. +.It Er ENODEV +Unable to allocate state for the file descriptor. +.El +.Sh SEE ALSO +.Xr poll 2 , +.Xr sigwait 2 , +.Xr sigsetops 3C , +.Xr sigwaitinfo 3C , +.Xr signal.h 3HEAD diff --git a/usr/src/man/man3c/timerfd_create.3c b/usr/src/man/man3c/timerfd_create.3c new file mode 100644 index 0000000000..167b905d1e --- /dev/null +++ b/usr/src/man/man3c/timerfd_create.3c @@ -0,0 +1,181 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH TIMERFD 3C "Feb 23, 2015" +.SH NAME +timerfd_create, timerfd_settime, timerfd_gettime \- create and manipulate +timers via a file descriptor interface +.SH SYNOPSIS + +.LP +.nf +#include <sys/timerfd.h> + +\fBint\fR \fBtimerfd_create\fR(\fBint\fR \fIclockid\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBtimerfd_settime\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIflags\fR, + \fBconst struct itimerspec *restrict\fR \fIvalue\fR, + \fBstruct itimerspec *restrict\fR \fIovalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBtimerfd_gettime\fR(\fBint\fR \fIfd\fR, \fBstruct itimerspec *\fR\fIvalue\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These routines create and manipulate timers in which events are associated +with a file descriptor, allowing for timer-based events to be used +in file-descriptor based facilities like +\fBpoll\fR(2), \fBport_get\fR(3C) or \fBepoll_wait\fR(3C). + +The \fBtimerfd_create()\fR function creates a timer with the clock +type specified by \fIclockid\fR. The \fBCLOCK_REALTIME\fR and +\fBCLOCK_HIGHRES\fR clock types, as defined in \fBtimer_create\fR(3C), +are supported by \fBtimerfd_create()\fR. (Note that \fBCLOCK_MONOTONIC\fR +may be used as an alias for \fBCLOCK_HIGHRES\fR.) + +.sp +The \fIflags\fR argument specifies additional parameters for the +timer instance, and can have any of the following values: + +.sp +.ne 2 +.na +\fBTFD_CLOEXEC\fR +.ad +.RS 12n +Instance will be closed upon an +\fBexec\fR(2); see \fBopen\fR(2)'s description of \fBO_CLOEXEC\fR. +.RE + +.sp +.ne 2 +.na +\fBTFD_NONBLOCK\fR +.ad +.RS 12n +Instance will be set to be non-blocking. A \fBread\fR(2) on a +\fBtimerfd\fR instance that has been initialized with +\fBTFD_NONBLOCK\fR will return \fBEAGAIN\fR in lieu of blocking if the +timer has not expired since the last \fBtimerfd_settime()\fR or successful +\fBread()\fR. +.RE + +.sp +The following operations can be performed upon a \fBtimerfd\fR instance: + +.sp +.ne 2 +.na +\fBread\fR(2) +.ad +.RS 12n +Atomically reads and clears the number of timer expirations since the +last successful \fBread\fR(2) or \fBtimerfd_settime()\fR. Upon success, +the number of expirations will be copied into the eight byte buffer +passed to the system call. If there have been no expirations of the +timer since the last successful \fBread\fR(2) or \fBtimerfd_settime()\fR, +\fBread\fR(2) will block until at least the next expiration, +or return \fBEAGAIN\fR if the instance was created with +\fBTFD_NONBLOCK\fR. Note that if multiple threads are blocked in +\fBread\fR(2) for the same timer, only one of them will return upon +a single timer expiration. + +If the buffer specified to \fBread\fR(2) is less than +eight bytes in length, \fBEINVAL\fR will be returned. +.RE + +.sp +.ne 2 +.na +\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C) +.ad +.RS 12n +Provide notification when the timer expires or has expired in the past without +a more recent \fBread\fR(2). Note that threads being simultaneously +blocked in \fBread\fR(2) and \fBpoll\fR(2) (or equivalents) for the same +timer constitute an application-level race; on a timer expiration, +the thread blocked in \fBpoll\fR(2) may or may not return depending on how +it is scheduled with respect to the thread blocked in \fBread\fR(2). +.RE + +.sp +.ne 2 +.na +\fBtimerfd_gettime()\fR +.ad +.RS 12n +Returns the amount of time until the next timer expiration, with the +same functional signature and semantics as \fBtimer_gettime\fR(3C). +.RE + +.sp +.ne 2 +.na +\fBtimerfd_settime()\fR +.ad +.RS 12n +Sets or disarms the timer, with the +same functional signature and semantics as \fBtimer_settime\fR(3C). +.RE + +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, a file descriptor associated with the instance +is returned. Otherwise, -1 is returned and errno +is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtimerfd_create()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +The \fIflags\fR are invalid. +.RE + +.sp +.ne 2 +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +There are currently {\fBOPEN_MAX\fR} file descriptors open in the calling +process. +.RE + +.sp +.ne 2 +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +The \fIclock_id\fR, is \fBCLOCK_HIGHRES\fR and the +{\fBPRIV_PROC_CLOCK_HIGHRES\fR} is not asserted in the effective set of the +calling process. +.RE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBport_get\fR(3C), \fBepoll_wait\fR(3C), +\fBtimer_create\fR(3C), \fBtimer_gettime\fR(3C), \fBtimer_settime\fR(3C), +\fBprivileges\fR(5), \fBtimerfd\fR(5) + diff --git a/usr/src/man/man3dlpi/Makefile b/usr/src/man/man3dlpi/Makefile index cdd24216bd..4c5448f0be 100644 --- a/usr/src/man/man3dlpi/Makefile +++ b/usr/src/man/man3dlpi/Makefile @@ -41,10 +41,12 @@ MANFILES= dlpi_arptype.3dlpi \ dlpi_walk.3dlpi MANLINKS= dlpi_disabmulti.3dlpi \ + dlpi_open_zone.3dlpi \ dlpi_promiscoff.3dlpi dlpi_disabmulti.3dlpi := LINKSRC = dlpi_enabmulti.3dlpi +dlpi_open_zone.3dlpi := LINKSRC = man3dlpi/dlpi_open.3dlpi dlpi_promiscoff.3dlpi := LINKSRC = dlpi_promiscon.3dlpi .KEEP_STATE: diff --git a/usr/src/man/man3dlpi/dlpi_open.3dlpi b/usr/src/man/man3dlpi/dlpi_open.3dlpi index 8129a75404..489f66066a 100644 --- a/usr/src/man/man3dlpi/dlpi_open.3dlpi +++ b/usr/src/man/man3dlpi/dlpi_open.3dlpi @@ -1,9 +1,10 @@ '\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH DLPI_OPEN 3DLPI "Nov 17, 2008" +.TH DLPI_OPEN 3DLPI "Feb 24, 2014" .SH NAME dlpi_open \- open DLPI link .SH SYNOPSIS @@ -14,6 +15,9 @@ dlpi_open \- open DLPI link \fBint\fR \fBdlpi_open\fR(\fBconst char *\fR\fIlinkname\fR, \fBdlpi_handle_t *\fR\fIdhp\fR, \fBuint_t\fR \fIflags\fR); + +\fBint\fR \fBdlpi_open_zone\fR(\fBconst char *\fR\fIlinkname\fR, \fBconst char *\fR + \fIzonename\fR, \fBdlpi_handle_t *\fR\fIdhp\fR, \fBuint_t\fR \fIflags\fR); .fi .SH DESCRIPTION @@ -114,6 +118,18 @@ value ensures that \fBDLPI_ETIMEDOUT\fR is returned from a \fBlibdlpi\fR operation only in the event that the \fBDLPI\fR link becomes unresponsive. The timeout value can be changed with \fBdlpi_set_timeout\fR(3DLPI), although this should seldom be necessary. + +.sp +.LP +The \fBdlpi_open_zone()\fR function behaves as \fBdlpi_open()\fR, except that it +looks for the link specified by \fBlinkname\fR in the specified zone +\fBzonename\fR as opposed to the current zone. This function is only meaningful +from the global zone. Instead of scanning \fB/dev/net\fR, \fBdlpi_open_zone()\fR +scans \fB/dev/net/zone/<\fIzonename\fR> for the data link and +\fB/dev/ipnet/zone/<\fIzonename\fR> when DLPI_DEVIPNET is present in +\fBflags\fR. If a NULL or empty string is passed into \fBdlpi_open_zone()\fR, it +will behave as though \fBdlpi_open\fR has been called. + .SH RETURN VALUES .sp .LP @@ -124,7 +140,7 @@ section is returned. .SH ERRORS .sp .LP -The \fBdlpi_open()\fR function will fail if: +The \fBdlpi_open()\fR and \fBdlpi_open_zone()\fR function will fail if: .sp .ne 2 .na @@ -195,6 +211,17 @@ DLPI operation failed See \fBattributes\fR(5) for description of the following attributes: .sp +.LP +The \fBdlpi_open_zone()\fR function will fail if: +.sp +.ne 2 +.na +\fB\fBDLPI_EZONENAMEINVAL\fR\fR +.ad +.RS 25n +Invalid \fIzonename\fR argument +.RE + .sp .TS box; diff --git a/usr/src/man/man3lib/Makefile b/usr/src/man/man3lib/Makefile index 48abd74fd8..7dc5bfb66d 100644 --- a/usr/src/man/man3lib/Makefile +++ b/usr/src/man/man3lib/Makefile @@ -104,6 +104,7 @@ MANFILES= libMPAPI.3lib \ libumem.3lib \ libuuid.3lib \ libvolmgt.3lib \ + libvnd.3lib \ libw.3lib \ libxnet.3lib \ liby.3lib diff --git a/usr/src/man/man3lib/libvnd.3lib b/usr/src/man/man3lib/libvnd.3lib new file mode 100644 index 0000000000..ead69ff82e --- /dev/null +++ b/usr/src/man/man3lib/libvnd.3lib @@ -0,0 +1,690 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH LIBVND 3LIB "Mar 06, 2014" +.SH NAME +libvnd \- vnd library + +.SH SYNOPSIS +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> +.fi + +.SH DESCRIPTION +.LP +The libvnd library provides a stable and programmatic interface to +vnd(7D) devices. vnd devices provide the means for creating a layer two +interface over a data link, similar to the use of libdlpi(3LIB) and +IP(7P). In dlpi parlance, a vnd device obtains data from all service +attachment points (SAP). For ethernet devices, this means that a vnd +device sends and receives traffic for all ethertypes. It is intended to +be used for services such as virtual machines which emulate layer two +devices. + +.LP +Handles to vnd(7D) devices are obtained through the use of vnd_create +and vnd_open. With a handle, I/O can be performed and properties on the +device can be set and retrieved. I/O on devices should be performed +through the vnd_frameio_read and vnd_frameio_write functions. A file +descriptor suitable for use with event ports and polling may be obtained +through vnd_pollfd. Handles are relinquished through calls to vnd_close; +however, devices will persist until vnd_unlink has been called. + +.LP +The rest of this manual documents the interfaces, properties, errors, +and threading model for libvnd. The in-depth description of individual +interfaces, their arguments, and examples, are in manual pages for each +provided interface. + + +.SH INTERFACES +.sp +.LP + +The shared object libvnd.so.1 provides the public interfaces defined +below. See Intro(3) for additional information on shared object +interfaces. Individual functions are documented in their own manual +pages. + +.sp +.TS +l l +l l . +vnd_create vnd_errno +vnd_open vnd_syserrno +vnd_unlink vnd_strerror +vnd_close vnd_strsyserror +vnd_pollfd vnd_walk +vnd_prop_get vnd_prop_set +vnd_prop_iter vnd_prop_writeable +vnd_frameio_read vnd_frameio_write +.TE + +.SH PROPERTIES + +.LP +The following table summarizes properties of a vnd device. The +properties can be retrieved and set with the functions +vnd_prop_get(3VND) and vnd_prop_set(3VND). Following the table, the +structures and properties are described in greater detail. + +.nf + +-------------------+---------------------+-------+ + | PROPERTY | STRUCTURE | PERM | + +-------------------+---------------------+-------+ + | VND_PROP_RXBUF | vnd_prop_buf_t | R/W | + +-------------------+---------------------+-------+ + | VND_PROP_TXBUF | vnd_prop_buf_t | R/W | + +-------------------+---------------------+-------+ + | VND_PROP_MAXBUF | vnd_prop_buf_t | R/- | + +-------------------+---------------------+-------+ + | VND_PROP_MINTU | vnd_prop_buf_t | R/- | + +-------------------+---------------------+-------+ + | VND_PROP_MAXTU | vnd_prop_buf_t | R/- | + +-------------------+---------------------+-------+ +.fi + +.SS Structures + +.LP +The vnd_prop_buf_t structure has the following members: + +.in +2 +.nf +uint64_t vpb_size; +.fi +.in -2 + +.LP +The vpb_size member refers to a size in bytes. When getting a property, +it represents the size of that property, when setting a property, it is +the size to set the property to. + + +.SS Property Descriptions +.sp +.ne 2 +.na +rxbuf +.ad +.sp .6 +.RS 4n +A read/write property that controls the size of the receive buffer for +the device. All received data enters the receive buffer until a consumer +consumes it. If adding a received frame would exceed the size of the +receive buffer, then that frame will be dropped. The maximum size of the +buffer is limited by the 'maxsize' property. +.RE + +.sp +.ne 2 +.na +txbuf +.ad +.sp .6 +.RS 4n +A read/write property that controls the size of the transmit buffer. All +in-flight transmitted data must be able to fix into the transmit buffer +to deal with potential flow control events. If there is not enough space +in the transmit buffer, transmit related I/O operations will either +block or fail based on whether or not O_NONBLOCK or O_NDELAY were set +with fcntl(2). +.RE + +.sp +.ne 2 +.na +maxsize +.ad +.sp .6 +.RS 4n +A read only property that describes the maximum size of buffers in the +system. Properties such as rxbuf and txbuf cannot be set beyond this. +.RE + +.sp +.ne 2 +.na +mintu +.ad +.sp .6 +.RS 4n +A read only property that describes the minimum size of a frame +transmitted to the underlying data link. Note that the minimum listed +here may be less than the size of a valid layer two frame and therefore +may be dropped. A frame smaller than this value will be rejected by vnd. +.RE + +.sp +.ne 2 +.na +maxtu +.ad +.sp .6 +.RS 4n +A read only property that describes the maximum size of +a frame transmitted to the underlying data link. A frame +larger than this value will be rejected by vnd. +.RE + + +.SH ERRORS +.sp +.LP +Most interfaces provided by libvnd provide a means to retrieve a +vnd_errno_t that describes an error that has occurred. The manuals for +individual interfaces describe whether or not this additional error +information is available and how to retrieve it. The following is a +complete list of the error numbers and their names as defined in +<sys/vnd_errno.h>. Any entries not listed here are private to the +implementation and may change at any time. + +.sp +.ne 2 +.na +0 VND_E_SUCCESS +.ad +.RS 23n +no error +.sp +This indicates that the operation completed successfully. +.RE + +.sp +.ne 2 +.na +1 VND_E_NOMEM +.ad +.RS 23n +not enough memory available +.sp +Insufficient memory was available. This is the equivalent of the +standard system errno ENOMEM. +.RE + +.sp +.ne 2 +.na +2 VND_E_NODATALINK +.ad +.RS 23n +no such datalink +.sp +The data link requested to be used as part of vnd_create does not exist +in the requested zone. +.RE + +.sp +.ne 2 +.na +3 VND_E_NOTETHER +.ad +.RS 23n +datalink not of type DL_ETHER +.sp +The data link used as part of a call to vnd_create is not an Ethernet +device. vnd_create only works with Ethernet devices at this time. +.RE + +.sp +.ne 2 +.na +4 VND_E_DLPIINVAL +.ad +.RS 23n +unknown dlpi failure +.sp +An unexpected DLPI message was received during vnd device +initialization. +.RE + +.sp +.ne 2 +.na +5 VND_E_ATTACHFAIL +.ad +.RS 23n +DL_ATTACH_REQ failed +.sp +During vnd device initialization, the dlpi call to attach to the +requested data link failed. +.RE + +.sp +.ne 2 +.na +6 VND_E_BINDFAIL +.ad +.RS 23n +DL_BIND_REQ failed +.sp + +During vnd device initialization, the dlpi call to bind to a service +attachment point on the data link failed. +.RE + +.sp +.ne 2 +.na +7 VND_E_PROMISCFAIL +.ad +.RS 23n +DL_PROMISCON_REQ failed +.sp + +During vnd device initialization, the dlpi call to enable promiscuous +mode on the underlying device failed. +.RE + +.sp +.ne 2 +.na +8 VND_E_DIRECTFAIL +.ad +.RS 23n +DLD_CAPAB_DIRECT enable failed +.sp +During vnd device initialization, the dlpi call to enable the DLD fast +path failed. +.RE + +.sp +.ne 2 +.na +9 VND_E_CAPACKINVAL +.ad +.RS 23n +bad datalink capability +.sp +During vnd device initialization, the kernel responded with an invalid +capability acknowledgement. +.RE + +.sp +.ne 2 +.na +10 VND_E_SUBCAPINVAL +.ad +.RS 23n +bad datalink subcapability +.sp +During vnd device initialization, the kernel responded with an invalid +sub-capability. +.RE + +.sp +.ne 2 +.na +11 VND_E_DLDBADVERS +.ad +.RS 23n +bad dld version +.sp +The vnd(7D) module does not support the version of the dld capability +that the kernel sent. As such, the data path could not be brought up and +the device could not be fully initialized. +.RE + +.sp +.ne 2 +.na +12 VND_E_KSTATCREATE +.ad +.RS 23n +failed to create kstats +.sp +During vnd device initialization, the necessary kstats could not be +created. +.RE + +.sp +.ne 2 +.na +13 VND_E_NODEV +.ad +.RS 23n +no such vnd link +.sp +During device initialization, the requested character device did not +exist. +.RE + +.sp +.ne 2 +.na +14 VND_E_NONETSTACK +.ad +.RS 23n +netstack doesn't exist +.sp +During device initialization, the networking stack for the device did +not exist. +.RE + +.sp +.ne 2 +.na +15 VND_E_ASSOCIATED +.ad +.RS 23n +device already associated +.sp +During vnd device initialization, the vnd STREAMS device was already +associated with another vnd device. +.RE + +.sp +.ne 2 +.na +16 VND_E_ATTACHED +.ad +.RS 23n +device already attached +.sp +The given vnd device has already been created over a data link and +cannot be created over another one. +.RE + +.sp +.ne 2 +.na +17 VND_E_LINKED +.ad +.RS 23n +device already linked +.sp +The given vnd device has already been given a name and bound into the +file system name space. +.RE + +.sp +.ne 2 +.na +18 VND_E_BADNAME +.ad +.RS 23n +invalid name +.sp +The requested name is not a valid name. Valid names are alphanumeric +ascii names, along with the following ascii characters: ':', '\-', and +\'_'. Names must be less than LIBVND_NAMELEN bytes including the null +terminator. +.RE + +.sp +.ne 2 +.na +19 VND_E_PERM +.ad +.RS 23n +permission denied +.sp +A request was made from a non-global zone to manipulate a vnd device +that belongs to a different zone. +.RE + +.sp +.ne 2 +.na +20 VND_E_NOZONE +.ad +.RS 23n +no such zone +.sp +A request was made which targeted a zone that did not exist. +.RE + +.sp +.ne 2 +.na +21 VND_E_STRINIT +.ad +.RS 23n +failed to initialize vnd stream module +.sp +During vnd device initialization, the vnd STREAMS module could not be +pushed onto the data link's stream head. +.RE + +.sp +.ne 2 +.na +22 VND_E_NOTATTACHED +.ad +.RS 23n +device not attached +.sp +A request was made that requires a vnd device be attached to a data +link, such as a call to change a property. The device was not attached +to a data link. +.RE + +.sp +.ne 2 +.na +23 VND_E_NOTLINKED +.ad +.RS 23n +device not linked +.sp +A request was made to a vnd device that requires the vnd device to be +named and present in /dev. The given device was not linked into /dev at +the time of the call. +.RE + +.sp +.ne 2 +.na +24 VND_E_LINKEXISTS +.ad +.RS 23n +another device has the same link name +.sp +When trying to link a given vnd device into a zones /dev name space, +another device already exists with the same name. +.RE + +.sp +.ne 2 +.na +25 VND_E_MINORNODE +.ad +.RS 23n +failed to create minor node +.sp +While trying to link a vnd device into the /devices and /dev name space, +the call to ddi_create_minor_node() failed. +.RE + +.sp +.ne 2 +.na +26 VND_E_BUFTOOBIG +.ad +.RS 23n +requested buffer size is too large +.sp +The requested buffer size exceeds the maximum valid value for the given +property. +.RE + +.sp +.ne 2 +.na +27 VND_E_BUFTOOSMALL +.ad +.RS 23n +requested buffer size is too small +.sp +The requested buffer size is less than the minimum buffer size. This +generally occurs when making the buffer size less than the maximum +transmission unit. +.RE + +.sp +.ne 2 +.na +28 VND_E_DLEXCL +.ad +.RS 23n +unable to obtain exclusive access to dlpi link, link busy +.sp +When a vnd device is created, it expects exclusive active access to the +device. If any other active dlpi consumers, such as IP, are already +using the device, then the vnd device will not be created. Passive +consumers, such as snoop, can still use a device that has been +exclusively opened. +.RE + +.sp +.ne 2 +.na +28 VND_E_DIRECTNOTSUP +.ad +.RS 23n +DLD direct capability not supported over data link +.sp +The data link that the vnd device was created over does not supported +the DLD Direct capability. As such, the data path could not be +initialized. +.RE + +.sp +.ne 2 +.na +30 VND_E_BADPROPSIZE +.ad +.RS 23n +invalid property size +.sp +The size of the data passed into vnd_prop_get or vnd_prop_set is +incorrect and does not match the expected data size. +.RE + +.sp +.ne 2 +.na +31 VND_E_BADPROP +.ad +.RS 23n +invalid property +.sp +An unknown property identifier was specified. For a list of valid +properties, see the section above entitled "PROPERTIES". +.RE + +.sp +.ne 2 +.na +32 VND_E_PROPRDONLY +.ad +.RS 23n +property is read only +.sp +An operation tried to update the value of a read only property. For a +list of which properties are read only and which are readable and +writeable, see the section above entitled "PROPERTIES". +.RE + +.sp +.ne 2 +.na +33 VND_E_SYS +.ad +.RS 23n +unexpected system error +.sp +This indicates that there is no vnd specific error available and that +the system errno is valid. The system errno can be obtained and printed +through vnd_syserrno and vnd_strsyserror. The possible values and their +meanings are documented in Intro(2). +.RE + +.sp +.ne 2 +.na +34 VND_E_CAPABPASS +.ad +.RS 23n +capabilities invalid, pass-through module detected +.sp +While negotiating capabilities, a pass-through module was detected and +the capability had to be discarded. Because of this, the data path could +not be initialized. +.RE + + +.SH THREADING + +.LP +The libvnd library is not truly MT-safe. MT-safety is provided on +the granularity of a given vnd_handle_t. Operations on a single +vnd_handle_t are unsafe; however, operations on different handles are +MT-safe. If a single vnd_handle_t is used by multiple threads, it +is the caller's responsibility to provide locking to ensure that +multiple threads aren't simultaneously calling into libvnd on a +single handle. + + +.SH FILES +.sp +.ne 2 +.na +/usr/lib/libvnd.so.1 +.ad +.RS 27n +shared object +.RE + +.sp +.ne 2 +.na +/usr/lib/64/libvnd.so.1 +.ad +.RS 27n +64-bit shared object +.RE + +.SH ATTRIBUTES + +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See "THREADING" +.TE + +.SH SEE ALSO + +.sp +.LP +attributes(5), Intro(2), fcntl(2), Intro(3), fcntl.h(3HEAD), libdlpi(3LIB), port_create(3C), vnd(7D) +.sp +.LP +vnd_close(3VND), vnd_create(3VND), vnd_errno(3VND), +vnd_frameio_read(3VND), vnd_frameio_write(3VND), vnd_open(3VND) +vnd_pollfd(3VND), vnd_prop_get(3VND), vnd_prop_iter(3VND), +vnd_prop_set(3VND), +vnd_prop_writeable(3VND), vnd_walk(3VND) diff --git a/usr/src/man/man3sysevent/sysevent_get_vendor_name.3sysevent b/usr/src/man/man3sysevent/sysevent_get_vendor_name.3sysevent index 5400e62be9..b17cb69389 100644 --- a/usr/src/man/man3sysevent/sysevent_get_vendor_name.3sysevent +++ b/usr/src/man/man3sysevent/sysevent_get_vendor_name.3sysevent @@ -1,9 +1,10 @@ '\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH SYSEVENT_GET_VENDOR_NAME 3SYSEVENT "Jul 24, 2009" +.TH SYSEVENT_GET_VENDOR_NAME 3SYSEVENT "Jun 29, 2015" .SH NAME sysevent_get_vendor_name, sysevent_get_pub_name, sysevent_get_pid \- get vendor name, publisher name or processor ID of event @@ -23,11 +24,10 @@ name, publisher name or processor ID of event .LP .nf -\fBpid_t\fR \fBsysevent_get_pid\fR(\fBsysevent_t *\fR\fIev\fR); +\fBvoid\fR \fBsysevent_get_pid\fR(\fBsysevent_t *\fR\fIev\fR, \fBpid_t *\fR\fIpid\fR); .fi .SH PARAMETERS -.sp .ne 2 .na \fB\fIev\fR\fR @@ -37,14 +37,13 @@ handle to a system event object .RE .SH DESCRIPTION -.sp .LP The \fBsysevent_get_pub_name()\fR function returns the publisher name for the sysevent handle, \fIev\fR. The publisher name identifies the name of the publishing application or kernel subsystem of the sysevent. .sp .LP -The \fBsysevent_get_pid()\fR function returns the process ID for the publishing +The \fBsysevent_get_pid()\fR function sets the process ID for the publishing application or \fBSE_KERN_PID\fR for sysevents originating in the kernel. The publisher name and PID are useful for implementing event acknowledgement. .sp @@ -75,6 +74,7 @@ event handler. .nf char *vendor; char *pub; +pid_t pid; void event_handler(sysevent_t *ev) @@ -94,7 +94,9 @@ event_handler(sysevent_t *ev) free(pub); return; } - (void) kill(sysevent_get_pid(ev), SIGUSR1); + sysevent_get_pid(ev, &pid); + (void) kill(pid, SIGUSR1); + free(vendor); free(pub); } @@ -102,7 +104,6 @@ event_handler(sysevent_t *ev) .in -2 .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -120,10 +121,8 @@ MT-Level MT-Safe .TE .SH SEE ALSO -.sp .LP \fBmalloc\fR(3MALLOC), \fBattributes\fR(5) .SH NOTES -.sp .LP The \fBlibsysevent\fR interfaces do not work at all in non-global zones. diff --git a/usr/src/man/man3vnd/Makefile b/usr/src/man/man3vnd/Makefile new file mode 100644 index 0000000000..64abf9dcd6 --- /dev/null +++ b/usr/src/man/man3vnd/Makefile @@ -0,0 +1,70 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# +# Copyright (c) 2014, Joyent, Inc. All rights reserved. +# + +include $(SRC)/Makefile.master + +MANSECT= 3vnd + +MANFILES= vnd_create.3vnd \ + vnd_errno.3vnd \ + vnd_frameio_read.3vnd \ + vnd_pollfd.3vnd \ + vnd_prop_get.3vnd \ + vnd_prop_iter.3vnd \ + vnd_prop_writeable.3vnd \ + vnd_walk.3vnd + +MANLINKS= frameio_t.3vnd \ + framevec_t.3vnd \ + vnd_close.3vnd \ + vnd_frameio_write.3vnd \ + vnd_open.3vnd \ + vnd_prop_set.3vnd \ + vnd_prop_iter_f.3vnd \ + vnd_strerror.3vnd \ + vnd_strsyserror.3vnd \ + vnd_syserrno.3vnd \ + vnd_unlink.3vnd \ + vnd_walk_cb_f.3vnd + +# vnd_create.3vnd +vnd_open.3vnd := LINKSRC = vnd_create.3vnd +vnd_unlink.3vnd := LINKSRC = vnd_create.3vnd +vnd_close.3vnd := LINKSRC = vnd_create.3vnd + +# vnd_errno.3vnd +vnd_strerror.3vnd := LINKSRC = vnd_errno.3vnd +vnd_syserrno.3vnd := LINKSRC = vnd_errno.3vnd +vnd_strsyserror.3vnd := LINKSRC = vnd_errno.3vnd + +# vnd_frameio_read.3vnd +vnd_frameio_write.3vnd := LINKSRC = vnd_frameio_read.3vnd +framevec_t.3vnd := LINKSRC = vnd_frameio_read.3vnd +frameio_t.3vnd := LINKSRC = vnd_frameio_read.3vnd + +# vnd_prop_get.3vnd +vnd_prop_set.3vnd := LINKSRC = vnd_prop_get.3vnd + +# vnd_prop_iter.3vnd +vnd_prop_iter_f.3vnd := LINKSRC = vnd_prop_iter.3vnd + +# vnd_walk.3vnd +vnd_walk_cb_f.3vnd := LINKSRC = vnd_walk.3vnd + +.KEEP_STATE: + +include $(SRC)/man/Makefile.man + +install: $(ROOTMANFILES) $(ROOTMANLINKS) diff --git a/usr/src/man/man3vnd/vnd_create.3vnd b/usr/src/man/man3vnd/vnd_create.3vnd new file mode 100644 index 0000000000..d29237a60c --- /dev/null +++ b/usr/src/man/man3vnd/vnd_create.3vnd @@ -0,0 +1,280 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_CREATE 3VND "Feb 21, 2014" + +.SH NAME + +vnd_create, vnd_open, vnd_unlink, vnd_close \- create, open, and destroy +vnd devices + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +vnd_handle_t *vnd_create(const char *zonename, const char *datalink, + const char *linkname, vnd_errno_t *vnderr, int *syserr); + +vnd_handle_t *vnd_open(const char *zonename, const char *linkname, + vnd_errno_t *vnderr, int *syserr); + +int vnd_unlink(vnd_handle_t *vhp); + +void vnd_close(vnd_handle_t *vhp); +.fi + + +.SH DESCRIPTION +.LP +These functions create vnd devices, obtain handles to extant vnd +devices, and close handles to vnd devices, for use with the rest of +libvnd(3LIB). + +.LP +The vnd_create function creates a new vnd device in the zone specified +by zonename. The zone name argument may be null, in which case the +caller's current zone is used instead. The vnd device and data link it +is created over must both be in the same zone. The datalink argument +indicates the name of the DLPI data link to create the vnd device over. +The linkname argument indicates the name of the new vnd device. The +linkname argument must be less than VND_NAMELEN characters long, +excluding the null terminator. It should be an alphanumeric string. The +only non-alphanumeric characters allowed are ':', '-', and \'_'. +Neither the datalink argument nor linkname argument may be NULL. A +handle to the created device is returned to the caller. Once the +vnd_create function returns, the device can be subsequently opened with +a call to vnd_open. The named device persists until a call to vnd_unlink +or the containing zone is halted. Creating a vnd device requires +PRIV_SYS_NET_CONFIG as well as PRIV_RAWACCESS. The arguments vnderr and +syserr are used to obtain errors in the cases where the call to +vnd_create fails. Both arguments may be NULL pointers, in which case the +more detailed error information is discarded. + +.LP +The vnd_open function opens an existing vnd device and returns a +unique handle to that device. The vnd device to open is specified by +both zonename and linkname. The zonename argument specifies what zone +to look for the vnd device in. The linkname specifies the name of the +link. The zonename argument may be NULL. If it is, the current zone is +used. Similar to vnd_create, the integer values pointed to by the +arguments vnderr and syserr will be filled in with additional error +information in the cases where a call to vnd_open fails. Both +arguments may be NULL to indicate that the error information is not +requested, though this is not recommended. + +.LP +The vnd_unlink function unlinks the vnd device specified by the vnd +handle vhp. This unlink is similar to the use of unlink in a file +system. After a call to unlink, the vnd device will no longer be +accessible by callers to vnd_open and the name will be available for +use in vnd_create. However, the device will continue to exist until +all handles to the device have been closed. + +.LP +The vnd_close function relinquishes the vnd device referenced by the +handle vhp. After a call to vnd_close, the handle is invalidated and +must not be used by the consumer again. The act of calling vnd_close +on a handle does not remove the device. The device is persisted as +long as vnd_unlink has not been called on the device or the containing +zone has not been destroyed. + +.SH RETURN VALUES + +.LP +Upon successful completion, the functions vnd_create and vnd_open +return a pointer to a vnd_handle_t. This handle is used for all +subsequent library operations. If either function fails, then a NULL +pointer is returned and more detailed error information is filled into +the integers pointed to by vnderr and syserr. The vnderr and syserr +correspond to the values that would normally be returned by a call to +vnd_errno(3VND) and vnd_syserrno(3VND). For the full list of possible +errors see libvnd(3LIB). + +.LP +The vnd_unlink function returns zero on success and -1 on failure. On +failure, the vnd and system errnos are updated and available through +the vnd_errno(3VND) and vnd_syserrno(3VND) functions. + +.LP +The vnd_close function does not return any values nor does it set +vnderr or syserr. The handle passed to vnd_close can no longer be +used. + +.SH EXAMPLES +.LP +Example 1 Creating a device +.sp +.LP + +The following sample C program shows how to create a vnd device over +an existing datalink named "net0" that other applications can open +and use as "vnd0". + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr; + + /* Errors are considered fatal */ + vhp = vnd_create(NULL, "net0", "vnd0", &vnderr, &syserr); + + if (vhp == NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to create device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to create device: %s", + vnd_strerror(vnderr)); + return (1); + } + + (void) printf("successfully created vnd0\n"); + vnd_close(vhp); + return (0); +} +.fi +.in -2 + +.LP +Example 2 Opening an existing device in another zone +.sp +.LP + +The following sample C program opens the device named "vnd1" in the zone +named "turin" for further use. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr, ret; + + vhp = vnd_open("turin", "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + /* + * Use the device vnd1 with the handle vhp with any of + * the other interfaces documented in libvnd(3LIB) here. + * + * After an arbitrary amount of code, the program will + * set the variable ret with the exit code for the + * program and should execute the following code before + * returning. + */ + vnd_close(vhp); + return (ret); +} +.fi +.in -2 + + +.LP +Example 3 Removing a device +.sp +.LP + +The following sample C program removes a vnd device named vnd0. This +program makes it so no additional programs can access the device. +However, if anyone is actively using it, it will still exist, +similar to calling unlink(2). + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr, ret; + + vhp = vnd_open(NULL, "vnd0", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + if (vnd_unlink(vhp) != 0) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to unlink device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to unlink device: %s", + vnd_strerror(vnderr)); + ret = 1; + } else { + (void) printf("successfully unlinked vnd0!\n"); + ret = 0; + } + + vnd_close(vhp); + return (ret); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See "THREADING" in libvnd(3LIB) +.TE + +.SH SEE ALSO + +libvnd(3LIB), vnd_errno(3VND), vnd_syserrno(3VND), attributes(5), privileges(5) diff --git a/usr/src/man/man3vnd/vnd_errno.3vnd b/usr/src/man/man3vnd/vnd_errno.3vnd new file mode 100644 index 0000000000..ddd6126dd1 --- /dev/null +++ b/usr/src/man/man3vnd/vnd_errno.3vnd @@ -0,0 +1,170 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_ERRNO 3VND "Feb 21, 2014" + +.SH NAME + +vnd_errno, vnd_syserrno, vnd_strerror, vnd_strsyserror \- obtain and +translate vnd errors + + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +uint32_t vnd_errno(vnd_handle_t *vhp); + +const char *vnd_strerror(vnd_errno_t err); + +int vnd_syserrno(vnd_handle_t *vhp); + +const char *vnd_strsyserror(int syserr); +.fi + +.SH DESCRIPTION + +.LP +The libvnd(3LIB) library supports a complementary array of errors that +give more specific error information than the traditional set of +system errors available via errno(3C). When an error occurs, consumers +should call the vnd_errno function first and check its value. If the +value of the vnd_errno_t is VND_E_SYS, then the system errno should be +checked. If the vnd_errno_t is not VND_E_SYS, then the contents of the +system errno returned from vnd_syserrno are undefined. Both the vnd +and system errors are only valid for a given handle after a libvnd +library function returned an error and before another libvnd library +function is called on the same handle. The act of making an additional +function call with the same vnd_handle_t invalidates any prior vnd or +system error numbers. For the full list of valid vnd errors see +libvnd(3LIB). For the full list of valid system errors, see Intro(2). + +.LP +The vnd_errno and vnd_syserrno functions retrieve the most recent vnd +and syserr error number respectively from a vnd handle vhp. + +.LP +The vnd_strerror function translates a vnd_errno_t err to a +corresponding string and returns a pointer to that constant string. + +.LP +The vnd_syserrno function is analogous to the vnd_strerror function, +except that it translates a system error back to a string. + + +.SH RETURN VALUES + +.LP +The vnd_errno function returns a vnd_errno_t which contains the vnd +error information. + +.LP +The vnd_syserror function returns an integer which contains the system +error information. These values are the same as those returned by +errno(3C). + +.LP +The vnd_strerror function returns a pointer to a constant string. If +the error passed in is unknown, the string "unknown error" is +returned. + +.LP +The vnd_strsyserror function returns a pointer to the translated +constant string. If an unknown error number is passed, it returns the +string "Unknown error". If an error occurs, it returns a NULL pointer. + +.SH EXAMPLES + +.LP +Example 1 Obtaining errors from a vnd_handle_t + +.sp +.LP +The following sample C function, which can be incorporated into a larger +program, shows how to obtain the vnd and system errors from a +vnd_handle_t after a vnd interface on a handle failed. + +.sp +.in +2 +.nf +#include <libvnd.h> + +static void +print_errnos(vnd_handle_t *vhp) +{ + vnd_errno_t vnderr; + int syserr; + + vnderr = vnd_errno(vhp); + syserr = vnd_syserrno(vhp); + + (void) printf("vnd err: %d, sys err: %d\n", + vnderr, syserr); +} +.fi +.in -2 + +.LP +Example 2 A perror-like function + +.sp +.LP +The following sample C function which can be incorporated into a +larger program shows how to write a perror-like function to print +out error messages for a vnd device. + +.sp +.in +2 +.nf +#include <libvnd.h> + +static void +sample_perror(const char *msg, vnd_error_t vnderr, int syserr) +{ + (void) fprintf(stderr, "%s: %s", msg, + vnderr != VND_E_SYS ? vnd_strerror(vnderr) : + vnd_strsyserror(syserr)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See below +.TE + +.LP +The MT-Level of the functions vnd_strerror and vnd_strsyserror is +MT-Safe. See "THREADING" in libvnd(3LIB) for a discussion of the +MT-Level of vnd_errno and vnd_syserrno. + + +.SH SEE ALSO + +Intro(2), errno(3C), libvnd(3LIB), attributes(5) diff --git a/usr/src/man/man3vnd/vnd_frameio_read.3vnd b/usr/src/man/man3vnd/vnd_frameio_read.3vnd new file mode 100644 index 0000000000..5fc65c96a3 --- /dev/null +++ b/usr/src/man/man3vnd/vnd_frameio_read.3vnd @@ -0,0 +1,705 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_FRAMEIO_READ 3VND "Mar 06, 2014" + +.SH NAME + +vnd_frameio_read, vnd_frameio_write \- perform framed I/O to a vnd device + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +int vnd_frameio_read(vnd_handle_t *vhp, frameio_t *fiop); + +int vnd_frameio_write(vnd_handle_t *vhp, frameio_t *fiop); +.fi + +.SH DESCRIPTION +.LP +Framed I/O is a general means to manipulate data that is inherently +framed, meaning that there is a maximum frame size, but the data may +often be less than that size. As an example, an Ethernet device's MTU +describes the maximum frame size, but the size of an individual frame +is often much less. You can read a single frame at a time, or you can +read multiple frames in a single call. + +In addition, framed I/O allows the consumer to break individual frames +into a series of vectors. This is analogous to the use of an iovec(9S) +with readv(2) and writev(2). + +vnd_frameio_read performs a framed I/O read of the device represented by +the handle vhp, with the framed I/O data described by fiop. +vnd_frameio_write works in the same manner, except performing a write +instead of a read. + +.LP +The basic vector component of the frameio_t is the framevec_t. Each +framevec_t represents a single vector entry. An array of these is +present in the frameio_t. The framevec_t structure has the following +members: + +.in +2 +.nf +void *fv_buf /* data buffer */ +size_t fv_buflen; /* total size of buffer */ +size_t fv_actlen; /* amount of buffer consumed */ +.fi +.in -2 + +.LP +The fv_buf member points to a buffer which contains the data for this +individual vector. When reading, data is consumed from fv_buf. When +writing, data is written into fv_buf. + +The fv_buflen should indicate the total amount of data that is in the +buffer. When reading, it indicates the size of the buffer. It must be +set prior to calling vnd_frameio_read(). When writing, it indicates the +amount of data that is valid in the buffer. + +The fv_actlen is a read-only member. It is set on successful return of +the functions vnd_frameio_read and vnd_frameio_write. When reading, it +is updated with the amount of data that was read into fv_buf. When +writing, it is instead updated with the amount of data from fv_buf that +was actually consumed. Generally when writing data, a framevec_t will +either be entirely consumed or it will not be consumed at all. + + +.LP +A series of framevec_t's is encapsulated in a frameio_t. The frameio_t +structure has the following members: + +.in +2 +.nf +uint_t fio_version; /* current version */ +uint_t fio_nvpf; /* number of vectors in one frame */ +uint_t fio_nvecs; /* The total number of vectors */ +framevec_t fio_vecs[]; /* vectors */ +.fi +.in -2 + +.LP +The fio_version member represents the current version of the frameio_t. +The fio_version should be set to the macro FRAMEIO_CURRENT_VERSION, +which is currently 1. + +The members fio_nvpf and fio_nvecs describe the number of frames that +exist. fio_nvecs describes the total number of vectors that are present +in fio_vecs. The upper bound on this is described by FRAMEIO_NVECS_MAX +which is currently 32. fio_nvpf describe the number of vectors that +should be used to make up each frame. By setting fio_vecs to be an even +multiple of fio_nvpf, multiple frames can be read or written in a single +call. + +After a call to vnd_frameio_read or vnd_frameio_write fio_nvecs is +updated with total number of vectors read or written to. This value can +be divided by fio_nvpf to determine the total number of frames that were +written or read. + +.LP +Each frame can be broken down into a series of multiple vectors. As an +example, someone might want to break Ethernet frames into mac headers +and payloads. The value of fio_nvpf would be set to two, to indicate +that a single frame consists of two different vector components. The +member fio_nvecs describes the total number of frames. As such, the +value of fio_vecs divided by fio_nvpf describes the total number of +frames that can be consumed in one call. As a result of this, fio_nvpf +must evenly divide fio_vecs. If fio_nvpf is set to two and +fio_nvecs is set to ten, then a total of five frames can be processed +at once, each frame being broken down into two different vector +components. + +A given frame will never overflow the number of vectors described by +fio_nvpf. Consider the case where each vector component has a buffer +sized to 1518 bytes, fio_nvpf is set to one, and fio_nvecs is set to +three. If a call to vnd_frameio_read is made and four 500 byte Ethernet +frames come in, then each frame will be mapped to a single vector. The +500 bytes will be copied into fio_nvecs[i]->fio_buf and +fio_nvecs[i]->fio_actlen will be set to 500. To contrast this, if +readv(2) had been called, the first three frames would all be in the +first iov and the fourth frame's first eight bytes would be in the first +iov and the remaining in the second. + +.LP +The user must properly initialize fio_nvecs framevec_t's worth of the +fio_vecs array. When multiple vectors comprise a frame, fv_buflen data +is consumed before moving onto the next vector. Consider the case +where the user wants to break a vector into three different +components, an 18 byte vector for an Ethernet VLAN header, a 20 byte +vector for an IPv4 header, and a third 1500 byte vector for the +remaining payload. If a frame was received that only had 30 bytes, +then the first 18 bytes would fill up the first vector, the remaining +12 bytes would fill up the IPv4 header. If instead a 524 byte frame +came in, then the first 18 bytes would be placed in the first vector, +the next 24 bytes would be placed in the next vector, and the remaining +500 bytes in the third. + +.LP +The functions vnd_frameio_read and vnd_frameio_write operate in both +blocking and non-blocking mode. If either O_NONBLOCK or O_NDELAY have +been set on the file descriptor, then the I/O will behave in +non-blocking mode. When in non-blocking mode, if no data is available +when vnd_frameio_read is called, EAGAIN is returned. When +vnd_frameio_write is called in non-blocking mode, if sufficient buffer +space to hold all of the output frames is not available, then +vnd_frameio_write will return EAGAIN. To know when the given vnd device +has sufficient space, the device fires POLLIN/POLLRDNORM when data is +available for read and POLLOUT/POLLRDOUT when space in the buffer has +opened up for write. These events can be watched for through +port_associate(3C) and similar routines with a file descriptor returned +from vnd_polfd(3VND). + +.LP +When non-blocking mode is disabled, calls to vnd_frameio_read will +block until some amount of data is available. Calls to +vnd_frameio_write will block until sufficient buffer space is +available. + +.LP +Similar to read(2) and write(2), vnd_frameio_read and +vnd_frameio_write make no guarantees about the ordering of data when +multiple threads simultaneously call the interface. While the data +itself will be atomic, the ordering of multiple simultaneous calls is +not defined. + +.SH RETURN VALUES + +.LP +The vnd_frameio_read function returns zero on success. The member +fio_nvecs of fiop is updated with the total number of vectors that had +data read into them. Each updated framevec_t will have the buffer +pointed to by fv_buf filled in with data, and fv_actlen will be +updated with the amount of valid data in fv_buf. + +.LP +The vnd_frameio_write function returns zero on success. The member +fio_nvecs of fiop is updated with the total number of vectors that +were written out to the underlying datalink. The fv_actlen of each +vector is updated to indicate the amount of data that was written from +that buffer. + +.LP +On failure, both vnd_frameio_read and vnd_frameio_write return -1. The +vnd and system error numbers are updated and available via +vnd_errno(3VND) and vnd_syserrno(3VND). See ERRORS below for a list of +errors and their meaning. + + +.SH ERRORS +.LP +The functions vnd_frameio_read and vnd_frameio_write always set the +vnd error to VND_E_SYS. The following system errors will be +encountered: + +.sp +.ne 2 +.na +EAGAIN +.ad +.RS 10n +Insufficient system memory was available for the operation. +.sp +Non-blocking mode was enabled and during the call to vnd_frameio_read, +no data was available. Non-blocking mode was enabled and during the call +to vnd_frameio_write, insufficient buffer space was available. +.RE + +.sp +.ne 2 +.na +ENXIO +.ad +.RS 10n +The vnd device referred to by vhp is not currently attached to an +underlying data link and cannot send data. +.RE + +.sp +.ne 2 +.na +EFAULT +.ad +.RS 10n +The fiop argument points to an illegal address or the fv_buf members of +the framevec_t's associated with the fiop member fio_vecs point to +illegal addresses. +.RE + +.sp +.ne 2 +.na +EINVAL +.ad +.RS 10n +The fio_version member of fiop was unknown, the number of vectors +specified by fio_nvecs is zero or greater than FRAMEIO_NVECS_MAX, +fio_nvpf equals zero, fio_nvecs is not evenly divisible by fio_nvpf, or +a buffer in fio_vecs[] has set fv_buf or fv_buflen to zero. +.RE + + +.sp +.ne 2 +.na +EINTR +.ad +.RS 10n +A signal was caught during vnd_frameio_read or vnd_frameio_write, and no +data was transferred. +.RE + + +.sp +.ne 2 +.na +EOVERFLOW +.ad +.RS 10n +During vnd_frameio_read, the size of a frame specified by fiop->fio_nvpf +and fiop->fio_vecs[].fv_buflen cannot contain a frame. +.sp +In a ILP32 environment, more data than UINT_MAX would be set in +fv_actlen. +.RE + + +.sp +.ne 2 +.na +ERANGE +.ad +.RS 10n +During vnd_frameio_write, the size of a frame is less than the device's +minimum transmission unit or it is larger than the size of the maximum +transmission unit. +.RE + + +.SH EXAMPLES + +.LP +Example 1 Read a single frame with a single vector + +.sp +.LP +The following sample C program opens an existing vnd device named +"vnd0" in the current zone and performs a blocking read of a single +frame from it. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr, i; + frameio_t *fiop; + + fiop = malloc(sizeof (frameio_t) + sizeof (framevec_t)); + if (fiop == NULL) { + perror("malloc frameio_t"); + return (1); + } + fiop->fio_version = FRAMEIO_CURRENT_VERSION; + fiop->fio_nvpf = 1; + fiop->fio_nvecs = 1; + fiop->fio_vecs[0].fv_buf = malloc(1518); + fiop->fio_vecs[0].fv_buflen = 1518; + if (fiop->fio_vecs[0].fv_buf == NULL) { + perror("malloc framevec_t.fv_buf"); + free(fiop); + return (1); + } + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + free(fiop->fio_vecs[0].fv_buf); + free(fiop); + return (1); + } + + if (frameio_read(vhp, fiop) != 0) { + vnd_errno_t vnderr = vnd_errno(vhp); + int syserr = vnd_syserrno(vhp); + + /* Most consumers should retry on EINTR */ + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to read: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to read: %s", + vnd_strerror(vnderr)); + vnd_close(vhp); + free(fiop->fio_vecs[0].fv_buf); + free(fiop); + return (1); + } + + + /* Consume the data however it's desired */ + (void) printf("received %d bytes\n", fiop->fio_vecs[0].fv_actlen); + for (i = 0; i < fiop->fio_vecs[0].fv_actlen) + (void) printf("%x ", fiop->fio_vecs[0].fv_buf[i]); + + vnd_close(vhp); + free(fiop->fio_vecs[0].fv_buf); + free(viop); + return (0); +} +.fi +.in -2 + +.LP +Example 2 Write a single frame with a single vector +.sp +.LP +The following sample C program opens an existing vnd device named +"vnd0" in the current zone and performs a blocking write of a single +frame to it. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> +#include <string.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr; + frameio_t *fiop; + + fiop = malloc(sizeof (frameio_t) + sizeof (framevec_t)); + if (fiop == NULL) { + perror("malloc frameio_t"); + return (1); + } + fiop->fio_version = FRAMEIO_CURRENT_VERSION; + fiop->fio_nvpf = 1; + fiop->fio_nvecs = 1; + fiop->fio_vecs[0].fv_buf = malloc(1518); + if (fiop->fio_vecs[0].fv_buf == NULL) { + perror("malloc framevec_t.fv_buf"); + free(fiop); + return (1); + } + + /* + * Fill in your data however you desire. This is an entirely + * invalid frame and while the frameio write may succeed, the + * networking stack will almost certainly drop it. + */ + (void) memset(fiop->fio_vecs[0].fv_buf, 'r', 1518); + fiop->fio_vecs[0].fv_buflen = 1518; + + vhp = vnd_open(NULL, "vnd0", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + free(fiop->fio_vecs[0].fv_buf); + free(fiop); + return (1); + } + + if (frameio_write(vhp, fiop) != 0) { + /* Most consumers should retry on EINTR */ + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to write: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to write: %s", + vnd_strerror(vnderr)); + vnd_close(vhp); + free(fiop->fio_vecs[0].fv_buf); + free(fiop); + return (1); + } + + + (void) printf("wrote %d bytes\n", fiop->fio_vecs[0].fv_actlen); + + vnd_close(vhp); + free(fiop->fio_vecs[0].fv_buf); + free(viop); + return (0); +} +.fi +.in -2 + +.LP +Example 3 Read frames comprised of multiple vectors +.sp +.LP +The following sample C program is similar to example 1, except instead +of reading a single frame consisting of a single vector it reads +multiple frames consisting of two vectors. The first vector has room for +an 18 byte VLAN enabled Ethernet header and the second vector has room +for a 1500 byte payload. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr, i, nframes; + frameio_t *fiop; + + /* Allocate enough framevec_t's for 5 frames */ + fiop = malloc(sizeof (frameio_t) + sizeof (framevec_t) * 10); + if (fiop == NULL) { + perror("malloc frameio_t"); + return (1); + } + fiop->fio_version = FRAMEIO_CURRENT_VERSION; + fiop->fio_nvpf = 2; + fiop->fio_nvecs = 10; + for (i = 0; i < 10; i += 2) { + fiop->fio_vecs[i].fv_buf = malloc(18); + fiop->fio_vecs[i].fv_buflen = 18; + if (fiop->fio_vecs[i].fv_buf == NULL) { + perror("malloc framevec_t.fv_buf"); + /* Perform appropriate memory cleanup */ + return (1); + } + fiop->fio_vecs[i+1].fv_buf = malloc(1500); + fiop->fio_vecs[i+1].fv_buflen = 1500; + if (fiop->fio_vecs[i+1].fv_buf == NULL) { + perror("malloc framevec_t.fv_buf"); + /* Perform appropriate memory cleanup */ + return (1); + } + } + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + /* Perform appropriate memory cleanup */ + return (1); + } + + if (frameio_read(vhp, fiop) != 0) { + /* Most consumers should retry on EINTR */ + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to read: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to read: %s", + vnd_strerror(vnderr)); + vnd_close(vhp); + /* Perform appropriate memory cleanup */ + return (1); + } + + /* Consume the data however it's desired */ + nframes = fiop->fio_nvecs / fiop->fio_nvpf; + (void) printf("consumed %d frames!\n", nframes); + for (i = 0; i < nframes; i++) { + (void) printf("received %d bytes of Ethernet Header\n", + fiop->fio_vecs[i].fv_actlen); + (void) printf("received %d bytes of payload\n", + fiop->fio_vecs[i+1].fv_actlen); + } + + vnd_close(vhp); + /* Do proper memory cleanup */ + return (0); +} +.fi +.in -2 + +.LP +Example 4 Perform non-blocking reads of multiple frames with a +single vector +.sp +.LP +In this sample C program, opens an existing vnd device named "vnd0" in +the current zone, ensures that it is in non-blocking mode, and uses +event ports to do device reads. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> +#include <port.h> +#include <unistd.h> +#include <errno.h> +#include <sys/tpyes.h> +#include <fcntl.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr, i, nframes, port, vfd; + frameio_t *fiop; + + port = port_create(); + if (port < 0) { + perror("port_create"); + return (1); + } + /* Allocate enough framevec_t's for 10 frames */ + fiop = malloc(sizeof (frameio_t) + sizeof (framevec_t) * 10); + if (fiop == NULL) { + perror("malloc frameio_t"); + (void) close(port); + return (1); + } + fiop->fio_version = FRAMEIO_CURRENT_VERSION; + fiop->fio_nvpf = 1; + fiop->fio_nvecs = 10; + for (i = 0; i < 10; i++) { + fiop->fio_vecs[i].fv_buf = malloc(1518); + fiop->fio_vecs[i].fv_buflen = 1518; + if (fiop->fio_vecs[i].fv_buf == NULL) { + perror("malloc framevec_t.fv_buf"); + /* Perform appropriate memory cleanup */ + (void) close(port); + return (1); + } + } + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + /* Perform appropriate memory cleanup */ + (void) close(port); + return (1); + } + vfd = vnd_pollfd(vhp); + if (fcntl(fd, F_SETFL, O_NONBLOCK) != 0) { + (void) fprintf(stderr, "failed to enable non-blocking mode: %s", + strerrror(errno)); + } + + for (;;) { + port_event_t pe; + + if (port_associate(port, PORT_SOURCE_FD, vfd, POLLIN, + vhp) != 0) { + perror("port_associate"); + vnd_close(vhp); + /* Perform appropriate memory cleanup */ + (void) close(port); + return (1); + } + + if (port_get(port, &pe, NULL) != 0) { + if (errno == EINTR) + continue; + perror("port_associate"); + vnd_close(vhp); + /* Perform appropriate memory cleanup */ + (void) close(port); + return (1); + } + + /* + * Most real applications will need to compare the file + * descriptor and switch on it. In this case, assume + * that the fd in question that is readable is 'vfd'. + */ + if (frameio_read(pe.portev_user, fiop) != 0) { + vnd_errno_t vnderr = vnd_errno(vhp); + int syserr = vnd_syserrno(vhp); + + if (vnderr == VND_E_SYS && (syserr == EINTR || + syserr == EAGAIN)) + continue; + (void) fprintf(stderr, "failed to get read: %s", + vnd_strsyserror(vnderr)); + vnd_close(vhp); + /* Perform appropriate memory cleanup */ + (void) close(port); + return (1); + } + + /* Consume the data however it's desired */ + nframes = fiop->fio_nvecs / fiop->fio_nvpf; + for (i = 0; i < nframes; i++) { + (void) printf("frame %d is %d bytes large\n", i, + fiop->fio_vecs[i].fv_actlen); + } + + } + + vnd_close(vhp); + /* Do proper memory cleanup */ + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See "THREADING" in libvnd(3LIB) +.TE + + +.SH SEE ALSO + +Intro(2), getmsg(2), read(2), readv(2), write(2), writev(2), +libvnd(3VND), vnd_errno(3VND), vnd_pollfd(3VND), vnd_syserrno(3VND), +iovec(9S) diff --git a/usr/src/man/man3vnd/vnd_pollfd.3vnd b/usr/src/man/man3vnd/vnd_pollfd.3vnd new file mode 100644 index 0000000000..500d3bac99 --- /dev/null +++ b/usr/src/man/man3vnd/vnd_pollfd.3vnd @@ -0,0 +1,155 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_POLLFD 3VND "Feb 21, 2014" + +.SH NAME + +vnd_pollfd \- get file descriptor for polling + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +int vnd_pollfd(vnd_handle_t *vhp); +.fi + +.SH DESCRIPTION +.LP +The vnd_pollfd() function returns an integer id which corresponds to +the file descriptor that represents the underlying device that is +associated with the vnd handle vhp. This file descriptor is suitable +for use with port_associate(3C) and similar polling techniques such as +poll(2). Use of the file descriptor outside of these uses may cause +undocumented behavior from the rest of the library. + +.LP +The file descriptor in question is still managed by libvnd. The caller +must not call close(2) on it. Once vnd_close(3VND) has been called, +any further use of the file descriptor is undefined behavior. + + +.SH RETURN VALUES +.LP +The function returns the integer id of the file descriptor that +corresponds to the underlying vnd device. + +.SH EXAMPLES + +.LP +Example 1 Use event ports for vnd notifications +.sp +.LP +The following sample C program shows how to use the vnd_pollfd +function with event ports to be notified whenever there is data +available to be read. This program assumes that a vnd device named +"vnd0" exists in the current zone. For an example of creating the +device, see Example 1 in vnd_create(3VND). + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <port.h> +#include <sys/types.h> +#include <unistd.h> +#include <fcntl.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int port, syserr, vfd, ret; + + port = port_create(); + if (port < 0) { + perror("port_create"); + return (1); + } + + vhp = vnd_open(NULL, "vnd0", &vnderr, &syserr); + if (vhp == NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + (void) close(port); + return (1); + } + + vfd = vnd_pollfd(vhp); + if (fcntl(vfd, F_SETFL, O_NONBLOCK) != 0) { + perror("fcntl"); + vnd_close(vhp); + (void) close(port); + return (1); + } + + if (port_associate(port, PORT_SOURCE_FD, vfd, POLLIN, NULL) != 0) { + perror("port_associate"); + vnd_close(vhp); + (void) close(port); + return (1); + } + + for (;;) { + port_event_t pe; + + + if (port_get(port, &pe, NULL) != 0) { + if (errno == EINTR) + continue; + perror("port_get"); + vnd_close(vhp); + (void) close(port); + return (1); + } + + /* + * Read the data with vnd_frameio_read(3VND) and + * optionally break out of the loop or continue to the + * next iteration and reassociate vfd with the event + * port. + */ + } +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See "THREADING" in libvnd(3LIB) +.TE + +.SH SEE ALSO + +close(2), poll(2), port_create(3C), libvnd(3LIB), vnd_close(3VND) diff --git a/usr/src/man/man3vnd/vnd_prop_get.3vnd b/usr/src/man/man3vnd/vnd_prop_get.3vnd new file mode 100644 index 0000000000..e47698c85e --- /dev/null +++ b/usr/src/man/man3vnd/vnd_prop_get.3vnd @@ -0,0 +1,242 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_PROP_GET 3VND "Feb 21, 2014" + +.SH NAME + +vnd_prop_get, vnd_prop_set \- get and set vnd properties + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +int vnd_prop_get(vnd_handle_t *vhp, vnd_prop_t prop, void *buf, size_t len); + +int vnd_prop_set(vnd_handle_t *vhp, vnd_prop_t prop, void *buf, size_t len); +.fi + +.SH DESCRIPTION +.LP +The vnd_prop_get and vnd_prop_set functions are used to retrieve +and set property values on the vnd_handle_t referred to by vhp. The +property to get or set is specified by the argument prop. The +argument buf and the size of buf, in len, should be a pointer to the +appropriate structure for the property as defined in libvnd(3LIB). + +.LP +All of the supported properties are listed and described in the +libvnd(3LIB) manual page. + + +.SH RETURN VALUES +.LP +On success, the vnd_prop_get and vnd_prop_set functions return zero. +On failure, they return -1 and additional error information is +available through vnd_errno(3VND) and vnd_syserrno(3VND). + +.LP +When vnd_prop_get returns successfully, the contents of buf are +filled in with the value of the corresponding property. The contents +of buf should not change across a call to vnd_prop_set. + +.SH EXAMPLES + +.LP +Example 1 Getting the value of the rxbuf property +.LP +The following sample C program retrieves the value of the +rxbuf property and prints it to standard out. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr; + vnd_prop_buf_t vpb; + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + if (vnd_prop_get(vhp, VND_PROP_RXBUF, &vpn, sizeof (vpn)) != 0) { + vnderr = vnd_errno(vhp); + syserr = vnd_syserrno(vhp); + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to get VND_PROP_RXBUF: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to get VND_PROP_RXBUF: %s", + vnd_strerror(vnderr)); + return (1); + } + + (void) printf("recieve buffer size is %d bytes\n", vpb.vpb_size); + + vnd_close(vnd); + return (0); +} +.fi +.in -2 + +.LP +EXAMPLE 2 Setting a property +.LP +This sample C program sets the property VND_PROP_RXBUF to the value of +4200 bytes. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr; + vnd_prop_buf_t vpb; + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + vpb.vpb_size = 4200; + if (vnd_prop_set(vhp, VND_PROP_RXBUF, &vpb, sizeof (vpb)) != 0) { + vnderr = vnd_errno(vhp); + syserr = vnd_syserrno(vhp); + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to set VND_PROP_RXBUF: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to set VND_PROP_RXBUF: %s", + vnd_strerror(vnderr)); + return (1); + } + + (void) printf("successfully set VND_PROP_RXBUF to 4200\n"); + + vnd_close(vnd); + return (0); +} +.fi +.in -2 + +.LP +Example 3 Setting a property to the value of another. +.LP +In this sample C program, we set the VND_PROP_TXBUF to the maximum +allowable size as determined by the read-only property VND_PROP_MAXBUF. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr; + vnd_prop_buf_t vpb; + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + if (vnd_prop_get(vhp, VND_PROP_MAXBUF, &vpb, sizeof (vpb)) != 0) { + vnderr = vnd_errno(vhp); + syserr = vnd_syserrno(vhp); + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to get VND_PROP_MAXBUF: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to get VND_PROP_MAXBUF: %s", + vnd_strerror(vnderr)); + return (1); + } + + if (vnd_prop_set(vhp, VND_PROP_TXBUF, &vpb, sizeof (vpb)) != 0) { + vnderr = vnd_errno(vhp); + syserr = vnd_syserrno(vhp); + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to set VND_PROP_TXBUF: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to set VND_PROP_TXBUF: %s", + vnd_strerror(vnderr)); + return (1); + } + + (void) printf("successfully set VND_PROP_TXBUF to %d\n", vpb.vpb_size); + + vnd_close(vnd); + return (0); +} +.fi + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See "THREADING" in libvnd(3LIB) +.TE + +.SH SEE ALSO +libvnd(3VND), vnd_errno(3VND, vnd_syserrno(3VND) diff --git a/usr/src/man/man3vnd/vnd_prop_iter.3vnd b/usr/src/man/man3vnd/vnd_prop_iter.3vnd new file mode 100644 index 0000000000..29221734c5 --- /dev/null +++ b/usr/src/man/man3vnd/vnd_prop_iter.3vnd @@ -0,0 +1,148 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_PROP_ITER 3VND "Feb 21, 2014" + +.SH NAME + +vnd_prop_iter \- iterate vnd properties + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +typedef int (vnd_prop_iter_f)(vnd_handle_t *vhp, vnd_prop_t prop, + void *cbarg); + +int vnd_prop_iter(vnd_handle_t *vhp, vnd_prop_iter_f cb, + void *arg); +.fi + +.SH DESCRIPTION +.LP +The vnd_prop_iter function iterates over all the available properties +for the vnd handle vhp and calls the user supplied callback function +cb. The argument arg is passed directly to the callback function. + +.LP +The function specified by cb receives three arguments. The first, vhp, +is the same vnd library handle that was passed to vnd_prop_iter. During +the callback, the consumer should not call vnd_close(3VND). Doing so +will lead to undefined and undocumented behavior. The second argument, +prop, is the current property. While vnd_prop_iter guarantees that all +properties will be recieved, it does not guarantee the order of them. +The final argument, cbarg, is the same argument that the caller passed +in during arg. + +.LP +The return value of the callback function cb indicates whether or not +property iteration should continue. To continue iteration, the +function cb should return zero. Otherwise, to stop property iteration +it should return non-zero. + +.SH RETURN VALUES + +.LP +On success, the function vnd_prop_iter returns zero. If the callback +function returned non-zero to terminate iteration, vnd_prop_iter will +instead return one. In the case of library failure, vnd_prop_iter will +return -1. In such cases, the vnd and system errors will be updated +and available via vnd_errno(3VND) and vnd_syserrno(3VND). + +.SH EXAMPLES + +.LP +Example 1 Print writeable properties + +.LP +The following sample C program walks over every vnd property and +prints out whether the property is read-only or read-write for the +vnd device "vnd1" in the current zone. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdlib.h> +#include <stdio.h> + +static int +print_prop(vnd_handle_t *vhp, vnd_prop_t prop, void *unused) +{ + boolean_t canwrite; + + if (vnd_prop_writeable(vhp, &canwrite) != 0) + abort(); + + (void) printf("prop %d is %s", prop, canwrite == B_TRUE ? "rw" : "r-"); + return (0); +} + +int +main(void) +{ + vnd_handle_t *vhp; + vnd_errno_t vnderr; + int syserr; + + vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr); + if (vhp != NULL) { + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + if (vnd_prop_iter(vhp, print_prop, NULL) != 0) { + vnderr = vnd_errno(vhp); + syserr = vnd_syserrno(vhp); + if (vnderr == VND_E_SYS) + (void) fprintf(stderr, "failed to open device: %s", + vnd_strsyserror(syserr)); + else + (void) fprintf(stderr, "failed to open device: %s", + vnd_strerror(vnderr)); + return (1); + } + + vnd_close(vnd); + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level See "THREADING" in libvnd(3LIB) +.TE + +libvnd(3LIB), vnd_close(3VND), vnd_errno(3VND), vnd_syserrno(3VND) diff --git a/usr/src/man/man3vnd/vnd_prop_writeable.3vnd b/usr/src/man/man3vnd/vnd_prop_writeable.3vnd new file mode 100644 index 0000000000..c23414718b --- /dev/null +++ b/usr/src/man/man3vnd/vnd_prop_writeable.3vnd @@ -0,0 +1,101 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_PROP_WRITEABLE 3VND "Feb 21, 2014" + +.SH NAME + +vnd_prop_writeable \- determine if a vnd property can be updated + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +int vnd_prop_writeable(vnd_prop_t prop, boolean_t *wp); +.fi + + +.SH DESCRIPTION +.LP +The vnd_prop_writeable function is used as a programmatic means to +determine whether a given vnd property is writeable or not. The +property to check is specified in prop and should be from the list +described in libvnd(3VND). The argument wp is a pointer to a boolean_t +which will be updated upon the successful completion of the function. +The argument wp must be a valid pointer. If a property is writeable +than the value pointed to by wp is set to B_TRUE. If the property is +read-only, then the value is set to B_FALSE. + + +.SH RETURN VALUES +.LP +On success, vnd_prop_writeable returns zero and the value pointed to +by wp is updated with whether the property is writeable. If the +property prop does not exist, then vnd_prop_writeable will return -1. + +.SH EXAMPLES +.LP +Example 1 Check whether the property VND_PROP_TXBUF is writable +.LP +The following sample C program checks whether the vnd property +VND_PROP_TXBUF is writeable or not. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + boolean_t canwrite; + + if (vnd_prop_writeable(VND_PROP_TXBUF, &prop) != 0) + abort(); + + if (canwrite == B_TRUE) + (void) printf("VND_PROP_TXBUF is writeable\n"); + else + (void) printf("VND_PROP_TXBUF is read only\n"); + + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO + +vndadm(1M), libvnd(3VND) diff --git a/usr/src/man/man3vnd/vnd_walk.3vnd b/usr/src/man/man3vnd/vnd_walk.3vnd new file mode 100644 index 0000000000..bed53130d3 --- /dev/null +++ b/usr/src/man/man3vnd/vnd_walk.3vnd @@ -0,0 +1,155 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND_CREATE 3VND "Feb 21, 2014" + +.SH NAME + +vnd_walk \- walk all vnd devices + + +.SH SYNOPSIS + +.LP +.nf +cc [ flag... ] file... -lvnd [ library... ] +#include <libvnd.h> + +typedef int (*vnd_walk_cb_f)(vnd_info_t *viip, void *cbarg); + +int vnd_walk(vnd_walk_cb_t cb, void *arg, vnd_errno_t *vnderr, int *syserr); +.fi + + +.SH DESCRIPTION +.LP +The vnd_walk() function fires the callback function cb once for every +vnd device that is visible in the current zone. If the caller is in +the global zone, then all vnd devices in all zones will be walked. If +the caller is in a non-global zone, then only the devices in that zone +will be visible. + +.LP +The function cb will be called with two arguments. The first argument, +viip, is a pointer to a structure that contains information about the +link. The second argument to the function cb, cbarg, is the same +argument that is passed to the function vnd_walk as arg. To continue +the function cb should return zero. If the function cb returns +non-zero the walk will terminate. + +.LP +As the vnd_walk function does not have a handle, errors are returned +in vnderr and syserr. Both vnderr and syserr are allowed to be NULL +pointers. If either one is a NULL pointer, then error information for +that class of error will not be returned. It is not recommended that +consumers supply NULL pointers. + +.LP +The vnd_info_t structure contains the following members: + +.in +2 +.nf +uint32_t vi_version +zoneid_t vi_zone +char vi_name[LIBVND_NAMELEN]; +char vi_datalink[LIBVND_NAMELEN]; +.fi +.in -2 + +.LP +The member vi_version is guaranteed to be the first member of the +structure. This number indicates the current revision of the structure +and is set to the integer value 1. More properties may be added in +future releases. Those properties will be tied to a greater version +number so software knows whether or not it is legal to access them. + +.LP +The vi_zone field indicates the zone id that the vnd device exists in. +The vi_name field is the name of the vnd device. If the vnd_device is +not linked, the name field is set to "<unknown>". The vi_datalink +field is filled in with the name of the data link the vnd device is on +top of. + + +.SH RETURN VALUES + +.LP +The vnd_walk function will return zero on success. If the consumer +supplied callback function returned non-zero, then the vnd_walk +function will return 1. If an error occurred, -1 is returned, and if +vnderr and syserr are non-null, they are filled in with their +respective error values. See vnd_errno(3VND) for more information on +these errors. + +.SH EXAMPLES + +.LP +Example 1 Walk all devices and print information about them + +.LP +The following sample C program walks every vnd device and prints out +information about them. + +.sp +.in +2 +.nf +#include <libvnd.h> +#include <stdio.h> + +static int +print_entry(vnd_info_t *viip, void *unused) +{ + (void) printf("device %s over data link %s in zone %d\n", + viip->vi_name, viip->vi_datalink, viip->vi_zone); + return (0); +} + +int +main(void) +{ + vnd_errno_t vnderr; + int syserr; + + if (vnd_walk(print_entry, NULL, &vnderr, &syserr) != 0) { + (void) fprintf(stderr, "failed to walk vnd devices: %s\n", + vnderr != VND_E_SYS ? vnd_strerror(vnderr) : + vnd_strsyserror(syserr)); + return (1); + } + + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Stability Committed +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO + +libvnd(3VND), vnd_errno(3VND), attributes(5), zones(5) diff --git a/usr/src/man/man3xnet/Makefile b/usr/src/man/man3xnet/Makefile index 81cd96cba3..cc231f60c4 100644 --- a/usr/src/man/man3xnet/Makefile +++ b/usr/src/man/man3xnet/Makefile @@ -62,6 +62,7 @@ MANLINKS= getaddrinfo.3xnet \ getservbyname.3xnet \ getservbyport.3xnet \ getservent.3xnet \ + htonll.3xnet \ htons.3xnet \ if_freenameindex.3xnet \ if_indextoname.3xnet \ @@ -73,6 +74,7 @@ MANLINKS= getaddrinfo.3xnet \ inet_ntoa.3xnet \ inet_pton.3xnet \ ntohl.3xnet \ + ntohll.3xnet \ ntohs.3xnet \ sethostent.3xnet \ setnetent.3xnet \ @@ -97,6 +99,7 @@ getservbyname.3xnet := LINKSRC = endservent.3xnet getservbyport.3xnet := LINKSRC = endservent.3xnet getservent.3xnet := LINKSRC = endservent.3xnet +htonll.3xnet := LINKSRC = htonl.3xnet htons.3xnet := LINKSRC = htonl.3xnet if_freenameindex.3xnet := LINKSRC = if_nametoindex.3xnet @@ -112,6 +115,7 @@ inet_ntoa.3xnet := LINKSRC = inet_addr.3xnet inet_pton.3xnet := LINKSRC = inet_ntop.3xnet ntohl.3xnet := LINKSRC = htonl.3xnet +ntohll.3xnet := LINKSRC = htonl.3xnet ntohs.3xnet := LINKSRC = htonl.3xnet sethostent.3xnet := LINKSRC = endhostent.3xnet diff --git a/usr/src/man/man3xnet/htonl.3xnet b/usr/src/man/man3xnet/htonl.3xnet index aa8470a28e..dda4586eb7 100644 --- a/usr/src/man/man3xnet/htonl.3xnet +++ b/usr/src/man/man3xnet/htonl.3xnet @@ -7,7 +7,8 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH HTONL 3XNET "Jun 10, 2002" +.\" Portions Copyright (c) 2012 Joyent, Inc. All rights reserved. +.TH HTONL 3XNET "Jan 03, 2013" .SH NAME htonl, htons, ntohl, ntohs \- convert values between host and network byte order @@ -22,6 +23,11 @@ order .LP .nf +\fBuint64_t\fR \fBhtonll\fR(\fBuint64_t\fR \fIhostlonglong\fR); +.fi + +.LP +.nf \fBuint16_t\fR \fBhtons\fR(\fBuint16_t\fR \fIhostshort\fR); .fi @@ -32,18 +38,23 @@ order .LP .nf +\fBuint64_t\fR \fBntohll\fR(\fBuint64_t\fR \fInetlonglong\fR); +.fi + +.LP +.nf \fBuint16_t\fR \fBntohs\fR(\fBuint16_t\fR \fI netshort\fR); .fi .SH DESCRIPTION .sp .LP -These functions convert 16-bit and 32-bit quantities between network byte order -and host byte order. +These functions convert 16-bit, 32-bit, and 64-bit quantities between network +byte order and host byte order. .sp .LP -The \fBuint32_t\fR and \fBuint16_t\fR types are made available by inclusion -of \fB<inttypes.h>\fR\&. +The \fBuint32_t\fR, \fBuint16_t\fR, and \fBuint64_t\fR types are made available +by inclusion of \fB<inttypes.h>\fR\&. .SH USAGE .sp .LP @@ -56,12 +67,12 @@ value of their argument. .SH RETURN VALUES .sp .LP -The \fBhtonl()\fR and \fBhtons()\fR functions return the argument value -converted from host to network byte order. +The \fBhtonl()\fR, \fBhtonll()\fR, and \fBhtons()\fR functions return the +argument value converted from host to network byte order. .sp .LP -The \fBntohl()\fR and \fBntohs()\fR functions return the argument value -converted from network to host byte order. +The \fBntohl()\fR, \fBntohll()\fR, and \fBntohs()\fR functions return the +argument value converted from network to host byte order. .SH ERRORS .sp .LP diff --git a/usr/src/man/man4/Makefile b/usr/src/man/man4/Makefile index d179643b98..e9c85801bf 100644 --- a/usr/src/man/man4/Makefile +++ b/usr/src/man/man4/Makefile @@ -12,6 +12,7 @@ # # Copyright 2011, Richard Lowe # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2015, Joyent, Inc. # include $(SRC)/Makefile.master @@ -82,6 +83,10 @@ _MANFILES= Intro.4 \ ib.4 \ ike.config.4 \ ike.preshared.4 \ + ipf.4 \ + ipmon.4 \ + ipnat.4 \ + ippool.4 \ inet_type.4 \ inetd.conf.4 \ init.4 \ @@ -133,6 +138,7 @@ _MANFILES= Intro.4 \ nsmbrc.4 \ nss.4 \ nsswitch.conf.4 \ + overlay_files.4 \ packingrules.4 \ pam.conf.4 \ passwd.4 \ @@ -182,8 +188,6 @@ _MANFILES= Intro.4 \ sndr.4 \ sock2path.d.4 \ space.4 \ - ssh_config.4 \ - sshd_config.4 \ sulog.4 \ syslog.conf.4 \ system.4 \ @@ -224,6 +228,10 @@ _MANLINKS= addresses.4 \ hosts.allow.4 \ hosts.deny.4 \ intro.4 \ + ipf.conf.4 \ + ipmon.conf.4 \ + ipnat.conf.4 \ + ippool.conf.4 \ md.cf.4 \ mdi_ib_cache.4 \ mdi_scsi_vhci_cache.4 \ @@ -264,6 +272,14 @@ rhosts.4 := LINKSRC = hosts.equiv.4 hosts.allow.4 := LINKSRC = hosts_access.4 hosts.deny.4 := LINKSRC = hosts_access.4 +ipf.conf.4 := LINKSRC = ipf.4 + +ipmon.conf.4 := LINKSRC = ipmon.4 + +ipnat.conf.4 := LINKSRC = ipnat.4 + +ippool.conf.4 := LINKSRC = ippool.4 + fbtab.4 := LINKSRC = logindevperm.4 md.cf.4 := LINKSRC = md.tab.4 diff --git a/usr/src/man/man4/ipf.4 b/usr/src/man/man4/ipf.4 new file mode 100644 index 0000000000..e93753881b --- /dev/null +++ b/usr/src/man/man4/ipf.4 @@ -0,0 +1,562 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPF 4 +.SH NAME +ipf, ipf.conf, ipf6.conf \- IP packet filter rule syntax +.SH DESCRIPTION +.PP +A rule file for \fBipf\fP may have any name or even be stdin. As +\fBipfstat\fP produces parsable rules as output when displaying the internal +kernel filter lists, it is quite plausible to use its output to feed back +into \fBipf\fP. Thus, to remove all filters on input packets, the following +could be done: +.nf + +\fC# ipfstat \-i | ipf \-rf \-\fP +.fi +.SH GRAMMAR +.PP +The format used by \fBipf\fP for construction of filtering rules can be +described using the following grammar in BNF: +\fC +.nf +filter-rule = [ insert ] action in-out [ options ] [ tos ] [ ttl ] + [ proto ] ip [ group ]. + +insert = "@" decnumber . +action = block | "pass" | log | "count" | skip | auth | call . +in-out = "in" | "out" . +options = [ log ] [ tag ] [ "quick" ] [ "on" interface-name [ dup ] + [ froute ] [ replyto ] ] . +tos = "tos" decnumber | "tos" hexnumber . +ttl = "ttl" decnumber . +proto = "proto" protocol . +ip = srcdst [ flags ] [ with withopt ] [ icmp ] [ keep ] . +group = [ "head" decnumber ] [ "group" decnumber ] . + +block = "block" [ return-icmp[return-code] | "return-rst" ] . +log = "log" [ "body" ] [ "first" ] [ "or-block" ] [ "level" loglevel ] . +tag = "tag" tagid . +skip = "skip" decnumber . +auth = "auth" | "preauth" . +call = "call" [ "now" ] function-name . +dup = "dup-to" interface-name [ ":" ipaddr ] . +froute = "fastroute" | "to" interface-name [ ":" ipaddr ] . +replyto = "reply-to" interface-name [ ":" ipaddr ] . +protocol = "tcp/udp" | "udp" | "tcp" | "icmp" | decnumber . +srcdst = "all" | fromto . +fromto = "from" [ "!" ] object "to" [ "!" ] object . + +return-icmp = "return-icmp" | "return-icmp-as-dest" . +return-code = "(" icmp-code ")" . +object = addr [ port-comp | port-range ] . +addr = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] . +addr = "any" | "<thishost>" | nummask | + host-name [ "mask" ipaddr | "mask" hexnumber ] . +port-comp = "port" compare port-num . +port-range = "port" port-num range port-num . +flags = "flags" flag { flag } [ "/" flag { flag } ] . +with = "with" | "and" . +icmp = "icmp-type" icmp-type [ "code" decnumber ] . +return-code = "(" icmp-code ")" . +keep = "keep" "state" [ "(" state-options ")" ] | "keep" "frags" . +loglevel = facility"."priority | priority . + +nummask = host-name [ "/" decnumber ] . +host-name = ipaddr | hostname | "any" . +ipaddr = host-num "." host-num "." host-num "." host-num . +host-num = digit [ digit [ digit ] ] . +port-num = service-name | decnumber . +state-options = state-opts [ "," state-options ] . + +state-opts = "age" decnumber [ "/" decnumber ] | "strict" | + "no-icmp-err" | "limit" decnumber | "newisn" | "sync" . +withopt = [ "not" | "no" ] opttype [ withopt ] . +opttype = "ipopts" | "short" | "frag" | "opt" optname . +optname = ipopts [ "," optname ] . +ipopts = optlist | "sec-class" [ secname ] . +secname = seclvl [ "," secname ] . +seclvl = "unclass" | "confid" | "reserv-1" | "reserv-2" | "reserv-3" | + "reserv-4" | "secret" | "topsecret" . +icmp-type = "unreach" | "echo" | "echorep" | "squench" | "redir" | + "timex" | "paramprob" | "timest" | "timestrep" | "inforeq" | + "inforep" | "maskreq" | "maskrep" | decnumber . +icmp-code = decumber | "net-unr" | "host-unr" | "proto-unr" | "port-unr" | + "needfrag" | "srcfail" | "net-unk" | "host-unk" | "isolate" | + "net-prohib" | "host-prohib" | "net-tos" | "host-tos" | + "filter-prohib" | "host-preced" | "cutoff-preced" . +optlist = "nop" | "rr" | "zsu" | "mtup" | "mtur" | "encode" | "ts" | + "tr" | "sec" | "lsrr" | "e-sec" | "cipso" | "satid" | "ssrr" | + "addext" | "visa" | "imitd" | "eip" | "finn" . +facility = "kern" | "user" | "mail" | "daemon" | "auth" | "syslog" | + "lpr" | "news" | "uucp" | "cron" | "ftp" | "authpriv" | + "audit" | "logalert" | "local0" | "local1" | "local2" | + "local3" | "local4" | "local5" | "local6" | "local7" . +priority = "emerg" | "alert" | "crit" | "err" | "warn" | "notice" | + "info" | "debug" . + +hexnumber = "0" "x" hexstring . +hexstring = hexdigit [ hexstring ] . +decnumber = digit [ decnumber ] . + +compare = "=" | "!=" | "<" | ">" | "<=" | ">=" | "eq" | "ne" | "lt" | + "gt" | "le" | "ge" . +range = "<>" | "><" . +hexdigit = digit | "a" | "b" | "c" | "d" | "e" | "f" . +digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . +flag = "F" | "S" | "R" | "P" | "A" | "U" . +.fi +.PP +This syntax is somewhat simplified for readability, some combinations +that match this grammar are disallowed by the software because they do +not make sense (such as tcp \fBflags\fP for non-TCP packets). +.SH FILTER RULES +.PP +The "briefest" valid rules are (currently) no-ops and are of the form: +.nf + block in all + pass in all + log out all + count in all +.fi +.PP +Filter rules are checked in order, with the last matching rule +determining the fate of the packet (but see the \fBquick\fP option, +below). +.PP +Filters are installed by default at the end of the kernel's filter +lists, prepending the rule with \fB@n\fP will cause it to be inserted +as the n'th entry in the current list. This is especially useful when +modifying and testing active filter rulesets. See \fBipf\fP(1M) for more +information. +.SH ACTIONS +.PP +The action indicates what to do with the packet if it matches the rest +of the filter rule. Each rule MUST have an action. The following +actions are recognised: +.TP +.B block +indicates that the packet should be flagged to be dropped. In response +to blocking a packet, the filter may be instructed to send a reply +packet, either an ICMP packet (\fBreturn-icmp\fP), an ICMP packet +masquerading as being from the original packet's destination +(\fBreturn-icmp-as-dest\fP), or a TCP "reset" (\fBreturn-rst\fP). An +ICMP packet may be generated in response to any IP packet, and its +type may optionally be specified, but a TCP reset may only be used +with a rule which is being applied to TCP packets. When using +\fBreturn-icmp\fP or \fBreturn-icmp-as-dest\fP, it is possible to specify +the actual unreachable `type'. That is, whether it is a network +unreachable, port unreachable or even administratively +prohibited. This is done by enclosing the ICMP code associated with +it in parenthesis directly following \fBreturn-icmp\fP or +\fBreturn-icmp-as-dest\fP as follows: +.nf + block return-icmp(11) ... +.fi +.PP +Would return a Type-Of-Service (TOS) ICMP unreachable error. +.TP +.B pass +will flag the packet to be let through the filter. +.TP +.B log +causes the packet to be logged (as described in the LOGGING section +below) and has no effect on whether the packet will be allowed through +the filter. +.TP +.B count +causes the packet to be included in the accounting statistics kept by +the filter, and has no effect on whether the packet will be allowed through +the filter. These statistics are viewable with ipfstat(8). +.TP +.B call +this action is used to invoke the named function in the kernel, which +must conform to a specific calling interface. Customised actions and +semantics can thus be implemented to supplement those available. This +feature is for use by knowledgeable hackers, and is not currently +documented. +.TP +.B "skip <n>" +causes the filter to skip over the next \fIn\fP filter rules. If a rule is +inserted or deleted inside the region being skipped over, then the value of +\fIn\fP is adjusted appropriately. +.TP +.B auth +this allows authentication to be performed by a user-space program running +and waiting for packet information to validate. The packet is held for a +period of time in an internal buffer whilst it waits for the program to return +to the kernel the \fIreal\fP flags for whether it should be allowed through +or not. Such a program might look at the source address and request some sort +of authentication from the user (such as a password) before allowing the +packet through or telling the kernel to drop it if from an unrecognised source. +.TP +.B preauth +tells the filter that for packets of this class, it should look in the +pre-authenticated list for further clarification. If no further matching +rule is found, the packet will be dropped (the FR_PREAUTH is not the same +as FR_PASS). If a further matching rule is found, the result from that is +used in its instead. This might be used in a situation where a person +\fIlogs in\fP to the firewall and it sets up some temporary rules defining +the access for that person. +.PP +The next word must be either \fBin\fP or \fBout\fP. Each packet +moving through the kernel is either inbound (just been received on an +interface, and moving towards the kernel's protocol processing) or +outbound (transmitted or forwarded by the stack, and on its way to an +interface). There is a requirement that each filter rule explicitly +state which side of the I/O it is to be used on. +.SH OPTIONS +.PP +The list of options is brief, and all are indeed optional. Where +options are used, they must be present in the order shown here. These +are the currently supported options: +.TP +.B log +indicates that, should this be the last matching rule, the packet +header will be written to the \fBipl\fP log (as described in the +LOGGING section below). +.TP +.B tag tagid +indicates that, if this rule causes the packet to be logged or entered +in the state table, the tagid will be logged as part of the log entry. +This can be used to quickly match "similar" rules in scripts that post +process the log files for e.g. generation of security reports or accounting +purposes. The tagid is a 32 bit unsigned integer. +.TP +.B quick +allows "short-cut" rules in order to speed up the filter or override +later rules. If a packet matches a filter rule which is marked as +\fBquick\fP, this rule will be the last rule checked, allowing a +"short-circuit" path to avoid processing later rules for this +packet. The current status of the packet (after any effects of the +current rule) will determine whether it is passed or blocked. +.IP +If this option is missing, the rule is taken to be a "fall-through" +rule, meaning that the result of the match (block/pass) is saved and +that processing will continue to see if there are any more matches. +.TP +.B on +allows an interface name to be incorporated into the matching +procedure. Interface names are as printed by "netstat \-i". If this +option is used, the rule will only match if the packet is going +through that interface in the specified direction (in/out). If this +option is absent, the rule is taken to be applied to a packet +regardless of the interface it is present on (i.e. on all interfaces). +Filter rulesets are common to all interfaces, rather than having a +filter list for each interface. +.IP +This option is especially useful for simple IP-spoofing protection: +packets should only be allowed to pass inbound on the interface from +which the specified source address would be expected, others may be +logged and/or dropped. +.TP +.B dup-to +causes the packet to be copied, and the duplicate packet to be sent +outbound on the specified interface, optionally with the destination +IP address changed to that specified. This is useful for off-host +logging, using a network sniffer. +.TP +.B to +causes the packet to be moved to the outbound queue on the +specified interface. This can be used to circumvent kernel routing +decisions, and even to bypass the rest of the kernel processing of the +packet (if applied to an inbound rule). It is thus possible to +construct a firewall that behaves transparently, like a filtering hub +or switch, rather than a router. The \fBfastroute\fP keyword is a +synonym for this option. +.SH MATCHING PARAMETERS +.PP +The keywords described in this section are used to describe attributes +of the packet to be used when determining whether rules match or don't +match. The following general-purpose attributes are provided for +matching, and must be used in this order: +.TP +.B tos +packets with different Type-Of-Service values can be filtered. +Individual service levels or combinations can be filtered upon. The +value for the TOS mask can either be represented as a hex number or a +decimal integer value. +.TP +.B ttl +packets may also be selected by their Time-To-Live value. The value given in +the filter rule must exactly match that in the packet for a match to occur. +This value can only be given as a decimal integer value. +.TP +.B proto +allows a specific protocol to be matched against. All protocol names +found in \fB/etc/protocols\fP are recognised and may be used. +However, the protocol may also be given as a DECIMAL number, allowing +for rules to match your own protocols, or new ones which would +out-date any attempted listing. +.IP +The special protocol keyword \fBtcp/udp\fP may be used to match either +a TCP or a UDP packet, and has been added as a convenience to save +duplication of otherwise-identical rules. +.\" XXX grammar should reflect this (/etc/protocols) +.PP +The \fBfrom\fP and \fBto\fP keywords are used to match against IP +addresses (and optionally port numbers). Rules must specify BOTH +source and destination parameters. +.PP +IP addresses may be specified in one of two ways: as a numerical +address\fB/\fPmask, or as a hostname \fBmask\fP netmask. The hostname +may either be a valid hostname, from either the hosts file or DNS +(depending on your configuration and library) or of the dotted numeric +form. There is no special designation for networks but network names +are recognised. Note that having your filter rules depend on DNS +results can introduce an avenue of attack, and is discouraged. +.PP +There is a special case for the hostname \fBany\fP which is taken to +be 0.0.0.0/0 (see below for mask syntax) and matches all IP addresses. +Only the presence of "any" has an implied mask, in all other +situations, a hostname MUST be accompanied by a mask. It is possible +to give "any" a hostmask, but in the context of this language, it is +non-sensical. +.PP +The numerical format "x\fB/\fPy" indicates that a mask of y +consecutive 1 bits set is generated, starting with the MSB, so a y value +of 16 would give 0xffff0000. The symbolic "x \fBmask\fP y" indicates +that the mask y is in dotted IP notation or a hexadecimal number of +the form 0x12345678. Note that all the bits of the IP address +indicated by the bitmask must match the address on the packet exactly; +there isn't currently a way to invert the sense of the match, or to +match ranges of IP addresses which do not express themselves easily as +bitmasks (anthropomorphization; it's not just for breakfast anymore). +.PP +If a \fBport\fP match is included, for either or both of source and +destination, then it is only applied to +.\" XXX - "may only be" ? how does this apply to other protocols? will it not match, or will it be ignored? +TCP and UDP packets. If there is no \fBproto\fP match parameter, +packets from both protocols are compared. This is equivalent to "proto +tcp/udp". When composing \fBport\fP comparisons, either the service +name or an integer port number may be used. Port comparisons may be +done in a number of forms, with a number of comparison operators, or +port ranges may be specified. When the port appears as part of the +\fBfrom\fP object, it matches the source port number, when it appears +as part of the \fBto\fP object, it matches the destination port number. +See the examples for more information. +.PP +The \fBall\fP keyword is essentially a synonym for "from any to any" +with no other match parameters. +.PP +Following the source and destination matching parameters, the +following additional parameters may be used: +.TP +.B with +is used to match irregular attributes that some packets may have +associated with them. To match the presence of IP options in general, +use \fBwith ipopts\fP. To match packets that are too short to contain +a complete header, use \fBwith short\fP. To match fragmented packets, +use \fBwith frag\fP. For more specific filtering on IP options, +individual options can be listed. +.IP +Before any parameter used after the \fBwith\fP keyword, the word +\fBnot\fP or \fBno\fP may be inserted to cause the filter rule to only +match if the option(s) is not present. +.IP +Multiple consecutive \fBwith\fP clauses are allowed. Alternatively, +the keyword \fBand\fP may be used in place of \fBwith\fP, this is +provided purely to make the rules more readable ("with ... and ..."). +When multiple clauses are listed, all those must match to cause a +match of the rule. +.\" XXX describe the options more specifically in a separate section +.TP +.B flags +is only effective for TCP filtering. Each of the letters possible +represents one of the possible flags that can be set in the TCP +header. The association is as follows: +.LP +.nf + F - FIN + S - SYN + R - RST + P - PUSH + A - ACK + U - URG +.fi +.IP +The various flag symbols may be used in combination, so that "SA" +would represent a SYN-ACK combination present in a packet. There is +nothing preventing the specification of combinations, such as "SFR", +that would not normally be generated by law-abiding TCP +implementations. However, to guard against weird aberrations, it is +necessary to state which flags you are filtering against. To allow +this, it is possible to set a mask indicating which TCP flags you wish +to compare (i.e., those you deem significant). This is done by +appending "/<flags>" to the set of TCP flags you wish to match +against, e.g.: +.LP +.nf + ... flags S + # becomes "flags S/AUPRFS" and will match + # packets with ONLY the SYN flag set. + + ... flags SA + # becomes "flags SA/AUPRFS" and will match any + # packet with only the SYN and ACK flags set. + + ... flags S/SA + # will match any packet with just the SYN flag set + # out of the SYN-ACK pair; the common "establish" + # keyword action. "S/SA" will NOT match a packet + # with BOTH SYN and ACK set, but WILL match "SFP". +.fi +.TP +.B icmp-type +is only effective when used with \fBproto icmp\fP and must NOT be used +in conjunction with \fBflags\fP. There are a number of types, which can be +referred to by an abbreviation recognised by this language, or the numbers +with which they are associated can be used. The most important from +a security point of view is the ICMP redirect. +.SH KEEP HISTORY +.PP +The second last parameter which can be set for a filter rule is whether or not +to record historical information for that packet, and what sort to keep. The +following information can be kept: +.TP +.B state +keeps information about the flow of a communication session. State can +be kept for TCP, UDP, and ICMP packets. +.TP +.B frags +keeps information on fragmented packets, to be applied to later +fragments. +.PP +allowing packets which match these to flow straight through, rather +than going through the access control list. +.SH GROUPS +The last pair of parameters control filter rule "grouping". By default, all +filter rules are placed in group 0 if no other group is specified. To add a +rule to a non-default group, the group must first be started by creating a +group \fIhead\fP. If a packet matches a rule which is the \fIhead\fP of a +group, the filter processing then switches to the group, using that rule as +the default for the group. If \fBquick\fP is used with a \fBhead\fP rule, rule +processing isn't stopped until it has returned from processing the group. +.PP +A rule may be both the head for a new group and a member of a non-default +group (\fBhead\fP and \fBgroup\fP may be used together in a rule). +.TP +.B "head <n>" +indicates that a new group (number n) should be created. +.TP +.B "group <n>" +indicates that the rule should be put in group (number n) rather than group 0. +.SH LOGGING +.PP +When a packet is logged, with either the \fBlog\fP action or option, +the headers of the packet are written to the \fBipl\fP packet logging +pseudo-device. Immediately following the \fBlog\fP keyword, the +following qualifiers may be used (in order): +.TP +.B body +indicates that the first 128 bytes of the packet contents will be +logged after the headers. +.TP +.B first +If log is being used in conjunction with a "keep" option, it is recommended +that this option is also applied so that only the triggering packet is logged +and not every packet which thereafter matches state information. +.TP +.B or-block +indicates that, if for some reason the filter is unable to log the +packet (such as the log reader being too slow) then the rule should be +interpreted as if the action was \fBblock\fP for this packet. +.TP +.B "level <loglevel>" +indicates what logging facility and priority, or just priority with +the default facility being used, will be used to log information about +this packet using ipmon's -s option. +.PP +See ipl(4) for the format of records written +to this device. The ipmon(8) program can be used to read and format +this log. +.SH EXAMPLES +.PP +The \fBquick\fP option is good for rules such as: +\fC +.nf +block in quick from any to any with ipopts +.fi +.PP +which will match any packet with a non-standard header length (IP +options present) and abort further processing of later rules, +recording a match and also that the packet should be blocked. +.PP +The "fall-through" rule parsing allows for effects such as this: +.LP +.nf + block in from any to any port < 6000 + pass in from any to any port >= 6000 + block in from any to any port > 6003 +.fi +.PP +which sets up the range 6000-6003 as being permitted and all others being +denied. Note that the effect of the first rule is overridden by subsequent +rules. Another (easier) way to do the same is: +.LP +.nf + block in from any to any port 6000 <> 6003 + pass in from any to any port 5999 >< 6004 +.fi +.PP +Note that both the "block" and "pass" are needed here to effect a +result as a failed match on the "block" action does not imply a pass, +only that the rule hasn't taken effect. To then allow ports < 1024, a +rule such as: +.LP +.nf + pass in quick from any to any port < 1024 +.fi +.PP +would be needed before the first block. To create a new group for +processing all inbound packets on le0/le1/lo0, with the default being to block +all inbound packets, we would do something like: +.LP +.nf + block in all + block in quick on le0 all head 100 + block in quick on le1 all head 200 + block in quick on lo0 all head 300 +.fi +.PP + +and to then allow ICMP packets in on le0, only, we would do: +.LP +.nf + pass in proto icmp all group 100 +.fi +.PP +Note that because only inbound packets on le0 are used processed by group 100, +there is no need to respecify the interface name. Likewise, we could further +breakup processing of TCP, etc, as follows: +.LP +.nf + block in proto tcp all head 110 group 100 + pass in from any to any port = 23 group 110 +.fi +.PP +and so on. The last line, if written without the groups would be: +.LP +.nf + pass in on le0 proto tcp from any to any port = telnet +.fi +.PP +Note, that if we wanted to say "port = telnet", "proto tcp" would +need to be specified as the parser interprets each rule on its own and +qualifies all service/port names with the protocol specified. +.SH FILES +/dev/ipauth +.br +/dev/ipl +.br +/dev/ipstate +.br +/etc/hosts +.br +/etc/services +.SH SEE ALSO +\fBipnat\fR(4), \fBipf\fR(1M), \fBipfstat\fR(1M), \fBipfilter\fR(5) diff --git a/usr/src/man/man4/ipmon.4 b/usr/src/man/man4/ipmon.4 new file mode 100644 index 0000000000..9f38eb0551 --- /dev/null +++ b/usr/src/man/man4/ipmon.4 @@ -0,0 +1,72 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPMON 4 +.SH NAME +ipmon, ipmon.conf \- ipmon configuration file format +.SH DESCRIPTION +The format for files accepted by ipmon is described by the following grammar: +.LP +.nf +"match" "{" matchlist "}" "do" "{" doing "}" ";" + +matchlist ::= matching [ "," matching ] . +matching ::= direction | dstip | dstport | every | group | interface | + logtag | nattag | protocol | result | rule | srcip | srcport . + +dolist ::= doing [ "," doing ] . +doing ::= execute | save | syslog . + +direction ::= "in" | "out" . +dstip ::= "dstip" "=" ipv4 "/" number . +dstport ::= "dstport" "=" number . +every ::= "every" every-options . +execute ::= "execute" "=" string . +group ::= "group" "=" string | "group" "=" number . +interface ::= "interface" "=" string . +logtag ::= "logtag" "=" string | "logtag" "=" number . +nattag ::= "nattag" "=" string . +protocol ::= "protocol" "=" string | "protocol" "=" number . +result ::= "result" "=" result-option . +rule ::= "rule" "=" number . +srcip ::= "srcip" "=" ipv4 "/" number . +srcport ::= "srcport" "=" number . +type ::= "type" "=" ipftype . +ipv4 ::= number "." number "." number "." number . + +every-options ::= "second" | number "seconds" | "packet" | number "packets" . +result-option ::= "pass" | "block" | "short" | "nomatch" | "log" . +ipftype ::= "ipf" | "nat" | "state" . + +.fi +.PP +In addition, lines that start with a # are considered to be comments. +.SH OVERVIEW +.PP +The ipmon configuration file is used for defining rules to be executed when +logging records are read from +.B /dev/ipl. +.PP +At present, only IPv4 matching is available for source/destination address +matching. +.SH MATCHING +.PP +Each rule for ipmon consists of two primary segments: the first describes how +the log record is to be matched, the second defines what action to take if +there is a positive match. All entries of the rules present in the file are +compared for matches - there is no first or last rule match. +.SH FILES +/dev/ipl +.br +/dev/ipf +.br +/dev/ipnat +.br +/dev/ipstate +.br +/etc/ipmon.conf +.SH SEE ALSO +\fBipmon\fR(1M), \fBipfilter\fR(5) diff --git a/usr/src/man/man4/ipnat.4 b/usr/src/man/man4/ipnat.4 new file mode 100644 index 0000000000..d7f6143de0 --- /dev/null +++ b/usr/src/man/man4/ipnat.4 @@ -0,0 +1,295 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPNAT 4 +.SH NAME +ipnat, ipnat.conf \- IP NAT file format +.SH DESCRIPTION +The format for files accepted by ipnat is described by the following grammar: +.LP +.nf +ipmap :: = mapblock | redir | map . + +map ::= mapit ifname lhs "->" dstipmask [ mapicmp | mapport | mapproxy ] + mapoptions . +mapblock ::= "map-block" ifname lhs "->" ipmask [ ports ] mapoptions . +redir ::= "rdr" ifname rlhs "->" ip [ "," ip ] rdrport rdroptions . + +lhs ::= ipmask | fromto . +rlhs ::= ipmask dport | fromto . +dport ::= "port" portnum [ "-" portnum ] . +ports ::= "ports" numports | "auto" . +rdrport ::= "port" portnum . +mapit ::= "map" | "bimap" . +fromto ::= "from" object "to" object . +ipmask ::= ip "/" bits | ip "/" mask | ip "netmask" mask . +dstipmask ::= ipmask | "range" ip "-" ip . +mapicmp ::= "icmpidmap" "icmp" number ":" number . +mapport ::= "portmap" tcpudp portspec . +mapoptions ::= [ tcpudp ] [ "frag" ] [ age ] [ clamp ] . +rdroptions ::= rdrproto [ rr ] [ "frag" ] [ age ] [ clamp ] [ rdrproxy ] . + +object :: = addr [ port-comp | port-range ] . +addr :: = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] . +port-comp :: = "port" compare port-num . +port-range :: = "port" port-num range port-num . +rdrproto ::= tcpudp | protocol . + +rr ::= "round-robin" . +age ::= "age" decnumber [ "/" decnumber ] . +clamp ::= "mssclamp" decnumber . +tcpudp ::= "tcp/udp" | protocol . +mapproxy ::= "proxy" "port" port proxy-name '/' protocol +rdrproxy ::= "proxy" proxy-name . + +protocol ::= protocol-name | decnumber . +nummask ::= host-name [ "/" decnumber ] . +portspec ::= "auto" | portnumber ":" portnumber . +port ::= portnumber | port-name . +portnumber ::= number { numbers } . +ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers . + +numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' . +.fi +.PP +For standard NAT functionality, a rule should start with \fBmap\fP and then +proceeds to specify the interface for which outgoing packets will have their +source address rewritten. +.PP +Packets which will be rewritten can only be selected by matching the original +source address. A netmask must be specified with the IP address. +.PP +The address selected for replacing the original is chosen from an IP#/netmask +pair. A netmask of all 1's indicating a hostname is valid. A netmask of +31 1's (255.255.255.254) is considered invalid as there is no space for +allocating host IP#'s after consideration for broadcast and network +addresses. +.PP +When remapping TCP and UDP packets, it is also possible to change the source +port number. Either TCP or UDP or both can be selected by each rule, with a +range of port numbers to remap into given as \fBport-number:port-number\fP. +.SH COMMANDS +There are four commands recognised by IP Filter's NAT code: +.TP +.B map +that is used for mapping one address or network to another in an unregulated +round robin fashion; +.TP +.B rdr +that is used for redirecting packets to one IP address and port pair to +another; +.TP +.B bimap +for setting up bidirectional NAT between an external IP address and an internal +IP address and +.TP +.B map-block +which sets up static IP address based translation, based on a algorithm to +squeeze the addresses to be translated into the destination range. +.SH MATCHING +.PP +For basic NAT and redirection of packets, the address subject to change is used +along with its protocol to check if a packet should be altered. The packet +\fImatching\fP part of the rule is to the left of the "->" in each rule. +.PP +Matching of packets has now been extended to allow more complex compares. +In place of the address which is to be translated, an IP address and port +number comparison can be made using the same expressions available with +\fBipf\fP. A simple NAT rule could be written as: +.LP +.nf +map de0 10.1.0.0/16 -> 201.2.3.4/32 +.fi +.LP +or as +.LP +.nf +map de0 from 10.1.0.0/16 to any -> 201.2.3.4/32 +.fi +.LP +Only IP address and port numbers can be compared against. This is available +with all NAT rules. +.SH TRANSLATION +.PP +To the right of the "->" is the address and port specification which will be +written into the packet providing it has already successfully matched the +prior constraints. The case of redirections (\fBrdr\fP) is the simplest: +the new destination address is that specified in the rule. For \fBmap\fP +rules, the destination address will be one for which the tuple combining +the new source and destination is known to be unique. If the packet is +either a TCP or UDP packet, the destination and source ports come into the +equation too. If the tuple already exists, IP Filter will increment the +port number first, within the available range specified with \fBportmap\fP +and if there exists no unique tuple, the source address will be incremented +within the specified netmask. If a unique tuple cannot be determined, then +the packet will not be translated. The \fBmap-block\fP is more limited in +how it searches for a new, free and unique tuple, in that it will used an +algorithm to determine what the new source address should be, along with the +range of available ports - the IP address is never changed and nor does the +port number ever exceed its allotted range. +.SH ICMPIDMAP +.PP +ICMP messages can be divided into two groups: "errors" and "queries". ICMP +errors are generated as a response of another IP packet. IP Filter will take +care that ICMP errors that are the response of a NAT-ed IP packet are +handled properly. +.PP +For 4 types of ICMP queries (echo request, timestamp request, information +request and address mask request) IP Filter supports an additional mapping +called "ICMP id mapping". All these 4 types of ICMP queries use a unique +identifier called the ICMP id. This id is set by the process sending the +ICMP query and it is usually equal to the process id. The receiver of the +ICMP query will use the same id in its response, thus enabling the +sender to recognize that the incoming ICMP reply is intended for him and is +an answer to a query that he made. The "ICMP id mapping" feature modifies +these ICMP id in a way identical to \fBportmap\fP for TCP or UDP. +.PP +The reason that you might want this, is that using this feature you don't +need an IP address per host behind the NAT box, that wants to do ICMP queries. +The two numbers behind the \fBicmpidmap\fP keyword are the first and the +last icmp id number that can be used. There is one important caveat: if you +map to an IP address that belongs to the NAT box itself (notably if you have +only a single public IP address), then you must ensure that the NAT box does +not use the \fBicmpidmap\fP range that you specified in the \fBmap\fP rule. +.SH KERNEL PROXIES +.PP +IP Filter comes with a few, simple, proxies built into the code that is loaded +into the kernel to allow secondary channels to be opened without forcing the +packets through a user program. The current state of the proxies is listed +below, as one of three states: +.HP +Aging - protocol is roughly understood from +the time at which the proxy was written but it is not well tested or +maintained; +.HP +Developmental - basic functionality exists, works most of the time but +may be problematic in extended real use; +.HP +Experimental - rough support for the protocol at best, may or may not +work as testing has been at best sporadic, possible large scale changes +to the code in order to properly support the protocol. +.HP +Mature - well tested, protocol is properly +understood by the proxy; +.PP +The currently compiled in proxy list is as follows: +.HP +FTP - Mature +.HP +IRC - Experimental +.HP +rpcbind - Experimental +.HP +H.323 - Experimental +.HP +Real Audio (PNA) - Aging +.HP +IPsec - Developmental +.HP +netbios - Experimental +.HP +R-command - Mature + +.SH TRANSPARENT PROXIES +.PP +True transparent proxying should be performed using the redirect (\fBrdr\fP) +rules directing ports to localhost (127.0.0.1) with the proxy program doing +a lookup through \fB/dev/ipnat\fP to determine the real source and address +of the connection. +.SH LOAD-BALANCING +.PP +Two options for use with \fBrdr\fP are available to support primitive, +\fIround-robin\fP based load balancing. The first option allows for a +\fBrdr\fP to specify a second destination, as follows: +.LP +.nf +rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp +.fi +.LP +This would send alternate connections to either 203.1.2.3 or 203.1.2.4. +In scenarios where the load is being spread amongst a larger set of +servers, you can use: +.LP +.nf +rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp round-robin +rdr le0 203.1.2.3/32 port 80 -> 203.1.2.5 port 80 tcp round-robin +.fi +.LP +In this case, a connection will be redirected to 203.1.2.3, then 203.1.2.4 +and then 203.1.2.5 before going back to 203.1.2.3. In accomplishing this, +the rule is removed from the top of the list and added to the end, +automatically, as required. This will not effect the display of rules +using "ipnat -l", only the internal application order. +.SH EXAMPLES +.PP +This section deals with the \fBmap\fP command and its variations. +.PP +To change IP#'s used internally from network 10 into an ISP provided 8 bit +subnet at 209.1.2.0 through the ppp0 interface, the following would be used: +.LP +.nf +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 +.fi +.PP +The obvious problem here is we're trying to squeeze over 16,000,000 IP +addresses into a 254 address space. To increase the scope, remapping for TCP +and/or UDP, port remapping can be used; +.LP +.nf +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000 +.fi +.PP +which falls only 527,566 `addresses' short of the space available in network +10. If we were to combine these rules, they would need to be specified as +follows: +.LP +.nf +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000 +map ppp0 10.0.0.0/8 -> 209.1.2.0/24 +.fi +.PP +so that all TCP/UDP packets were port mapped and only other protocols, such as +ICMP, only have their IP# changed. In some instances, it is more appropriate +to use the keyword \fBauto\fP in place of an actual range of port numbers if +you want to guarantee simultaneous access to all within the given range. +However, in the above case, it would default to 1 port per IP address, since +we need to squeeze 24 bits of address space into 8. A good example of how +this is used might be: +.LP +.nf +map ppp0 172.192.0.0/16 -> 209.1.2.0/24 portmap tcp/udp auto +.fi +.PP +which would result in each IP address being given a small range of ports to +use (252). In all cases, the new port number that is used is deterministic. +That is, port X will always map to port Y. +WARNING: It is not advisable to use the \fBauto\fP feature if you are map'ing +to a /32 (i.e. 0/32) because the NAT code will try to map multiple hosts to +the same port number, outgoing and ultimately this will only succeed for one +of them. +The problem here is that the \fBmap\fP directive tells the NAT +code to use the next address/port pair available for an outgoing connection, +resulting in no easily discernible relation between external addresses/ports +and internal ones. This is overcome by using \fBmap-block\fP as follows: +.LP +.nf +map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto +.fi +.PP +For example, this would result in 172.192.0.0/24 being mapped to 209.1.2.0/32 +with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its +own. As opposed to the above use of \fBmap\fP, if for some reason the user +of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would +be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next +IP address with the \fBmap\fP command. +/dev/ipnat +.br +/etc/services +.br +/etc/hosts +.SH SEE ALSO +\fBhosts\fR(4), \fBipf\fR(4), \fBservices\fR(4), \fBipf\fR(1M), +\fBipnat\fR(1M), \fBipfilter\fR(5) diff --git a/usr/src/man/man4/ippool.4 b/usr/src/man/man4/ippool.4 new file mode 100644 index 0000000000..1ff0e79129 --- /dev/null +++ b/usr/src/man/man4/ippool.4 @@ -0,0 +1,159 @@ +'\" te +.\" To view license terms, attribution, and copyright for IP Filter, the +.\" default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Illumos operating +.\" environment has been installed anywhere other than the default, modify the +.\" given path to access the file at the installed location. +.\" Portions Copyright (c) 2015, Joyent, Inc. +.TH IPPOOL 4 +.SH NAME +ippool, ippool.conf \- IP Pool file format +.SH DESCRIPTION +The format for files accepted by ippool is described by the following grammar: +.LP +.nf +line ::= table | groupmap . +table ::= "table" role tabletype . +groupmap ::= "group-map" inout role number ipfgroup +tabletype ::= ipftree | ipfhash . + +role ::= "role" "=" "ipf" . +inout ::= "in" | "out" . + +ipftree ::= "type" "=" "tree" number "{" addrlist "}" . +ipfhash ::= "type" "=" "hash" number hashopts "{" hashlist "}" . + +ipfgroup ::= setgroup hashopts "{" grouplist "}" | + hashopts "{" setgrouplist "}" . +setgroup ::= "group" "=" groupname . + +hashopts ::= size [ seed ] | seed . + +size ::= "size" number . +seed ::= "seed" number . + +addrlist ::= [ "!" ] addrmask ";" [ addrlist ] . +grouplist ::= groupentry ";" [ grouplist ] | addrmask ";" [ grouplist ] . + +setgrouplist ::= groupentry ";" [ setgrouplist ] . + +groupentry ::= addrmask "," setgroup . + +hashlist ::= hashentry ";" [ hashlist ] . +hashentry ::= addrmask . + +addrmask ::= ipaddr | ipaddr "/" mask . + +mask ::= number | ipaddr . + +groupname ::= number | name . + +number ::= digit { digit } . + +ipaddr = host-num "." host-num "." host-num "." host-num . +host-num = digit [ digit [ digit ] ] . + +digit ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . +name ::= letter { letter | digit } . +.fi +.PP +The IP pool configuration file is used for defining a single object that +contains a reference to multiple IP address/netmask pairs. A pool may consist +of a mixture of netmask sizes, from 0 to 32. +.PP +At this point in time, only IPv4 addressing is supported. +.SH OVERVIEW +.PP +The IP pool configuration file provides for defining two different mechanisms +for improving speed in matching IP addresses with rules. +The first, +.B table +, defines a lookup +.I table +to provide a single reference in a +filter rule to multiple targets and the second, +.B group-map +, provides a mechanism to target multiple groups from a single filter line. +.PP +The +.B group-map +command can only be used with filter rules that use the +.B call +command to invoke either +.B fr_srcgrpmap +or +.B fr_dstgrpmap +, to use the source or destination address, +respectively, for determining which filter group to jump to next for +continuation of filter packet processing. +.SH POOL TYPES +.PP +Two storage formats are provided: hash tables and tree structure. The hash +table is intended for use with objects all containing the same netmask or a +few different sized netmasks of non-overlapping address space and the tree +is designed for being able to support exceptions to a covering mask, in +addition to normal searching as you would do with a table. It is not possible +to use the tree data storage type with +.B group-map +configuration entries. +.SH POOL ROLES +.PP +When a pool is defined in the configruation file, it must have an associated +role. At present the only supported role is +.B ipf. +Future development will see futher expansion of their use by other sections +of IPFilter code. +.SH EXAMPLES +The following examples show how the pool configuration file is used with +the ipf configuration file to enhance the ability for the ipf configuration +file to be succinct in meaning. +.TP +1 +The first example shows how a filter rule makes reference to a specific +pool for matching of the source address. +.nf +pass in from pool/100 to any +.fi +.PP +The pool configuration, which matches IP addresses 1.1.1.1 and any +in 2.2.0.0/16, except for those in 2.2.2.0/24. +.PP +.nf +table role = ipf type = tree number = 100 + { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24 }; +.fi +.TP +2 +The following ipf.conf extract uses the +fr_srcgrpmap/fr_dstgrpmap lookups to use the +.B group-map +facility to lookup the next group to use for filter processing, providing +the +.B call +filter rule is matched. +.nf +call now fr_srcgrpmap/1010 in all +call now fr_dstgrpmap/2010 out all +pass in all group 1020 +block in all group 1030 +pass out all group 2020 +block out all group 2040 +.fi +.PP +A ippool configuration to work with the above ipf.conf file might +look like this: +.PP +.nf +group-map in role = ipf number = 1010 + { 1.1.1.1/32, group = 1020; 3.3.0.0/16, group = 1030; }; +group-map out role = ipf number = 2010 group = 2020 + { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; }; +.fi +.SH FILES +/dev/iplookup +.br +/etc/ippool.conf +.br +/etc/hosts +.SH SEE ALSO +\fBippool\fR(1M), \fBhosts\fR(4), \fBipf\fR(4), \fBipf\fR(1M), \fBipnat\fR(1M), +\fBipfilter\fR(5) diff --git a/usr/src/man/man4/overlay_files.4 b/usr/src/man/man4/overlay_files.4 new file mode 100644 index 0000000000..c1a4ce4b3b --- /dev/null +++ b/usr/src/man/man4/overlay_files.4 @@ -0,0 +1,169 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2015, Joyent, Inc. +.\" +.Dd Apr 13, 2015 +.Dt OVERLAY_FILES 4 +.Os +.Sh NAME +.Nm overlay_files +.Nd Overlay files plugin file format +.Sh DESCRIPTION +The +.Sy files +plugin provides a means for a dynamic overlay where the destinations are +determined based on a static description contained in a +.Sy JSON +file. This manual describes the format of the file used by the +.Sy files/config +property. To create and manage overlays +with the +.Sy files +plugin, use +.Xr dladm 1M . +For more information on overlays, see +.Xr overlay 5 . +.Pp +Using the +.Sy files +module, a static and simple overlay network can be created. This network +does not support the use of +.Em broadcast +or +.Em multicast +traffic. Both ARP and NDP traffic are proxied by the plugin itself. In +addition, the plugin allows for DHCP. Instead of providing a traditional +DHCP proxy, when an initial DHCP broadcast goes out to a broadcast +address, it will get rewritten to target a specific MAC address. The +.Sy files +plugin is useful as proof of concept and for simple static networks +where addresses do not need to be reconfigured. If more advanced +topologies or more streamlined updates are required, consider a different +plugin. +.Pp +The file format is encoded as a series of +.Sy JSON +objects. Each object has a key, which is a MAC address on the +.Sy overlay +network. It has multiple values, some required, some optional, which +describe various properties. The valid properties are: +.Bl -hang -width Ds +.It Sy ip +.Bd -filled -compact +The +.Sy ip +key indicates the IP address on the +.Sy underlay +network that houses the MAC address in question. Packets directed for +the MAC address will be encapsulated and set to this address. This field +is required. +.Pp +The value is a +.Em JSON String . +Both IPv4 and IPv6 addresses are supported and should be written out in their +traditional forms. Follow the guidelines for writing addresses in +.Xr inet_aton 3SOCKET . +.Ed +.It Sy port +.Bd -filled -compact +The +.Sy port +key indicates the port on the +.Sy underlay +network that houses the MAC address in question. This property is required if +the encapsulation module requires a port for its destination. The value is +a +.Em JSON Number . +.Ed +.It Sy arp +.Bd -filled -compact +The +.Sy arp +key stores the IPv4 address that corresponds to this MAC address on the +.Sy overlay +network. This will be used to respond to ARP queries that would traditionally +have been received by the OS kernel. If this address is not present, no IPv4 +packets directed to this IP address will be received by the network interface +that has this MAC address, regardless of what is configured on top of it. +.Pp +The value is a +.Em JSON String +and should be written out following the guidelines for IPv4 addresses in +.Xr inet_aton 3SOCKET . +.Ed +.It Sy ndp +.Bd -filled -compact +The +.Sy ndp +key stores the IPv6 address that corresponds to this MAC address on the +.Sy overlay +network. This will be used to respond to NDP queries that would traditionally +have been received by the OS kernel. If this address is not present, no IPv6 +packets directed to this IP address will be received by the network interface +that has this MAC address, regardless of what is configured on top of it. +.Pp +The value is a +.Em JSON String +and should be written out following the guidelines for IPv6 addresses in +.Xr inet_aton 3SOCKET . +.Ed +.It Sy dhcp-proxy +.Bd -filled -compact +The +.Sy dhcp-proxy +key stores a MAC address that DHCP messages directed to a broadcast address get +rewritten to be sent to. This can be viewed as a form of proxy DHCP, but is +different in mechanism from a traditional proxy. The value is a +.Em JSON String +and should be written as a traditional MAC address string as described by +.Xr ether_aton 3SOCKET . +.Ed +.El +.Sh EXAMPLES +.Sy Example 1 +Sample configuration file +.Pp +This configuration file provides information for three different MAC +addresses. Each MAC address has an entry which describes what its IPv4 +and IPv6 address is, as well as the IP address and port of the host on +the underlay network. Finally, one host has a DHCP proxy entry to +demonstrate how one might configure DHCP. +.Bd -literal -offset indent +{ + "de:ad:be:ef:00:00": { + "arp": "10.55.55.2", + "ip": "10.88.88.69", + "ndp": "fe80::3", + "port": 4789 + }, + "de:ad:be:ef:00:01": { + "arp": "10.55.55.3", + "dhcp-proxy": "de:ad:be:ef:00:00", + "ip": "10.88.88.70", + "ndp": "fe80::4", + "port": 4789 + }, + "de:ad:be:ef:00:02": { + "arp": "10.55.55.4", + "ip": "10.88.88.71", + "ndp": "fe80::5", + "port": 4789 + } +} +.Ed +.Sh STABILITY +This file format is +.Sy committed ; +however, keys that are not listed here are reserved for future use. +.Sh SEE ALSO +.Xr dladm 1M +.Xr overlay 5 diff --git a/usr/src/man/man4/proc.4 b/usr/src/man/man4/proc.4 index 20f2089f5e..c0a044164a 100644 --- a/usr/src/man/man4/proc.4 +++ b/usr/src/man/man4/proc.4 @@ -1,15 +1,14 @@ '\" te .\" Copyright 1989 AT&T .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright (c) 2013, Joyent, Inc. All rights reserved. +.\" Copyright 2015, Joyent, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PROC 4 "Mar 31, 2013" +.TH PROC 4 "May 19, 2014" .SH NAME proc \- /proc, the process file system .SH DESCRIPTION -.sp .LP \fB/proc\fR is a file system that provides access to the state of each process and light-weight process (lwp) in the system. The name of each entry in the @@ -174,7 +173,6 @@ To help deal with system data structures that are read from 32-bit processes, a explicit 32-bit fixed-width data structures (like \fBcstruct stat32\fR) visible to the 64-bit program. See \fBtypes32.h\fR(3HEAD). .SH DIRECTORY STRUCTURE -.sp .LP At the top level, the directory \fB/proc\fR contains entries each of which names an existing process in the system. These entries are themselves @@ -201,7 +199,6 @@ structures may grow by the addition of elements at the end in future releases of the system and it is not legitimate for a program to assume that they will not. .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR -.sp .LP A given directory \fB/proc/\fR\fIpid\fR contains the following entries. A process can use the invisible alias \fB/proc/self\fR if it wishes to open one @@ -209,13 +206,11 @@ of its own \fB/proc\fR files (invisible in the sense that the name ``self'' does not appear in a directory listing of \fB/proc\fR obtained from \fBls\fR(1), \fBgetdents\fR(2), or \fBreaddir\fR(3C)). .SS "contracts" -.sp .LP A directory containing references to the contracts held by the process. Each entry is a symlink to the contract's directory under \fB/system/contract\fR. See \fBcontract\fR(4). .SS "as" -.sp .LP Contains the address-space image of the process; it can be opened for both reading and writing. \fBlseek\fR(2) is used to position the file at the virtual @@ -223,7 +218,6 @@ address of interest and then the address space can be examined or changed through \fBread\fR(2) or \fBwrite\fR(2) (or by using \fBpread\fR(2) or \fBpwrite\fR(2) for the combined operation). .SS "ctl" -.sp .LP A write-only file to which structured messages are written directing the system to change some aspect of the process's state or control its behavior in some @@ -235,7 +229,6 @@ message is immediately reflected in the state of the process visible through appropriate status and information files. The types of control messages are described in detail later. See \fBCONTROL MESSAGES\fR. .SS "status" -.sp .LP Contains state information about the process and the representative lwp. The file contains a \fBpstatus\fR structure which contains an embedded @@ -672,6 +665,18 @@ the process. \fBpr_what\fR is unused in this case. .RE .sp +.ne 2 +.na +\fB\fBPR_BRAND\fR\fR +.ad +.RS 17n +indicates that the lwp stopped for a brand-specific reason. Interpretation +of the value of \fBpr_what\fR depends on which zone brand is in use. It is +not generally expected that an lwp stopped in this state will be restarted +by native \fBproc\fR(4) consumers. +.RE + +.sp .LP \fBpr_cursig\fR names the current signal, that is, the next signal to be delivered to the lwp, if any. \fBpr_info\fR, when the lwp is in a @@ -864,7 +869,6 @@ registers. .LP If the lwp is not stopped, all register values are undefined. .SS "psinfo" -.sp .LP Contains miscellaneous information about the process and the representative lwp needed by the \fBps\fR(1) command. \fBpsinfo\fR remains accessible after a @@ -930,6 +934,15 @@ migrate to checking \fBPR_ISSYS\fR in the \fBpstatus\fR structure's 0x8000). \fBpr_pctcpu\fR is the summation over all lwps in the process. .sp .LP +The \fBpr_fname\fR and \fBpr_psargs\fR are writable by the owner of the +process. To write to them, the \fBpsinfo\fR file should be open for writing +and the desired value for the field should be written at the file offset +that corresponds to the member of structure. No other entry may be written +to; if a write is attempted to an offset that does not represent one of +these two memers, or if the size of the write is not exactly the size of +the member being written, no bytes will be written and zero will be returned. +.sp +.LP \fBpr_lwp\fR contains the \fBps\fR(1) information for the representative lwp. If the process is a \fIzombie\fR, \fBpr_nlwp\fR, \fBpr_nzomb\fR, and \fBpr_lwp.pr_lwpid\fR are zero and the other fields of \fBpr_lwp\fR are @@ -983,7 +996,6 @@ maximum value is 1/N, where N is the number of \fBCPU\fRs. \fBpr_contract\fR is the id of the process contract of which the process is a member. See \fBcontract\fR(4) and \fBprocess\fR(4). .SS "cred" -.sp .LP Contains a description of the credentials associated with the process: .sp @@ -1010,7 +1022,6 @@ length; the \fBcred\fR file contains all of the supplementary groups. \fBpr_ngroups\fR indicates the number of supplementary groups. (See also the \fBPCSCRED\fR and \fBPCSCREDX\fR control operations.) .SS "priv" -.sp .LP Contains a description of the privileges associated with the process: .sp @@ -1044,7 +1055,6 @@ which is followed by additional information about the process state The full size of the structure can be computed using \fBPRIV_PRPRIV_SIZE\fR(\fBprpriv_t *\fR). .SS "sigact" -.sp .LP Contains an array of \fBsigaction structures\fR describing the current dispositions of all signals associated with the traced process (see @@ -1052,14 +1062,18 @@ dispositions of all signals associated with the traced process (see that the action for signal number \fIn\fR appears in position \fIn\fR-1 of the array. .SS "auxv" -.sp .LP Contains the initial values of the process's aux vector in an array of \fBauxv_t\fR structures (see \fB<sys/auxv.h>\fR). The values are those that were passed by the operating system as startup information to the dynamic linker. +.SS "argv" +.LP +Contains the concatenation of each of the argument strings, including their +\fBNUL\fR terminators, in the argument vector (\fBargv\fR) for the process. If +the process has modified either its argument vector, or the contents of any of +the strings referenced by that vector, those changes will be visible here. .SS "ldt" -.sp .LP This file exists only on x86-based machines. It is non-empty only if the process has established a local descriptor table (\fBLDT\fR). If non-empty, the @@ -1067,7 +1081,6 @@ file contains the array of currently active \fBLDT\fR entries in an array of elements of type \fBstruct ssd\fR, defined in \fB<sys/sysi86.h>\fR, one element for each active \fBLDT\fR entry. .SS "map, xmap" -.sp .LP Contain information about the virtual address map of the process. The map file contains an array of \fBprmap\fR structures while the xmap file contains an @@ -1235,7 +1248,6 @@ translation for the mapping. \fBpr_hatpagesize\fR may be different than \fBpr_pagesize.\fR The possible values are hardware architecture specific, and may change over a mapping's lifetime. .SS "rmap" -.sp .LP Contains information about the reserved address ranges of the process. The file contains an array of \fBprmap\fR structures, as defined above for the \fBmap\fR @@ -1246,21 +1258,18 @@ not use any part of it for the new mapping. Examples of such reservations include the address ranges reserved for the process stack and the individual thread stacks of a multi-threaded process. .SS "cwd" -.sp .LP A symbolic link to the process's current working directory. See \fBchdir\fR(2). A \fBreadlink\fR(2) of \fB/proc/\fIpid\fR/cwd\fR yields a null string. However, it can be opened, listed, and searched as a directory, and can be the target of \fBchdir\fR(2). .SS "root" -.sp .LP A symbolic link to the process's root directory. \fB/proc/\fR\fIpid\fR\fB/root\fR can differ from the system root directory if the process or one of its ancestors executed \fBchroot\fR(2) as super user. It has the same semantics as \fB/proc/\fR\fIpid\fR\fB/cwd\fR. .SS "fd" -.sp .LP A directory containing references to the open files of the process. Each entry is a decimal number corresponding to an open file descriptor in the process. @@ -1274,7 +1283,6 @@ directory, it can be accessed with the same semantics as \fB/proc/\fIpid\fR/cwd\fR. An attempt to open any other type of entry fails with \fBEACCES\fR. .SS "object" -.sp .LP A directory containing read-only files with names corresponding to the \fBpr_mapname\fR entries in the \fBmap\fR and \fBpagedata\fR files. Opening @@ -1287,7 +1295,6 @@ The \fBobject\fR directory makes it possible for a controlling process to gain access to the object file and any shared libraries (and consequently the symbol tables) without having to know the actual path names of the executable files. .SS "path" -.sp .LP A directory containing symbolic links to files opened by the process. The directory includes one entry for \fBcwd\fR and \fBroot\fR. The directory also @@ -1299,7 +1306,6 @@ namespace (such as \fBFIFO\fRs and sockets), but can also happen for regular files. For the file descriptor entries, the path may be different from the one used by the process to open the file. .SS "pagedata" -.sp .LP Opening the page data file enables tracking of address space references and modifications on a per-page basis. @@ -1381,13 +1387,11 @@ to a system-imposed limit per traced process. A read of one does not affect the data being collected by the system for the others. An open of the page data file will fail with \fBENOMEM\fR if the system-imposed limit would be exceeded. .SS "watch" -.sp .LP Contains an array of \fBprwatch\fR structures, one for each watched area established by the \fBPCWATCH\fR control operation. See \fBPCWATCH\fR for details. .SS "usage" -.sp .LP Contains process usage information described by a \fBprusage\fR structure which contains at least the following fields: @@ -1434,7 +1438,6 @@ previously an estimate, if microstate accounting were not enabled, the current information is now never an estimate represents time the process has spent in various states. .SS "lstatus" -.sp .LP Contains a \fBprheader\fR structure followed by an array of \fBlwpstatus\fR structures, one for each active lwp in the process (see also @@ -1459,13 +1462,11 @@ file header to index through the array. These comments apply to all \fB/proc\fR files that include a \fBprheader\fR structure (\fBlpsinfo\fR and \fBlusage\fR, below). .SS "lpsinfo" -.sp .LP Contains a \fBprheader\fR structure followed by an array of \fBlwpsinfo\fR structures, one for eachactive and zombie lwp in the process. See also \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpsinfo\fR, below. .SS "lusage" -.sp .LP Contains a \fBprheader\fR structure followed by an array of \fBprusage\fR structures, one for each active lwp in the process, plus an additional element @@ -1476,43 +1477,36 @@ summation over all these structures is the definition of the process usage information obtained from the \fBusage\fR file. (See also \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR/\fBlwpusage\fR, below.) .SS "lwp" -.sp .LP A directory containing entries each of which names an active or zombie lwp within the process. These entries are themselves directories containing additional files as described below. Only the \fBlwpsinfo\fR file exists in the directory of a zombie lwp. .SH STRUCTURE OF \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR -.sp .LP A given directory \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwpid\fR contains the following entries: .SS "lwpctl" -.sp .LP Write-only control file. The messages written to this file affect the specific lwp rather than the representative lwp, as is the case for the process's \fBctl\fR file. .SS "lwpstatus" -.sp .LP lwp-specific state information. This file contains the \fBlwpstatus\fR structure for the specific lwp as described above for the representative lwp in the process's \fBstatus\fR file. .SS "lwpsinfo" -.sp .LP lwp-specific \fBps\fR(1) information. This file contains the \fBlwpsinfo\fR structure for the specific lwp as described above for the representative lwp in the process's \fBpsinfo\fR file. The \fBlwpsinfo\fR file remains accessible after an lwp becomes a zombie. .SS "lwpusage" -.sp .LP This file contains the \fBprusage\fR structure for the specific lwp as described above for the process's \fBusage\fR file. .SS "gwindows" -.sp .LP This file exists only on SPARC based machines. If it is non-empty, it contains a \fBgwindows_t\fR structure, defined in \fB<sys/regset.h>\fR, with the values @@ -1523,7 +1517,6 @@ pointer is improperly aligned. If the lwp is not stopped or if there are no register windows that could not be stored on the stack, the file is empty (the usual case). .SS "xregs" -.sp .LP Extra state registers. The extra state register set is architecture dependent; this file is empty if the system does not support extra state registers. If the @@ -1532,7 +1525,6 @@ file is non-empty, it contains an architecture dependent structure of type extra state registers. If the lwp is not stopped, all register values are undefined. See also the \fBPCSXREG\fR control operation, below. .SS "asrs" -.sp .LP This file exists only for 64-bit SPARC V9 processes. It contains an \fBasrset_t\fR structure, defined in <\fBsys/regset.h\fR>, containing the @@ -1540,7 +1532,6 @@ values of the lwp's platform-dependent ancillary state registers. If the lwp is not stopped, all register values are undefined. See also the \fBPCSASRS\fR control operation, below. .SS "spymaster" -.sp .LP For an agent lwp (see \fBPCAGENT\fR), this file contains a \fBpsinfo_t\fR structure that corresponds to the process that created the agent lwp at the @@ -1549,7 +1540,6 @@ the \fBpsinfo\fR file, with one modification: the \fBpr_time\fR field does not correspond to the CPU time for the process, but rather to the creation time of the agent lwp. .SS "templates" -.sp .LP A directory which contains references to the active templates for the lwp, named by the contract type. Changes made to an active template descriptor do @@ -1557,7 +1547,6 @@ not affect the original template which was activated, though they do affect the active template. It is not possible to activate an active template descriptor. See \fBcontract\fR(4). .SH CONTROL MESSAGES -.sp .LP Process state changes are effected through messages written to a process's \fBctl\fR file or to an individual lwp's \fBlwpctl\fR file. All control @@ -1577,7 +1566,6 @@ Descriptions of the allowable control messages follow. In all cases, writing a message to a control file for a process or lwp that has terminated elicits the error \fBENOENT\fR. .SS "PCSTOP PCDSTOP PCWSTOP PCTWSTOP" -.sp .LP When applied to the process control file, \fBPCSTOP\fR directs all lwps to stop and waits for them to stop, \fBPCDSTOP\fR directs all lwps to stop without @@ -1626,7 +1614,6 @@ level, has no user-level address space visible through \fB/proc\fR, and cannot be stopped. Applying one of these operations to a system process or any of its lwps elicits the error \fBEBUSY\fR. .SS "PCRUN" -.sp .LP Make an lwp runnable again after a stop. This operation takes a \fBlong\fR operand containing zero or more of the following flags: @@ -1707,7 +1694,6 @@ event of interest, the representative lwp is marked \fBPR_REQUESTED\fR. If, as a consequence, all lwps are in the \fBPR_REQUESTED\fR or \fBPR_SUSPENDED\fR stop state, all lwps showing \fBPR_REQUESTED\fR are made runnable. .SS "PCSTRACE" -.sp .LP Define a set of signals to be traced in the process. The receipt of one of these signals by an lwp causes the lwp to stop. The set of signals is defined @@ -1720,11 +1706,9 @@ sent to the lwp, the signal is not received and does not cause a stop until it is removed from the held signal set, either by the lwp itself or by setting the held signal set with \fBPCSHOLD\fR. .SS "PCCSIG" -.sp .LP The current signal, if any, is cleared from the specific or representative lwp. .SS "PCSSIG" -.sp .LP The current signal and its associated signal information for the specific or representative lwp are set according to the contents of the operand @@ -1736,7 +1720,6 @@ and an additional \fBPR_SIGNALLED\fR stop does not intervene even if the signal is traced. Setting the current signal to \fBSIGKILL\fR terminates the process immediately. .SS "PCKILL" -.sp .LP If applied to the process control file, a signal is sent to the process with semantics identical to those of \fBkill\fR(2). If applied to an lwp control @@ -1744,7 +1727,6 @@ file, a directed signal is sent to the specific lwp. The signal is named in a \fBlong\fR operand contained in the message. Sending \fBSIGKILL\fR terminates the process immediately. .SS "PCUNKILL" -.sp .LP A signal is deleted, that is, it is removed from the set of pending signals. If applied to the process control file, the signal is deleted from the process's @@ -1753,14 +1735,12 @@ the lwp's pending signals. The current signal (if any) is unaffected. The signal is named in a \fBlong\fR operand in the control message. It is an error (\fBEINVAL\fR) to attempt to delete \fBSIGKILL\fR. .SS "PCSHOLD" -.sp .LP Set the set of held signals for the specific or representative lwp (signals whose delivery will be blocked if sent to the lwp). The set of signals is specified with a \fBsigset_t\fR operand. \fBSIGKILL\fR and \fBSIGSTOP\fR cannot be held; if specified, they are silently ignored. .SS "PCSFAULT" -.sp .LP Define a set of hardware faults to be traced in the process. On incurring one of these faults, an lwp stops. The set is defined via the operand @@ -1885,12 +1865,10 @@ no signal is posted. The \fBpr_info\fR field in the \fBlwpstatus\fR structure identifies the signal to be sent and contains machine-specific information about the fault. .SS "PCCFAULT" -.sp .LP The current fault, if any, is cleared; the associated signal will not be sent to the specific or representative lwp. .SS "PCSENTRY PCSEXIT" -.sp .LP These control operations instruct the process's lwps to stop on entry to or exit from specified system calls. The set of system calls to be traced is @@ -1911,7 +1889,6 @@ instructed to go directly to system call exit by specifying the \fBPRSABORT\fR flag in a \fBPCRUN\fR control message. Unless exit from the system call is being traced, the lwp returns to user level showing \fBEINTR\fR. .SS "PCWATCH" -.sp .LP Set or clear a watched area in the controlled process from a \fBprwatch\fR structure operand: @@ -2060,7 +2037,6 @@ process's inherit-on-fork mode, \fBPR_FORK\fR, is set (see \fBPCSET\fR, below). All watched areas are cancelled when the traced process performs a successful \fBexec\fR(2). .SS "PCSET PCUNSET" -.sp .LP \fBPCSET\fR sets one or more modes of operation for the traced process. \fBPCUNSET\fR unsets these modes. The modes to be set or unset are specified by @@ -2176,7 +2152,6 @@ or to apply these operations to a system process. The current modes are reported in the \fBpr_flags\fR field of \fB/proc/\fR\fIpid\fR\fB/status\fR and \fB/proc/\fR\fIpid\fR\fB/lwp/\fR\fIlwp\fR\fB/lwpstatus\fR. .SS "PCSREG" -.sp .LP Set the general registers for the specific or representative lwp according to the operand \fBprgregset_t\fR structure. @@ -2195,7 +2170,6 @@ overflow-bit. \fBPCSREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest. .SS "PCSVADDR" -.sp .LP Set the address at which execution will resume for the specific or representative lwp from the operand \fBlong\fR. On SPARC based systems, both @@ -2203,7 +2177,6 @@ representative lwp from the operand \fBlong\fR. On SPARC based systems, both address. On x86-based systems, only %eip is set. \fBPCSVADDR\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest. .SS "PCSFPREG" -.sp .LP Set the floating-point registers for the specific or representative lwp according to the operand \fBprfpregset_t\fR structure. An error (\fBEINVAL\fR) @@ -2212,7 +2185,6 @@ floating-point hardware and the system does not emulate floating-point machine instructions). \fBPCSFPREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest. .SS "PCSXREG" -.sp .LP Set the extra state registers for the specific or representative lwp according to the architecture-dependent operand \fBprxregset_t\fR structure. An error @@ -2220,7 +2192,6 @@ to the architecture-dependent operand \fBprxregset_t\fR structure. An error registers. \fBPCSXREG\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest. .SS "PCSASRS" -.sp .LP Set the ancillary state registers for the specific or representative lwp according to the SPARC V9 platform-dependent operand \fBasrset_t\fR structure. @@ -2230,7 +2201,6 @@ state registers are privileged registers that cannot be modified. Only those that can be modified are set; all others are silently ignored. \fBPCSASRS\fR fails with \fBEBUSY\fR if the lwp is not stopped on an event of interest. .SS "PCAGENT" -.sp .LP Create an agent lwp in the controlled process with register values from the operand \fBprgregset_t\fR structure (see \fBPCSREG\fR, above). The agent lwp is @@ -2291,7 +2261,6 @@ agent lwp. Symbolic constants for system call trap numbers like \fBSYS_lwp_exit\fR and \fBSYS_lwp_create\fR can be found in the header file <\fBsys/syscall.h\fR>. .SS "PCREAD PCWRITE" -.sp .LP Read or write the target process's address space via a \fBpriovec\fR structure operand: @@ -2318,7 +2287,6 @@ space, or when stepping over a breakpointed instruction. Unlike \fBpread\fR(2) and \fBpwrite\fR(2), no provision is made for partial reads or writes; if the operation cannot be performed completely, it fails with \fBEIO\fR. .SS "PCNICE" -.sp .LP The traced process's \fBnice\fR(2) value is incremented by the amount in the operand \fBlong\fR. Only a process with the {\fBPRIV_PROC_PRIOCNTL\fR} @@ -2326,7 +2294,6 @@ privilege asserted in its effective set can better a process's priority in this way, but any user may lower the priority. This operation is not meaningful for all scheduling classes. .SS "PCSCRED" -.sp .LP Set the target process credentials to the values contained in the \fBprcred_t\fR structure operand (see \fB/proc/\fR\fIpid\fR\fB/cred\fR). The @@ -2336,13 +2303,11 @@ set. The target process's supplementary groups are not changed; the ignored. Only the privileged processes can perform this operation; for all others it fails with \fBEPERM\fR. .SS "PCSCREDX" -.sp .LP Operates like \fBPCSCRED\fR but also sets the supplementary groups; the length of the data written with this control operation should be "sizeof (\fBprcred_t\fR) + sizeof (\fBgid_t)\fR * (#groups - 1)". .SS "PCSPRIV" -.sp .LP Set the target process privilege to the values contained in the \fBprpriv_t\fR operand (see \fB/proc/pid/priv\fR). The effective, permitted, inheritable, and @@ -2360,7 +2325,6 @@ of the sets in the target process. If any of the above restrictions are not met, \fBEPERM\fR is returned. If the structure written is improperly formatted, \fBEINVAL\fR is returned. .SH PROGRAMMING NOTES -.sp .LP For security reasons, except for the \fBpsinfo\fR, \fBusage\fR, \fBlpsinfo\fR, \fBlusage\fR, \fBlwpsinfo\fR, and \fBlwpusage\fR files, which are @@ -2419,7 +2383,6 @@ descriptor has become invalid. \fBPOLLNVAL\fR is returned immediately if to a system process (see \fBPCSTOP\fR). The requested events may be empty to wait simply for termination. .SH FILES -.sp .ne 2 .na \fB\fB/proc\fR\fR @@ -2582,6 +2545,16 @@ process aux vector .sp .ne 2 .na +\fB\fB/proc/\fIpid\fR/argv\fR\fR +.ad +.sp .6 +.RS 4n +process argument vector +.RE + +.sp +.ne 2 +.na \fB\fB/proc/\fIpid\fR/ldt\fR\fR .ad .sp .6 @@ -2820,7 +2793,6 @@ For an agent LWP, the controlling process .RE .SH SEE ALSO -.sp .LP \fBls\fR(1), \fBps\fR(1), \fBchroot\fR(1M), \fBalarm\fR(2), \fBbrk\fR(2), \fBchdir\fR(2), \fBchroot\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2), @@ -2836,7 +2808,6 @@ For an agent LWP, the controlling process \fBwait\fR(3C), \fBcontract\fR(4), \fBcore\fR(4), \fBprocess\fR(4), \fBlfcompile\fR(5), \fBprivileges\fR(5) .SH DIAGNOSTICS -.sp .LP Errors that can occur in addition to the errors normally associated with file system access: @@ -2991,14 +2962,12 @@ restrictions. See \fBprivileges\fR(5). .RE .SH NOTES -.sp .LP Descriptions of structures in this document include only interesting structure elements, not filler and padding fields, and may show elements out of order for descriptive clarity. The actual structure definitions are contained in \fB<procfs.h>\fR\&. .SH BUGS -.sp .LP Because the old \fBioctl\fR(2)-based version of \fB/proc\fR is currently supported for binary compatibility with old applications, the top-level diff --git a/usr/src/man/man5/Makefile b/usr/src/man/man5/Makefile index 7c928f3473..27c549e44d 100644 --- a/usr/src/man/man5/Makefile +++ b/usr/src/man/man5/Makefile @@ -14,6 +14,7 @@ # Copyright (c) 2012 by Delphix. All rights reserved. # Copyright 2014 Nexenta Systems, Inc. # Copyright 2014 Garrett D'Amore <garrett@damore.org> +# Copyright (c) 2015, Joyent, Inc. All rights reserved. # include $(SRC)/Makefile.master @@ -41,6 +42,7 @@ MANFILES= Intro.5 \ device_clean.5 \ dhcp.5 \ environ.5 \ + epoll.5 \ eqn.5 \ eqnchar.5 \ eventfd.5 \ @@ -56,6 +58,7 @@ MANFILES= Intro.5 \ iconv_unicode.5 \ ieee802.3.5 \ ieee802.11.5 \ + inotify.5 \ ipfilter.5 \ isalist.5 \ kerberos.5 \ @@ -76,6 +79,7 @@ MANFILES= Intro.5 \ ms.5 \ mutex.5 \ nfssec.5 \ + overlay.5 \ pam_allow.5 \ pam_authtok_check.5 \ pam_authtok_get.5 \ @@ -120,6 +124,7 @@ MANFILES= Intro.5 \ tecla.5 \ term.5 \ threads.5 \ + timerfd.5 \ trusted_extensions.5 \ vgrindefs.5 \ zones.5 \ diff --git a/usr/src/man/man5/epoll.5 b/usr/src/man/man5/epoll.5 new file mode 100644 index 0000000000..94314861d9 --- /dev/null +++ b/usr/src/man/man5/epoll.5 @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH EPOLL 5 "Apr 17, 2014" +.SH NAME +epoll \- Linux-compatible I/O event notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/epoll.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBepoll\fR is a facility for efficient event-oriented I/O that has a +similar model to \fBpoll\fR(2), but does not necessitate rescanning a +set of file descriptors to wait for an event. \fBepoll\fR is of Linux +origins, and this facility is designed to be binary-compatible with +the Linux facility, including the following interfaces: + +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_create\fR(3C) creates an \fBepoll\fR instance, returning a file +descriptor. It contains a size arugment which is meaningful only in as +much as it cannot be 0. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_create1\fR(3C) also creates an \fBepoll\fR instance, but eliminates +the meaningless size argument -- replacing it instead with a flags +argument. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_ctl\fR(3C) allows file descriptors to be added +(via \fBEPOLL_CTL_ADD\fR), deleted (via \fBEPOLL_CTL_DEL\fR) or +modified (via \fBEPOLL_CTL_MOD\fR) with respect to the \fBepoll\fR'd set +of file descriptors. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_wait\fR(3C) fetches pending events for file descriptors added +via \fBepoll_ctl\fR(3C), blocking the caller if no such events are pending. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBepoll_pwait\fR(3C) opeates in a similar manner to \fBepoll_wait\fR(3C), but +allows the caller to specify a signal mask to be set atomically with respect +to waiting for events. +.RE + +.sp +.SH NOTES +.sp +.LP + +The \fBepoll\fR facility is implemented +for purposes of offering compatibility to and portability of Linux-borne +applications; native applications should continue to prefer using event ports +via the \fBport_create\fR(3C), +\fBport_associate\fR(3C) and \fBport_getn\fR(3C) interfaces. +In particular, use of \fBepoll\fR in a multithreaded environment is fraught +with peril; even when using \fBEPOLLONESHOT\fR for one-shot events, +there are race conditions with respect to \fBclose\fR(2) that are unresolvable. +(For more details, see the aborted effort in Linux to resolve this via the +proposed +\fBEPOLL_CTL_DISABLE\fR operation.) +The event port facility -- like the BSD kqueue facility that inspired it -- +is designed to deal with such issues via explicit event source dissociation. + +While a best effort has been made to mimic the Linux semantics, there +are some semantics that are too peculiar or ill-conceived to merit +accommodation. In particular, the Linux \fBepoll\fR facility will -- by +design -- continue to generate events for closed file descriptors where/when +the underlying file description remains open. For example, if one were +to \fBfork\fR(2) and subsequently close an actively \fBepoll\fR'd file +descriptor in the parent, +any events generated in the child on the implicitly duplicated file descriptor +will continue to be delivered to the parent -- despite the fact that the +parent itself no longer has any notion of the file description! +This \fBepoll\fR facility refuses to honor +these semantics; closing the \fBEPOLL_CTL_ADD\fR'd file descriptor +will always result in no further +events being generated for that event description. + +.SH SEE ALSO +.sp +.LP +\fBepoll_create\fR(3C), \fBepoll_create1\fR(3C), \fBepoll_ctl\fR(3C), +\fBepoll_wait\fR(3C), \fBepoll_pwait\fR(3C), +\fBport_create\fR(3C), \fBport_associate\fR(3C), \fBport_dissociate\fR(3C), +\fBport_get\fR(3C), +\fBpselect\fR(3C) diff --git a/usr/src/man/man5/inotify.5 b/usr/src/man/man5/inotify.5 new file mode 100644 index 0000000000..9b0016101d --- /dev/null +++ b/usr/src/man/man5/inotify.5 @@ -0,0 +1,305 @@ +'\" te +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH INOTIFY 5 "Sep 17, 2014" +.SH NAME +inotify \- Linux-compatible file event notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/inotify.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBinotify\fR is a facility for receiving file system events on specified +files or directories. When monitoring a directory, \fBinotify\fR can be +used to retrieve events not only on the directory, but also on any files +that the directory contains. \fBinotify\fR originated with Linux, and +this facility is designed to be binary-compatible with the Linux facility, +including the following interfaces: + +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_init\fR(3C) creates an \fBinotify\fR instance, returning a file +descriptor associated with the in-kernel event queue. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_init1\fR(3C) also creates an \fBinotify\fR instance, but allows +for a flags argument that controls some attributes of the returned file +descriptor. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_add_watch\fR(3C) allows a watch of a particular file or directory +to be added to a watch list associated with the specified \fBinotify\fR +instance. \fBinotify_add_watch\fR(3C) returns a watch descriptor that will +be reflected in the \fIwd\fR member of the \fIinotify_event\fR structure +returned via a \fBread\fR(2) of the instance. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinotify_rm_watch\fR(3C) removes the watch that corresponds to the specified +watch descriptor. +.RE + +When all file descriptors referring to a particular \fBinotify\fR instance +are closed, the instance and all watches associated with that instance are +freed. + +To consume events on an \fBinotify\fR instance, an application should +issue a \fBread\fR(2) to the instance. If no events are available +(and the \fBinotify\fR instance has not been explicitly made non-blocking +via \fBinotify_init1\fR(3C)) the \fBread\fR(2) will block until a +watched event occurs. If and when events are available, \fBread\fR(2) will +return an array of the following structures: + +.sp +.in +2 +.nf +struct inotify_event { + int wd; /* watch descriptor */ + uint32_t mask; /* mask of event */ + uint32_t cookie; /* cookie for associating renames */ + uint32_t len; /* size of name field */ + char name[]; /* optional name */ +}; +.fi +.in -2 + +\fIwd\fR contains the watch descriptor that corresponds to the event, +as returned by \fBinotify_add_watch\fR(3C). + +\fImask\fR is a bitwise \fBOR\fR of event masks (see below) that +describes the event. + +\fIcookie\fR is an opaque value that can be used to associate different +events into a single logical event. In particular, it allows consumers to +associate \fBIN_MOVED_FROM\fR events with subsequent \fBIN_MOVED_TO\fR +events. + +\fIlen\fR denotes the length of the \fIname\fR field, including any padding +required for trailing null bytes and alignment. The size of the entire +event is therefore the size of the \fIinotify_event\fR structure plus the +value of \fIlen\fR. + +\fIname\fR contains the name of the file associated with the event, if any. +This field is only present when the watched entity is a directory and +the event corresponds to a file that was contained by the watched directory +(though see \fBNOTES\fR and \fBWARNINGS\fR for details and limitations). +When present, \fIname\fR is null terminated, and may contain additional +zero bytes +to pad for alignment. (The length of this field -- including any bytes +for alignment -- is denoted by the \fIlen\fR field.) + +.SS "Events" + +The events that can be generated on a watched entity are as follows: + +.sp +.in +2 +.TS +c c +l l . +\fIEvent\fR \fIDescription\fR +\fBIN_ACCESS\fR File/directory was accessed +\fBIN_ATTRIB\fR File/directory attributes were changed +\fBIN_CLOSE_WRITE\fR File/directory opened for writing was closed +\fBIN_CLOSE_NOWRITE\fR File/directory not opened for writing was closed +\fBIN_CREATE\fR File/directory created in watched directory +\fBIN_DELETE\fR File/directory deleted from watched directory +\fBIN_DELETE_SELF\fR Watched file/directory was deleted +\fBIN_MODIFY\fR File/directory was modified +\fBIN_MODIFY_SELF\fR Watched file/directory was modified +\fBIN_MOVED_FROM\fR File was renamed from entity in watched directory +\fBIN_MOVED_TO\fR File was renamed to entity in watched directory +\fBIN_OPEN\fR File/directory was opened +.TE +.in -2 + +Of these, all events except \fBIN_MOVE_SELF\fR and \fBIN_DELETE_SELF\fR +can refer to either the watched entity or (if the watched entity +is a directory) a file or directory contained by the watched directory. +(See \fBNOTES\fR and \fBWARNINGS\fR, below for details on this +mechanism and its limitations.) +If the event corresponds to a contained entity, +\fIname\fR will be set to the name of the affected +entity. + +In addition to speciyfing events of interest, watched events may +be modified by potentially setting any of the following when adding a +watch via \fBinotify_add_watch\fR(3C): + +.sp +.ne 2 +.na +\fBIN_DONT_FOLLOW\fR +.ad +.RS 12n +Don't follow the specified pathname if it is a symbolic link. +.RE + +.sp +.ne 2 +.na +\fBIN_EXCL_UNLINK\fR +.ad +.RS 12n +If watching a directory and a contained entity becomes unlinked, cease +generating events for that entity. (By default, contained entities will +continue to generate events on their former parent directory.) +.RE + +.sp +.ne 2 +.na +\fBIN_MASK_ADD\fR +.ad +.RS 12n +If the specified pathname is already being watched, the specified events +will be added to the watched events instead of the default behavior of +replacing them. (If one +may forgive the editorializing, this particular interface gewgaw +seems entirely superfluous, and a canonical example of +feasibility trumping wisdom.) +.RE + +.sp +.ne 2 +.na +\fBIN_ONESHOT\fR +.ad +.RS 12n +Once an event has been generated for the watched entity, remove the +watch from the watch list as if \fBinotify_rm_watch\fR(3C) had been called +on it (thereby inducing an \fBIN_IGNORED\fR event). +.RE + +.sp +.ne 2 +.na +\fBIN_ONLYDIR\fR +.ad +.RS 12n +Only watch the specified pathname if it is a directory. +.RE + +In addition to the specified events, the following bits may be specified +in the \fImask\fR field as returned from \fBread\fR(2): + +.sp +.ne 2 +.na +\fBIN_IGNORED\fR +.ad +.RS 12n +A watch was removed explicitly (i.e, via \fBinotify_rm_watch\fR(3C)) or +implicitly (e.g., because \fBIN_ONESHOT\fR was set or because the watched +entity was deleted). +.RE + +.sp +.ne 2 +.na +\fBIN_ISDIR\fR +.ad +.RS 12n +The entity inducing the event is a directory. +.RE + +.sp +.ne 2 +.na +\fBIN_Q_OVERFLOW\fR +.ad +.RS 12n +The event queue exceeded the maximum event queue length per instance. +(By default, this is 16384, but it can be tuned by setting +\fBinotify_maxevents\fR via \fB/etc/system\fR.) +.RE + +.sp +.ne 2 +.na +\fBIN_UNMOUNT\fR +.ad +.RS 12n +The filesystem containing the watched entity was unmounted. +.RE + +.sp +.SH NOTES +.sp +.LP + +\fBinotify\fR instances can be monitored via \fBpoll\fR(2), +\fBport_get\fR(3C), \fBepoll\fR(5), etc. + +The event queue associated with an \fBinotify\fR instance is serialized +and ordered: events will be placed on the tail of the queue in the order +that they occur. + +If at the time an event occurs the tail of the event queue is identical +to the newly received event, the newly received event will be dropped, +effectively coalescing the two events. + +When watching a directory and receieving events on contained elements +(i.e., a contained file or subdirectory), note that the information +received in the \fIname\fR field may be stale: the file may have been +renamed between the event and its processing. If a file has been unlinked +(and if \fBIN_EXCL_UNLINK\fR has not been set), +the \fIname\fR will reflect the last name that resolved to the file. +If a new file is created in the same directory with the old name, events +on the new file and the old (unlinked) file will become undistinguishable. + +The number of bytes that are available to be read on an \fBinotify\fR +instance can be determined via a \fBFIONREAD\fR \fBioctl\fR(2). + +.sp +.SH WARNINGS +.sp +.LP + +While a best effort has been made to mimic the Linux semantics, there +remains a fundamental difference with respect to hard links: on Linux, +if a file has multiple hard links to it, a notification on a watched +directory or file will be received if and only if that event was received +via the watched path. For events that are induced by open files +(such as \fBIN_MODIFY\fR), these semantics seem peculiar: the watched +file is in fact changing, but because it is not changing via the watched +path, no notification is received. By contrast, the implementation here +will always yield an event in this case -- even if the event was induced +by an \fBopen\fR(2) via an unwatched path. If an event occurs within a +watched directory on a file for which there exist multiple hard links within +the same (watched) directory, the event's \fIname\fR will correspond to one +of the links to the file. If multiple hard links exist to the +same file in the same watched directory and one of the links is removed, +notifications may not necessarily continue to be received for the file, +despite the (remaining) link in the watched directory; users of +\fBinotify\fR should exercise extreme caution when watching directories +that contain files with multiple hard links in the same directory. + +.SH SEE ALSO +.sp +.LP +\fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), \fBinotify_add_watch\fR(3C), +\fBinotify_rm_watch\fR(3C), \fBport_get\fR(3C), \fBepoll\fR(5) diff --git a/usr/src/man/man5/overlay.5 b/usr/src/man/man5/overlay.5 new file mode 100644 index 0000000000..12134ebb82 --- /dev/null +++ b/usr/src/man/man5/overlay.5 @@ -0,0 +1,499 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2015 Joyent, Inc. +.\" +.Dd Apr 09, 2015 +.Dt OVERLAY 5 +.Os +.Sh NAME +.Nm overlay +.Nd Overlay Devices +.Sh DESCRIPTION +Overlay devices are a GLDv3 device that allows users to create overlay +networks that can be used to form the basis of network virtualization +and software defined networking. Overlay networks allow a single +physical network, often called an +.Sy underlay +network, to provide the means for creating multiple logical, isolated, +and discrete layer two and layer three networks on top of it. +.Pp +Overlay devices are administered through +.Xr dladm 1M . +Overlay devices themselves cannot be plumbed up with +.Sy IP , +.Sy vnd , +or any other protocol. Instead, like an +.Sy etherstub , +they allow for VNICs to be created on top of them. Like an +.Sy etherstub , +an overlay device acts as a local switch; however, when it encounters a +non-local destination address, it instead looks up where it should send +the packet, encapsulates it, and sends it out another interface in the +system. +.Pp +A single overlay device encapsulates the logic to answer two different, +but related, questions: +.Pp +.Bl -enum -offset indent -compact +.It +How should a packet be transformed and put on the wire? +.It +Where should a transformed packet be sent? +.El +.Pp +Each of these questions is answered by a plugin. The first question is +answered by what's called an +.Em encapsulation plugin . +The second question is answered by what's called a +.Em search plugin . +Packets are encapsulated and decapsulated using the encapsulation plugin +by the kernel. The search plugins are all user land plugins that are +consumed by the varpd service whose FMRI is +.Em svc:/network/varpd:default . +This separation allows for the kernel to be responsible for the data +path, while having the search plugins in userland allows the system to +provide a much more expressive interface. +.Ss Overlay Types +Overlay devices come in +two different flavors, one where all packets are always sent to a single +address, the other, where the destination of a packet varies based on +the target MAC address of the packet. This information is maintained in +a +.Em target table , +which is independent and unique to each overlay device. We call the +plugins that send traffic to a single location, for example a single +unicast or multicast IP address, a +.Sy point to point +overlay and the overlay devices that can send traffic to different +locations based on the MAC address of that packet a +.Sy dynamic +overlay. The plugin type is determined based on the type of the +.Sy search plugin . +These are all fully listed in the section +.Sx Plugins and their Properties . +.Ss Overlay Destination +Both encapsulation and search plugins define the kinds of destinations +that they know how to support. An encapsulation plugin always has a +single destination type that's determined based on how the encapsulation +is defined. A search plugin, on the other hand, can support multiple +combinations of destinations. A search plugin must support the +destination type of the encapsulation device. The destination may +require any of the following three pieces of information, depending on +the encapsulation plugin: +.Bl -hang -width Ds +.It Sy MAC Address +.Bd -filled -compact +An Ethernet MAC address is required to determine the destination. +.Ed +.It Sy IP Address +.Bd -filled -compact +An IP address is required. Both IPv4 and IPv6 addresses are supported. +.Ed +.It Sy Port +.Bd -filled -compact +An IP protocol level (TCP, UDP, SCTP, etc.) port is required. +.Ed +.El +.Pp +The list of destination types that are supported by both the search and +encapsulation plugins is listed in the section +.Sx Plugins and their Properties . +.Ss varpd +The varpd service, mentioned above, is responsible for providing the +virtual ARP daemon. Its responsibility is conceptually similar to ARP. +It runs all instances of search plugins in the system and is responsible +for answering the kernel's ARP-like questions for where packets should +be sent. +.Pp +The varpd service, svc:/network/varpd:default, must be enabled for +overlay devices to function. If it is disabled while there are active +devices, then most overlay devices will not function correctly and +likely will end up dropping traffic. +.Sh PLUGINS AND PROPERTIES +Properties fall into three categories in the system: +.Bl -enum -offset indent -compact +.It +Generic properties all overlay devices have +.It +Properties specific to the encapsulation plugin +.It +Properties specific to the search plugin +.El +.Pp +Each property in the system has the following attributes, which mirror +the traditional +.Xr dladm 1M +link properties: +.Bl -hang -width Ds +.It Sy Name +.Bd -filled -compact +The name of a property is namespaced by its module and always structured +and referred to as as module/property. This allows for both an +encapsulation and search plugin to have a property with the same name. +Properties that are valid for all overlay devices and not specific to a +module do not generally use a module prefix. +.Pp +For example, the property +.Sy vxlan/listen_ip +is associated with the +.Sy vxlan +encapsulation module. +.Ed +.It Sy Type +.Bd -filled -compact +Each property in the system has a type. +.Xr dladm 1M +takes care of converting between the internal representation and a +value, but the type influences the acceptable input range. The types +are: +.Bl -hang -width Ds +.It Sy INT +A signed integer that is up to eight bytes long +.Pq Sy int64_t . +.It Sy UINT +An unsigned integer that is up to eight bytes long +.Pq Sy uint64_t . +.It Sy IP +Either an IPv4 or IPv6 address in traditional string form. For example, +192.168.128.23 or 2001:470:8af4::1:1. IPv4 addresses may also be encoded +as IPv4-mapped IPv6 addresses. +.It Sy STRING +A string of ASCII or UTF-8 encoded characters terminated with a +.Sy NUL +byte. The maximum string length, including the terminator, is currently +256 bytes. +.El +.Ed +.It Sy Permissions +.Bd -filled -compact +Each property has permissions associated with it, which indicate whether +the system considers them read-only properties or read-write properties. +A read-only property can never be updated once the device is created. +This generally includes things like the overlay's encapsulation module. +.Ed +.It Sy Required +.Bd -filled -compact +This property indicates whether the property is required for the given +plugin. If it is not specified during a call to +.Sy dladm create-overlay , +then the overlay cannot be successfully created. Properties which have a +.Sy default +will use that value if one is not specified rather than cause the +overlay creation to fail. +.Ed +.It Sy Current Value +.Bd -filled -compact +The current value of a property, if the property has a value set. +Required properties always have a value set. +.Ed +.It Sy Default Value +.Bd -filled -compact +The default value is an optional part of a given property. If a property +does define a default value, then it will be used when an overlay is +created and no other value is given. +.Ed +.It Sy Value ranges +.Bd -filled -compact +Value ranges are an optional part of a given property. They indicate a +range or set of values that are valid and may be set for a property. A +property may not declare such a range as it may be impractical or +unknown. For example, most properties based on IP addresses will not +declare a range. +.Ed +.El +.Pp +The following sections describe both the modules and the properties that +exist for each module, noting their name, type, permissions, whether or +not they are required, and if there is a default value. In addition, the +effects of each property will be described. +.Ss Encapsulation Plugins +.Bl -hang -width Ds +.It Sy vxlan +The +.Sy vxlan +module is a UDP based encapsulation method. It takes a frame that would +be put on the wire, wraps it up in a VXLAN header and places it in a UDP +packet that gets sent out on the underlying network. For more details +about the specific format of the VXLAN header, see +.Xr vxlan 7P . +.Pp +The +.Sy vxlan +module requires both an +.Sy IP address +and +.Sy port +to address it. It has a 24-bit virtual network ID space, allowing for +virtual network identifiers that range from +.Sy 0 +- +.Sy 16777215 . +.Pp +The +.Sy vxlan +module has the following properties: +.Bl -hang -width Ds +.It Sy vxlan/listen_ip +.Bd -filled -compact +Type: +.Sy IP | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled +The +.Sy vxlan/listen_ip +property determines the IP address that the system will accept VXLAN +encapsulated packets on for this overlay. +.Ed +.It Sy vxlan/listen_port +.Bd -filled -compact +Type: +.Sy UINT | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled -compact +Default Value: +.Sy 4789 | +Range: +.Sy 0 - 65535 +.Ed +.Bd -filled +The +.Sy vxlan/listen_port +property determines the UDP port that the system will listen on for +VXLAN traffic for this overlay. The default value is +.Sy 4789 , +the IANA assigned port for VXLAN. +.Ed +.El +.Pp +The +.Sy vxlan/listen_ip +and +.Sy vxlan/listen_port +properties determine how the system will accept VXLAN encapsulated +packets for this interface. It does not determine the interface that +packets will be sent out over. Multiple overlays that all use VXLAN can +share the same IP and port combination, as the virtual network +identifier can be used to tell the different overlays apart. +.El +.Ss Search Plugins +Because search plugins may support multiple destinations, they may have +more properties listed than necessarily show up for a given overlay. +For example, the +.Sy direct +plugin supports destinations that are identified by both an IP address +and a port, or just an IP address. In cases where the device is created +over an overlay that only uses an IP address for its destination, then +it will not have the +.Sy direct/dest_port +property. +.Bl -hang -width Ds +.It Sy direct +The +.Sy direct +plugin is a point to point module that can be used to create an overlay +that forwards all non-local traffic to a single destination. It supports +destinations that are a combination of an +.Sy IP Address +and a +.Sy port . +.Pp +The +.Sy direct +plugin has the following properties: +.Bl -hang -width Ds +.It Sy direct/dest_ip +.Bd -filled -compact +Type: +.Sy IP | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled +The +.Sy direct/dest_ip +property indicates the IP address that all traffic will be sent out. +Traffic will be sent out the corresponding interface based on +traditional IP routing rules and the configuration of the networking +stack of the global zone. +.Ed +.It Sy direct/dest_port +.Bd -filled -compact +Type: +.Sy UINT | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled -compact +Default Value: +.Sy - | +Range: +.Sy 0 - 65535 +.Ed +.Bd -filled +The +.Sy direct/dest_port +property indicates the TCP or UDP port that all traffic will be directed +to. +.Ed +.El +.It Sy files +The +.Sy files +plugin implements a +.Sy dynamic +plugin that specifies where traffic should be sent based on a file. It +is a glorified verison of /etc/ethers. The +.Sy dynamic +plugin does not support broadcast or multicast traffic, but it has +support for proxy ARP, NDP, and DHCPv4. For the full details of the file +format, see +.Xr overlay_files 4 . +.Pp +The +.Sy files +plugin has the following property: +.Bl -hang -width Ds +.It Sy files/config +.Bd -filled -compact +Type: +.Sy String | +Permissions: +.Sy Read/Write | +.Sy Required +.Ed +.Bd -filled +The +.Sy files/config +property specifies an absolute path to a file to read. The file is a +JSON file that is formatted according to +.Xr overlay_files 4 . +.Ed +.El +.El +.Ss General Properties +Each overaly has the following properties which are used to give +additional information about the system. None of these properties may be +specified as part of a +.Sy dladm create-overlay , +instead they come from other arguments or from internal parts of the +system. +.Bl -hang -width Ds +.It Sy encap +.Bd -filled -compact +.Sy String | +Permissions: +.Sy Read Only +.Ed +.Bd -filled +The +.Sy encap +property contains the name of the encapsulation module that's in use. +.Ed +.It Sy mtu +.Bd -filled -compact +.Sy UINT | +Permissions: +.Sy Read/Write +.Ed +.Bd -filled -compact +Default Value: +.Sy 1400 | +Range: +.Sy 576 - 9000 +.Ed +.Bd -filled +The +.Sy mtu +property describes the maximum transmission unit of the overlay. The +default value is +.Sy 1400 +bytes, which ensures that in a traditional deployment with an MTU of +1500 bytes, the overhead that is added from encapsulation is all +accounted for. It is the administrator's responsibility to ensure that +the device's MTU and the encapsulation overhead does not exceed that of +the interfaces that the encapsulated traffic will be sent out of. +.Pp +To modify the +.Sy mtu +property, use +.Sy dladm set-linkprop . +.Ed +.It Sy search +.Bd -filled -compact +.Sy String | +Permissions: +.Sy Read Only +.Ed +.Bd -filled +The +.Sy search +property contains the name of the search plugin that's in use. +.Ed +.It Sy varpd/id +.Bd -filled -compact +.Sy String | +Permissions: +.Sy Read Only +.Ed +.Bd -filled +The +.Sy varpd/id +property indicates the identifier which the +.Sy varpd +service uses for this overlay. +.Ed +.It Sy vnetid +.Bd -filled -compact +.Sy UINT | +Permissions: +.Sy Read/Write +.Ed +.Bd -filled +The +.Sy vnetid +property has the virtual network identifier that belongs to this overlay. +The valid range for the virtual network identifier depends on the +encapsulation engine. +.Ed +.El +.Sh FMA INTEGRATION +Overlay devices are wired into FMA, the illumos fault management +architecture, and generates error reports depending on the +.Sy search +plugin in use. Due to limitations in FMA today, when a single overlay +enters a degraded state, meaning that it cannot properly perform look +ups or another error occurred, then it degrades the overall +.Sy overlay +psuedo-device driver. +.Pp +For more fine-grained information about which overlay is actually in a +.Em degraded +state, one should run +.Sy dladm show-overlay -f . +In addition, for each overlay in a degraded state a more useful +diagnostic message is provided which describes the reason that caused +this overlay to enter into a degraded state. +.Pp +The overlay driver is self-healing. If the problem corrects itself on +its own, it will clear the fault on the corresponding device. +.Sh SEE ALSO +.Xr dladm 1M , +.Xr overlay_files 4 , +.Xr vxlan 7P diff --git a/usr/src/man/man5/privileges.5 b/usr/src/man/man5/privileges.5 index 294eb378b4..4eac17d831 100644 --- a/usr/src/man/man5/privileges.5 +++ b/usr/src/man/man5/privileges.5 @@ -1,10 +1,10 @@ '\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright 2013, Joyent, Inc. All Rights Reserved. +.\" Copyright 2015, Joyent, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PRIVILEGES 5 "Feb 3, 2015" +.TH PRIVILEGES 5 "Apr 15, 2015" .SH NAME privileges \- process privilege model .SH DESCRIPTION @@ -235,7 +235,9 @@ modify that file's or directory's permission bits or ACL. .ad .sp .6 .RS 4n -Allow a process to read objects in the filesystem. +Allow a process to open objects in the filesystem for reading. This +privilege is not necessary to read from an already open file which was opened +before dropping the \fBPRIV_FILE_READ\fR privilege. .RE .sp @@ -275,7 +277,9 @@ Extensions. .ad .sp .6 .RS 4n -Allow a process to modify objects in the filesytem. +Allow a process to open objects in the filesytem for writing, or otherwise +modify them. This privilege is not necessary to write to an already open file +which was opened before dropping the \fBPRIV_FILE_WRITE\fR privilege. .RE .sp @@ -303,6 +307,16 @@ Allow a process to perform privileged mappings through a graphics device. .sp .ne 2 .na +\fB\fBPRIV_HYPRLOFS_CONTROL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to perform hyprlofs name space management. +.RE + +.sp +.ne 2 +.na \fB\fBPRIV_IPC_DAC_READ\fR\fR .ad .sp .6 @@ -344,7 +358,9 @@ Segment. .ad .sp .6 .RS 4n -Allow a process to open a TCP, UDP, SDP, or SCTP network endpoint. +Allow a process to open a TCP, UDP, SDP, or SCTP network endpoint. This +privilege is not necessary to communicate using an existing endpoint already +opened before dropping the \fBPRIV_NET_ACCESS\fR privilege. .RE .sp @@ -517,6 +533,16 @@ Allow a process to lock pages in physical memory. .sp .ne 2 .na +\fB\fBPRIV_PROC_MEMINFO\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to access physical memory information. +.RE + +.sp +.ne 2 +.na \fB\fBPRIV_PROC_OWNER\fR\fR .ad .sp .6 @@ -670,6 +696,16 @@ Allow a process to configure a system's datalink interfaces. .sp .ne 2 .na +\fB\fBPRIV_SYS_FS_IMPORT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to import a potentially untrusted file system (e.g. ZFS recv). +.RE + +.sp +.ne 2 +.na \fB\fBPRIV_SYS_IP_CONFIG\fR\fR .ad .sp .6 @@ -1057,7 +1093,8 @@ x86 platforms. .sp .LP Of the privileges listed above, the privileges \fBPRIV_FILE_LINK_ANY\fR, -\fBPRIV_PROC_INFO\fR, \fBPRIV_PROC_SESSION\fR, \fBPRIV_PROC_FORK\fR and +\fBPRIV_PROC_INFO\fR, \fBPRIV_PROC_SESSION\fR, \fBPRIV_PROC_FORK\fR, +\fBPRIV_FILE_READ\fR, \fBPRIV_FILE_WRITE\fR, \fBPRIV_NET_ACCESS\fR and \fBPRIV_PROC_EXEC\fR are considered "basic" privileges. These are privileges that used to be always available to unprivileged processes. By default, processes still have the basic privileges. diff --git a/usr/src/man/man5/resource_controls.5 b/usr/src/man/man5/resource_controls.5 index 745d777624..35a78aae6e 100644 --- a/usr/src/man/man5/resource_controls.5 +++ b/usr/src/man/man5/resource_controls.5 @@ -1,16 +1,18 @@ '\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2012, Joyent, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH RESOURCE_CONTROLS 5 "Jul 19, 2013" .SH NAME -resource_controls \- resource controls available through project database +resource_controls \- resource controls available through projects and zones .SH DESCRIPTION .sp .LP -The resource controls facility is configured through the project database. See -\fBproject\fR(4). You can set and modify resource controls through the +For projects the resource controls facility is configured through the project +database. See \fBproject\fR(4). For zones, resource controls are configured +through \fBzonecfg\fR(1M). You can set and modify resource controls through the following utilities: .RS +4 .TP @@ -36,6 +38,12 @@ following utilities: .el o \fBrctladm\fR(1M) .RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBzonecfg\fR(1M) +.RE .sp .LP In a program, you use \fBsetrctl\fR(2) to set resource control values. @@ -283,6 +291,19 @@ Maximum allowable number of event ports, expressed as an integer. .sp .ne 2 .na +\fB\fBproject.max-processes\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of processes that can be active in a project. This rctl is +similar to \fBproject.max-lwps\fR, except that zombie processes are included. +This rctl prevents process-slot exhaustion which can occur due to an excessive +number of zombies. Expressed as an integer. +.RE + +.sp +.ne 2 +.na \fB\fBproject.max-sem-ids\fR\fR .ad .sp .6 @@ -371,6 +392,33 @@ The following zone-wide resource controls are available: .sp .ne 2 .na +\fB\fBzone.cpu-baseline\fR\fR +.ad +.sp .6 +.RS 4n +Sets a baseline amount of CPU time that a zone can use before it is considered +to be bursting. The unit used is the percentage of a single CPU that is being +used by all user threads in a zone. The value should be less than the +\fBzone.cpu-cap\fR rctl value and is expressed as an integer. +This resource control does not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na +\fB\fBzone.cpu-burst-time\fR\fR +.ad +.sp .6 +.RS 4n +Sets the number of seconds that a zone can exceed the \fBzone.cpu-baseline\fR +rctl value before being cpu-capped down to the \fBzone.cpu-baseline\fR. +A value of 0 means that \fBzone.cpu-baseline\fR can be exceeded indefinitely. +This resource control does not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na \fB\fBzone.cpu-cap\fR\fR .ad .sp .6 @@ -389,7 +437,7 @@ not support the \fBsyslog\fR action. .ad .sp .6 .RS 4n -Sets a limit on the number of fair share scheduler (FSS) CPU shares for a zone. +Sets a value on the number of fair share scheduler (FSS) CPU shares for a zone. CPU shares are first allocated to the zone, and then further subdivided among projects within the zone as specified in the \fBproject.cpu-shares\fR entries. Expressed as an integer. This resource control does not support the @@ -409,14 +457,25 @@ Total amount of physical locked memory available to a zone. .sp .ne 2 .na +\fB\fBzone.max-lofi\fR\fR +.ad +.sp .6 +.RS 4n +Sets a limit on the number of \fBLOFI\fR(7D) devices that can be created in a +zone. Expressed as an integer. This resource control does not support the +\fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na \fB\fBzone.max-lwps\fR\fR .ad .sp .6 .RS 4n -Enhances resource isolation by preventing too many LWPs in one zone from -affecting other zones. A zone's total LWPs can be further subdivided among -projects within the zone within the zone by using \fBproject.max-lwps\fR -entries. Expressed as an integer. +Sets a limit on how many LWPs can be active in a zone. A zone's total LWPs +can be further subdivided among projects within the zone within the zone by +using \fBproject.max-lwps\fR entries. Expressed as an integer. .RE .sp @@ -433,6 +492,33 @@ integer. .sp .ne 2 .na +\fB\fBzone.max-physical-memory\fR\fR +.ad +.sp .6 +.RS 4n +Sets a limit on the amount of physical memory (RSS) that can be used by a zone +before resident pages start being forcibly paged out. The unit used is bytes. +Expressed as an integer. This resource control does not support the +\fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na +\fB\fBzone.max-processes\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of processes that can be active in a zone. This rctl is +similar to \fBzone.max-lwps\fR, except that zombie processes are included. +This rctl prevents process-slot exhaustion which can occur due to an excessive +number of zombies. This rctl can be further subdivided among projects within +the zone using \fBproject.max-processes\fR. Expressed as an integer. +.RE + +.sp +.ne 2 +.na \fB\fBzone.max-sem-ids\fR\fR .ad .sp .6 @@ -474,6 +560,18 @@ mappings and \fBtmpfs\fR mounts for this zone. .RE .sp +.ne 2 +.na +\fB\fBzone.zfs-io-priority\fR\fR +.ad +.sp .6 +.RS 4n +Sets a value for the \fBzfs\fR(1M) I/O priority for a zone. This is used as +one of the inputs to determine if a zone's I/O should be throttled. Expressed +as an integer. This resource control does not support the \fBsyslog\fR action. +.RE + +.sp .LP See \fBzones\fR(5). .SS "Units Used in Resource Controls" diff --git a/usr/src/man/man5/timerfd.5 b/usr/src/man/man5/timerfd.5 new file mode 100644 index 0000000000..a6829901aa --- /dev/null +++ b/usr/src/man/man5/timerfd.5 @@ -0,0 +1,44 @@ +'\" te +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH TIMERFD 5 "Feb 23, 2015" +.SH NAME +timerfd \- Linux-compatible timer notification facility +.SH SYNOPSIS + +.LP +.nf +#include <sys/timerfd.h> +.fi + +.SH DESCRIPTION +.sp +.LP + +\fBtimerfd\fR is a Linux-borne facility for creating POSIX timers and +receiving their subsequent events via a file descriptor. +The facility itself is arguably unnecessary: +portable code can either use the timeout value present in +\fBpoll\fR(2)/\fBport_get\fR(3C)/\fBepoll_wait\fR(3C) or -- if this +is deemed of unacceptably poor resolution -- create a POSIX timer +via \fBtimer_create\fR(3C) and use the resulting signal to induce an +\fBEINTR\fR to polling threads. (For code that need not be +portable, the \fBSIGEV_PORT\fR signal notification allows for explicit, +event-oriented timer notification to be sent to a specified port; +see \fBsignal.h\fR(3HEAD) for details.) +This facility therefore exists only to accommodate Linux-borne +applications and binaries; it is compatible with its Linux antecedent in both +binary interface and in semantics. + +.SH SEE ALSO +.sp +.LP +\fBtimerfd_create\fR(3C), \fBtimerfd_gettime\fR(3C), \fBtimerfd_settime\fR(3C) + diff --git a/usr/src/man/man7d/Makefile b/usr/src/man/man7d/Makefile index eb75db718a..6e8550e309 100644 --- a/usr/src/man/man7d/Makefile +++ b/usr/src/man/man7d/Makefile @@ -13,6 +13,7 @@ # Copyright 2011, Richard Lowe # Copyright 2015 Nexenta Systems, Inc. All rights reserved. # Copyright 2014 Garrett D'Amore <garrett@damore.org> +# Copyright 2014 Joyent, Inc. All rights reserved. # include $(SRC)/Makefile.master @@ -142,11 +143,13 @@ _MANFILES= aac.7d \ virtualkm.7d \ vni.7d \ vr.7d \ + vnd.7d \ wscons.7d \ xge.7d \ yge.7d \ zcons.7d \ - zero.7d + zero.7d \ + zfd.7d sparc_MANFILES= audiocs.7d \ bbc_beep.7d \ diff --git a/usr/src/man/man7d/cpuid.7d b/usr/src/man/man7d/cpuid.7d index 1ede29ccc5..b14cc64742 100644 --- a/usr/src/man/man7d/cpuid.7d +++ b/usr/src/man/man7d/cpuid.7d @@ -1,9 +1,10 @@ '\" te .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 2015, Joyent, Inc. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH CPUID 7D "Sep 16, 2004" +.TH CPUID 7D "Jun 04, 2015" .SH NAME cpuid \- CPU identification driver .SH SYNOPSIS @@ -14,29 +15,24 @@ cpuid \- CPU identification driver .SH DESCRIPTION .SS "SPARC and x86 system" -.sp .LP This device provides implementation-private information via ioctls about various aspects of the implementation to Solaris libraries and utilities. .SS "x86 systems only" -.sp .LP This device also provides a file-like view of the namespace and return values of the x86 cpuid instruction. The cpuid instruction takes a single 32-bit integer function code, and returns four 32-bit integer values corresponding to the input value that describe various aspects of the capabilities and configuration of the processor. -.sp .LP The API for the character device consists of using the seek offset to set the function code value, and using a \fBread\fR(2) or \fBpread\fR(2) of 16 bytes to fetch the four 32-bit return values of the instruction in the order %\fBeax\fR, %\fBebx\fR, %\fBecx\fR and %\fBedx\fR. -.sp .LP No data can be written to the device. Like the \fBcpuid\fR instruction, no special privileges are required to use the device. -.sp .LP The device is useful to enable low-level configuration information to be extracted from the CPU without having to write any assembler code to invoke the @@ -44,13 +40,15 @@ extracted from the CPU without having to write any assembler code to invoke the correct any erroneous data returned by the instruction (prompted by occassional errors in the information exported by various processor implementations over the years). -.sp .LP See the processor manufacturers documentation for further information about the syntax and semantics of the wide variety of information available from this instruction. +.LP +Some systems can be configured to limit the cpuid opcodes which are accessible. +While illumos handles this condition, other software may malfunction when such +limits are enabled. Those settings are typically manipulated in the BIOS. .SH EXAMPLE -.sp .LP This example allows you to determine if the current x86 processor supports "long mode," which is a necessary (but not sufficient) condition for running @@ -113,7 +111,6 @@ fail: .in -2 .SH ERRORS -.sp .ne 2 .na \fBENXIO\fR @@ -134,7 +131,6 @@ with a size that is not multiple of 16 bytes. .RE .SH FILES -.sp .ne 2 .na \fB\fB/dev/cpu/self/cpuid\fR\fR @@ -144,7 +140,6 @@ Provides access to CPU identification data. .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -160,7 +155,6 @@ Interface Stability Evolving .TE .SH SEE ALSO -.sp .LP \fBpsrinfo\fR(1M), \fBprtconf\fR(1M), \fBpread\fR(2), \fBread\fR(2), \fBattributes\fR(5) diff --git a/usr/src/man/man7d/poll.7d b/usr/src/man/man7d/poll.7d index cd3db77de9..7a3292eb97 100644 --- a/usr/src/man/man7d/poll.7d +++ b/usr/src/man/man7d/poll.7d @@ -73,15 +73,6 @@ Pointer to \fBpollfd\fR structure. .SH DESCRIPTION .LP -Note - -.sp -.RS 2 -The \fB/dev/poll\fR device, associated driver and corresponding manpages may be -removed in a future Solaris release. For similar functionality in the event -ports framework, see \fBport_create\fR(3C). -.RE -.sp -.LP The \fB/dev/poll\fR driver is a special driver that enables you to monitor multiple sets of polled file descriptors. By using the \fB/dev/poll\fR driver, you can efficiently poll large numbers of file descriptors. Access to diff --git a/usr/src/man/man7d/vnd.7d b/usr/src/man/man7d/vnd.7d new file mode 100644 index 0000000000..d311c4dc08 --- /dev/null +++ b/usr/src/man/man7d/vnd.7d @@ -0,0 +1,118 @@ +'\" te +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" +.TH VND 7D "Feb 11, 2014" +.SH NAME +vnd \- virtual layer two network driver + +.SH SYNOPSIS +.nf +.LP +/dev/vnd/ctl +.LP +/dev/vnd/* +.fi + +.SH DESCRIPTION +.sp +.LP +The vnd driver provides support for a layer two datapath in an +analogous way that IP(7P) provides a support for an IP-based layer +three datapath. Both devices operate exclusively on datalinks. A +datalink that has been plumbed up with IP via ifconfig(1M) or +ipadm(1M) cannot be used with vnd or vice-versa. +.sp +.LP +The vnd driver supports and takes advantage of the the following +illumos features: +.RS +.sp +.LP +Supports dld/dls feature negotation of GLDv3 features, such +as direct calls, flow control, checksum offloading, and more. +.sp +.LP +All IP and IPv6 based traffic is sent through ipfilter(5), +allowing packet filtering. +.sp +.LP +Better control over vectored reads and writes in a frame-centric manner +through framed I/O. See libvnd(3LIB) for more information on these +interfaces. +.RE +.sp +.LP +The vnd driver exposes two different kinds of device nodes. The first is +a self-cloning control node which can be used to create vnd devices on +top of datalinks. Those devices can optionally be bound into the file +system namespace under /dev/vnd. Control operations on the control node +or named devices are private to the implementation. Instead, +libvnd(3LIB) provides a stable interfaces for using, creating, and +manipulating vnd devices. +.sp +.SH FILES +.sp +.ne 2 +.na +/dev/vnd/ctl +.ad +.RS 16n +vnd self-cloning control node +.RE + +.sp +.ne 2 +.na +/dev/vnd/%link +.ad +.RS 16n +Character device that corresponds to the vnd device of the given +name (%link). A given device will appear for each actively linked device +in the current zone. +.RE + +.sp +.ne 2 +.na +/dev/vnd/zone/%zone/%link +.ad +.RS 16n +These are character devices that correspond to the vnd device of +the given name (%link). They are organized based on the zone that they +appear in. Thus if a zone named foo has a vnd device named +bar, then the global zone will have the file +/dev/vnd/zone/foo/bar. Note, these only occur in the global zone. +.RE + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +.TE + +.SH SEE ALSO +.sp +.LP +dladm(1M), ipflter(5), libvnd(3LIB), vndadm(1M), +vndstat(1) diff --git a/usr/src/man/man7d/zfd.7d b/usr/src/man/man7d/zfd.7d new file mode 100644 index 0000000000..f06777fee8 --- /dev/null +++ b/usr/src/man/man7d/zfd.7d @@ -0,0 +1,39 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2014, Joyent, Inc. All rights reserved. +.\" +.Dd "Dec 22, 2014" +.Dt ZFD 7D +.Os +.Sh NAME +.Nm zfd +.Nd Zone file descriptor driver +.Sh DESCRIPTION +The +.Nm zfd +character driver exports up to three file descriptors into the zone. These can +be used by a standalone process within the zone as +.Vt stdin , +.Vt stdout , +and +.Vt stderr . +The +.Nm zfd +driver behaves in a similar manner as the +.Nm zcons(7D) +device. +Inside a zone, the slave side file descriptors appear as +.Nm /dev/zfd/[0-2] . +.Sh SEE ALSO +.Xr zlogin 1 , +.Xr zoneadmd 1M , +.Xr zcons 7D diff --git a/usr/src/man/man7fs/Makefile b/usr/src/man/man7fs/Makefile index a288c94893..d985e95410 100644 --- a/usr/src/man/man7fs/Makefile +++ b/usr/src/man/man7fs/Makefile @@ -12,19 +12,23 @@ # # Copyright 2011, Richard Lowe # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2014 Joyent, Inc. All rights reserved. # include $(SRC)/Makefile.master MANSECT= 7fs -MANFILES= ctfs.7fs \ +MANFILES= bootfs.7fs \ + ctfs.7fs \ dcfs.7fs \ dev.7fs \ devfs.7fs \ fd.7fs \ hsfs.7fs \ + hyprlofs.7fs \ lofs.7fs \ + lxproc.7fs \ objfs.7fs \ pcfs.7fs \ sharefs.7fs \ diff --git a/usr/src/man/man7fs/bootfs.7fs b/usr/src/man/man7fs/bootfs.7fs new file mode 100644 index 0000000000..130530a1f6 --- /dev/null +++ b/usr/src/man/man7fs/bootfs.7fs @@ -0,0 +1,90 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2014 Joyent, Inc. All rights reserved. +.\" + +.TH BOOTFS 7FS "May 8, 2014" +.SH NAME +bootfs \- boot-time module file system + +.SH DESCRIPTION + +The +.B bootfs +file system is a read-only file system that provides access to any +boot-time modules that were passed in to the system loader which were +tagged with the type +.IR file . +.B bootfs +does not display any boot-time modules that were tagged as type +.I hash +or type +.IR rootfs . + +If modules with duplicate names and paths are specified, only the first +such entry will be present in the file system and a counter will be +incremented to indicate that a duplicate entry was found, but is not +present into the file system. If a module's name only consists of +invalid characters, such as '.', '..', or '/', then the module will not +be present in the file system and a counter will be incremented to +indicate that this has occurred. In both cases, diagnostic information +is available through the kstats facility. + +.SH FILES +.sp +.ne 2 +.na +.B /system/boot +.ad +.RS 8n +The mount point for the +.B bootfs +file system in the global zone. + +.SH EXAMPLES + +.LP +Example 1 Determining if collisions or invalid names are present +.sp +.LP +To determine if any boot-time modules were not created due to collisions +or invalid names, enter the following command: + +.sp +.in +2 +.nf +# kstat -m bootfs +module: bootfs instance: 1 +name: bootfs class: fs + crtime 236063.651324041 + nbytes 8749355 + ndirs 3 + ndiscard 0 + ndup 0 + nfiles 2 + snaptime 236063.651324041 +.fi +.in -2 +.sp +.LP +The field +.B ndiscard +lists the number of boot-time modules that were discarded due to naming conflicts. The field +.B ndup +lists the number of duplicate entries that were found and therefore not displayed in the file system. +.sp +.LP +This information is provided for informational purposes only, it is not to be construed as a stable interface. + +.SH SEE ALSO +.BR kstat (1M), +.BR grub (5) diff --git a/usr/src/man/man7fs/hyprlofs.7fs b/usr/src/man/man7fs/hyprlofs.7fs new file mode 100644 index 0000000000..8655791193 --- /dev/null +++ b/usr/src/man/man7fs/hyprlofs.7fs @@ -0,0 +1,62 @@ +'\" te +.\" Copyright (c) 2012, Joyent, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH HYPRLOFS 7FS "March 7, 2012" +.SH NAME +hyprlofs \- fast name space virtual file system +.SH SYNOPSIS +.LP +.nf +#include <sys/fs/hyprlofs.h> + +\fB\fR\fBmount\fR (\fB\fR\fIspecial\fR, \fB\fR\fIdirectory\fR, \fB\fR\fIMS_DATA\fR, \fB\fR\fI"hyprlofs"\fR, \fB\fR\fINULL\fR, \fB\fR\fI0\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBhyprlofs\fR is a hybrid file system combining features from +\fBtmpfs(7FS)\fR and \fBlofs(7FS)\fR. +As with \fBlofs\fR, the \fBhyprlofs\fR file system allows new, virtual file +systems to be created which provide access to existing files using alternate +pathnames. In addition, the files themselves may have alternate names and +paths within the mount. +Unlike \fBlofs\fR, files cannot be created and backing files cannot be removed. +The name space is completely managed through ioctls on the mount. +Entries in the name space are not mounts and thus, they will not appear in the +mnttab. The file system is designed to provide a very fast name space to the +backing files. The name space can be modified very quickly through the ioctl +interface. +.sp +.LP +\fBhyprlofs\fR file systems can be mounted with the command: +.sp +.in +2 +.nf +\fBmount \fR\fB-F\fR\fB hyprlofs swap \fR\fIdirectory\fR +.fi +.in -2 + +.sp +.LP +The name space used by \fBhyprlofs\fR exists only in-memory so it will consume +a small amount of the system's virtual memory. The files themselves are backed +by the original file as with \fBlofs\fR. + +.SH SEE ALSO +.sp +.LP +\fBdf\fR(1M), \fBmount\fR(1M), \fBswap\fR(1M), +\fBmount\fR(2), \fBumount\fR(2) +.sp +.LP +\fISystem Administration Guide: Basic Administration\fR +.SH DIAGNOSTICS +.sp +.LP +\fBdf\fR(1M) output is of limited accuracy since +the space available to \fBhyprlofs\fR is dependent on the swap +space demands of the entire system and the files in the name space are not +included. diff --git a/usr/src/man/man7fs/lxproc.7fs b/usr/src/man/man7fs/lxproc.7fs new file mode 100644 index 0000000000..7ef10ce343 --- /dev/null +++ b/usr/src/man/man7fs/lxproc.7fs @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2012, Joyent, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH LXPROC 7FS "April 25, 2012" +.SH NAME +lxproc \- a loosely Linux-compatible /proc +.SH SYNOPSIS +.LP +.nf +\fB\fR\fBmount\fR (\fB\fR\fI"lxproc"\fR, \fB\fR\fIdirectory\fR, \fB\fR\fIMS_DATA\fR, \fB\fR\fI"lxproc"\fR, \fB\fR\fINULL\fR, \fB\fR\fI0\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBlxproc\fR is an implementation of the \fB/proc\fR filesystem that +loosely matches the Linux semantics of providing human-readable text files +that correspond to elements of the system. +As with both \fBproc\fR(4) and Linux \fB/proc\fR, \fBlxproc\fR makes available +a directory for every process, with each directory containing a number +of files; like Linux \fB/proc\fR but unlike \fBproc\fR(4), \fBlxproc\fR also +makes available a number of files related to system-wide information. +To ascertain the meaning and structure of the files provided via +\fBlxproc\fR, users should consult the Linux documentation. +.sp +.LP +The \fBlxproc\fR compatibility layer is +provided only as a best-effort for simple Linux \fB/proc\fR readers; it +is not intended to exactly mimic Linux semantics and nor does it attempt to +somehow fool a consumer into believing that it is operating within a Linux +environment. As such, \fBlxproc\fR should only be used by Linux-specific +programs that are willing to trade precision in understanding the +system in return for Linux compatibility. To programmatically understand +the system precisely and in terms of its native constructs, +one should not use \fBlxproc\fR, but rather \fBproc\fR(4) or +\fBkstat\fR(3KSTAT). +To understand +a process or group of processes from either a shell script or the command line, +one should not use \fBlxproc\fR, but rather \fBproc\fR(4)-based tools like +\fBprstat\fR(1M), +\fBpfiles\fR(1), +\fBpargs\fR(1), +\fBpmap\fR(1), +\fBptree\fR(1), +\fBplimit\fR(1), +\fBpflags\fR(1), +\fBpcred\fR(1), +\fBpstack\fR(1), +\fBpldd\fR(1), +\fBpsig\fR(1), +or +\fBpwdx\fR(1). +To understand system-wide constructs from either a shell script or the +command line, one should not use \fBlxproc\fR, but rather +\fBkstat\fR(3KSTAT)-based tools like +\fBkstat\fR(1M), +\fBmpstat\fR(1M), +\fBiostat\fR(1M), +\fBnetstat\fR(1M) or +\fBpsrinfo\fR(1M). +.sp +.LP +Like \fB/proc\fR, \fBlxproc\fR can be mounted on any mount point, but the +preferred mount point is \fB/system/lxproc\fR; if a zone brand elects to +mount it by default, this will (or should) generally be the mount point. +.sp +.LP +\fBlxproc\fR can be mounted with the command: +.sp +.in +2 +.nf +\fBmount \fR\fB-F\fR\fB lxproc lxproc \fR\fIdirectory\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdf\fR(1M), +\fBiostat\fR(1M), +\fBkstat\fR(1M), +\fBmpstat\fR(1M), +\fBmount\fR(1M), +\fBnetstat\fR(1M), +\fBpargs\fR(1), +\fBpcred\fR(1), +\fBpfiles\fR(1), +\fBpflags\fR(1), +\fBpldd\fR(1), +\fBplimit\fR(1), +\fBpmap\fR(1), +\fBprstat\fR(1M), +\fBpsig\fR(1), +\fBpsrinfo\fR(1M), +\fBpstack\fR(1), +\fBptree\fR(1), +\fBpwdx\fR(1), +\fBmount\fR(2), \fBumount\fR(2), \fBkstat\fR(3KSTAT), \fBproc\fR(4), +\fBkstat\fR(9S) + +.SH NOTES +.sp +.LP +When choosing between offering +Linux compatibility and telling the truth, \fBlxproc\fR emphatically picks +the truth. A particular glaring example of this is the Linux notion of +"tasks" (that is, threads), which -- due to historical misadventures on +Linux -- allocate their identifiers from the process identifier space. +(That is, each thread has in effect a pid.) Some Linux \fB/proc\fR readers +have come to depend on this attribute, and become confused when threads +appear with proper identifiers, so \fBlxproc\fR simply opts for the pre-2.6 +behavior, and does not present the tasks directory at all. + diff --git a/usr/src/man/man7m/Makefile b/usr/src/man/man7m/Makefile index bb44184ba7..36eb293fc3 100644 --- a/usr/src/man/man7m/Makefile +++ b/usr/src/man/man7m/Makefile @@ -12,6 +12,7 @@ # # Copyright 2011, Richard Lowe # Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# Copyright 2015 Joyent, Inc. # include $(SRC)/Makefile.master @@ -20,6 +21,7 @@ MANSECT= 7m _MANFILES = bufmod.7m \ connld.7m \ + datafilt.7m \ ldterm.7m \ pckt.7m \ pfmod.7m \ diff --git a/usr/src/man/man7m/datafilt.7m b/usr/src/man/man7m/datafilt.7m new file mode 100644 index 0000000000..f74ac0b103 --- /dev/null +++ b/usr/src/man/man7m/datafilt.7m @@ -0,0 +1,46 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2014 Ryan Zezeski +.\" Copyright 2015 Joyent, Inc. +.\" +.Dd Apr 21, 2015 +.Dt DATAFILT 7M +.Os +.Sh NAME +.Nm datafilt +.Nd socket filter module for deferred TCP connections +.Sh DESCRIPTION +The +.Nm datafilt +socket filter provides deferment of +.Xr accept 3SOCKET +for TCP connections. The accept call will not return until at least +one byte has been buffered by the kernel. Deferment assures the +application that the first call to +.Xr read 2 or +.Xr recv 3SOCKET +will not block. It reduces unnecessary switching between user and +kernel. +.Sh EXAMPLES +.Ss Example 1 +Enable deferment on the listening socket. +.Bd -literal + setsockopt(lsock, SOL_FILTER, FIL_ATTACH, "datafilt", 8); +.Ed +.Ss Example 2 +Disable deferment on the listening socket. +.Bd -literal + char filt[] = "datafilt"; + setsockopt(lsock, SOL_FILTER, FIL_DETACH, filt, strlen(filt) + 1); +.Ed +.Sh SEE ALSO +.Xr setsockopt 3SOCKET diff --git a/usr/src/man/man7p/Makefile b/usr/src/man/man7p/Makefile index bbcf5ecf1d..2b3a92386b 100644 --- a/usr/src/man/man7p/Makefile +++ b/usr/src/man/man7p/Makefile @@ -38,7 +38,8 @@ MANFILES= arp.7p \ sip.7p \ slp.7p \ tcp.7p \ - udp.7p + udp.7p \ + vxlan.7p MANLINKS= AH.7p \ ARP.7p \ @@ -49,6 +50,7 @@ MANLINKS= AH.7p \ SCTP.7p \ TCP.7p \ UDP.7p \ + VXLAN.7p \ if.7p ARP.7p := LINKSRC = arp.7p @@ -71,6 +73,8 @@ TCP.7p := LINKSRC = tcp.7p UDP.7p := LINKSRC = udp.7p +VXLAN.7p := LINKSRC = vxlan.7p + .KEEP_STATE: include $(SRC)/man/Makefile.man diff --git a/usr/src/man/man7p/vxlan.7p b/usr/src/man/man7p/vxlan.7p new file mode 100644 index 0000000000..a32637b484 --- /dev/null +++ b/usr/src/man/man7p/vxlan.7p @@ -0,0 +1,124 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2015 Joyent, Inc. +.\" +.Dd Apr 10, 2015 +.Dt VXLAN 7P +.Os +.Sh NAME +.Nm VXLAN , +.Nm vxlan +.Nd Virtual eXtensible Local Area Network +.Sh SYNOPSIS +.In sys/vxlan.h +.Sh DESCRIPTION +.Nm +(RFC 7348) is a network encapsulation protocol that is used by +.Xr overlay 5 +devices. A payload, commonly an Ethernet frame, is placed inside of a +UDP packet and prepended with an 8-byte +.Nm +header. +.Pp +The +.Nm +header contains two 32-bit words. The first word is an 8-bit flags field +followed by 24 reserved bits. The second word is a 24-bit virtual network +identifier followed by 8 reserved bits. The virtual network identifier +identifies a unique +.Nm +and +is similar in concept to an IEEE 802.1Q VLAN identifier. +.Pp +The system provides access to +.Nm +through dladm overlays. See +.Xr dladm 1M +and +.Xr overlay 5 +for more information. +.Pp +The +.In sys/vxlan.h +header provides information for working with the +.Nm +protocol. The contents of this header are +.Sy uncommitted . +The header defines a structure that may be used to encode and decode a VXLAN +header. It defines a packed structure type +.Sy vxlan_hdr_t +which represents the +.Nm +frame header and has the following members: +.Bd -literal + uint32_t vxlan_flags; /* flags in upper 8 bits */ + uint32_t vxlan_id; /* VXLAN ID in upper 24 bits */ +.Ed +.Sh EXAMPLES +.Sy Example 1 +Decoding a +.Nm +header +.Pp +The following example shows how to validate a +.Nm header. For more information on this process, see RFC 7348. +.Bd -literal -offset indent +#include <sys/types.h> +#include <netinet/in.h> +#include <inttypes.h> +#include <sys/vxlan.h> + +\&... + +/* + * Validate the following bytes as a VXLAN header. If valid, return + * 0 and store the VXLAN identifier in *vidp. Otherwise, return an + * error. + */ +int +validate_vxlan(void *buf, int len, uint32_t *vidp) +{ + vxlan_hdr_t *hdr; + + if (len < sizeof (vxlan_hdr_t)) + return (EINAVL); + + hdr = buf; + if ((ntohl(hdr->vxlan_flags) & VXLAN_MAGIC) == 0) + return (EINAVL); + + *vidp = ntohl(vxlan->vxlan_id) >> VXLAN_ID_SHIFT; + + return (0); +} +.Ed +.Sh STABILITY +The contents of +.In sys/vxlan.h +are +.Sy Uncommitted . +.Sh SEE ALSO +.Xr dladm 1M , +.Xr overlay 5 +.Rs +.%A Mahalingam, M. +.%A Dutt, D. +.%A Duda, K. +.%A Agarwal, P. +.%A Kreeger L. +.%A Sridhar, T. +.%A Bursell, M. +.%A C. Wright +.%T RFC 7348, Virtual eXtensible Local Area Network (VXLAN): A Framework +.%T for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks +.%D August 2014 +.Re diff --git a/usr/src/man/man9e/chpoll.9e b/usr/src/man/man9e/chpoll.9e index 27fe2a20e9..7b4b3edf0b 100644 --- a/usr/src/man/man9e/chpoll.9e +++ b/usr/src/man/man9e/chpoll.9e @@ -121,6 +121,17 @@ The same as \fBPOLLOUT\fR. Priority data (priority band > 0) may be written. .RE +.sp +.ne 2 +.na +\fB\fBPOLLET\fR\fR +.ad +.RS 14n +The desired event is to be edge-triggered; calls to \fBpollwakeup\fR(9F) +should not be suppressed, even if the event is pending at the time of +call to the \fBchpoll()\fR function. +.RE + .RE .sp @@ -197,7 +208,43 @@ be called with multiple events at one time. The \fBpollwakup()\fR can be called regardless of whether or not the \fBchpoll()\fR entry is called; it should be called every time the driver detects the pollable event. The driver must not hold any mutex across the call to \fBpollwakeup\fR(9F) that is acquired in its -\fBchpoll()\fR entry point, or a deadlock may result. +\fBchpoll()\fR entry point, or a deadlock may result. Note that if +\fBPOLLET\fR is set in the specified events, the driver must call +\fBpollwakeup\fR(9F) on subsequent events, even if events are pending at +the time of the call to \fBchpoll()\fR. + +.RE +.RS +4 +.TP +4. +In the \fBclose\fR(9E) entry point, the driver should call \fBpollwakeup()\fR +on the \fBpollhead\fR structure that corresponds to the closing software +state, specifying \fBPOLLERR\fR for the events. Further, upon return from +\fBpollwakeup()\fR, the driver's \fBclose\fR(9E) entry point should call +the \fBpollhead_clean\fR(9F) function, specifying the \fBpollhead\fR that +corresponds to the structure that will be deallocated: + +.sp +.in +2 +.nf +static int +mydriver_close(dev_t dev, int flag, int otyp, cred_t *cp) +{ + minor_t minor = getminor(dev); + mydriver_state_t *state; + + state = ddi_get_soft_state(mydriver_softstate, minor); + + pollwakeup(&state->mydriver_pollhd, POLLERR); + pollhead_clean(&state->mydriver_pollhd); + ... +.fi +.in -2 + +This step is necessary to inform other kernel subsystems that the memory +associated with the \fBpollhead\fR is about to be deallocated by the +\fBclose\fR(9E) entry point. + .RE .SH RETURN VALUES .LP diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile index 815e2f8a10..9c45ac55f6 100644 --- a/usr/src/man/man9f/Makefile +++ b/usr/src/man/man9f/Makefile @@ -13,6 +13,7 @@ # Copyright 2011, Richard Lowe # Copyright 2013 Nexenta Systems, Inc. All rights reserved. # Copyright 2014 Garrett D'Amore <garrett@damore> +# Copyright (c) 2015 Joyent, Inc. All rights reserved. # include $(SRC)/Makefile.master @@ -393,6 +394,7 @@ MANFILES= ASSERT.9f \ pm_power_has_changed.9f \ pm_raise_power.9f \ pm_trans_check.9f \ + pollhead_clean.9f \ pollwakeup.9f \ priv_getbyname.9f \ priv_policy.9f \ diff --git a/usr/src/man/man9f/kmem_alloc.9f b/usr/src/man/man9f/kmem_alloc.9f index 9c4f8ccb0c..201544b57c 100644 --- a/usr/src/man/man9f/kmem_alloc.9f +++ b/usr/src/man/man9f/kmem_alloc.9f @@ -129,5 +129,8 @@ uninitialized kernel memory should be handled carefully. For example, never .SH NOTES .sp .LP -\fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR. -\fBkmem_free(NULL, 0)\fR is legal. +\fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR, but +if \fBKM_SLEEP\fR is set, this behavior is considered to be deprecated; +the system may be configured to explicitly panic in this case in lieu +of returning \fINULL\fR. +\fBkmem_free(NULL, 0)\fR is legal, however. diff --git a/usr/src/man/man9f/pollhead_clean.9f b/usr/src/man/man9f/pollhead_clean.9f new file mode 100644 index 0000000000..a163a65a51 --- /dev/null +++ b/usr/src/man/man9f/pollhead_clean.9f @@ -0,0 +1,64 @@ +'\" te +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved. +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.TH POLLHEAD_CLEAN 9F "Jun 12, 1998" +.\" +.\" A little inside joke with the above date: that's the date that the +.\" devpoll work integrated (under bug 1265897). The original work included +.\" pollhead_clean() -- but didn't bother to document it! With the date, +.\" we are therefore giving this man page the date it should have had in an +.\" attempt to right an historical wrong -- albeit nearly two decades after +.\" the fact. +.\" +.SH NAME +pollhead_clean \- inform the kernel that a pollhead is being deallocated +.SH SYNOPSIS +.LP +.nf +#include <sys/poll.h> + + + +\fBvoid\fR \fBpollhead_clean\fR(\fBstruct pollhead *\fR\fIphp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.na +\fB\fIphp\fR\fR +.ad +.RS 9n +Pointer to a \fBpollhead\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpollhead_clean()\fR function informs the kernel that a driver's +\fBpollhead\fR structure is about to be deallocated, usually as part of +the driver's \fBclose\fR(9E) entry point before the software state that +contains the \fBpollhead\fR is deallocated via \fBddi_soft_state_free\fR(9F). +See \fBchpoll\fR(9E), \fBpollwakeup\fR(9E) and \fBpoll\fR(2) for more detail. +.SH CONTEXT +.sp +.LP +The \fBpollhead_clean()\fR function is generally called from the context +of a \fBclose\fR(9E) entry point, but may be called from user or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBchpoll\fR(9E), \fBpollwakeup\fR(9E) + |