diff options
Diffstat (limited to 'usr/src/man/man7')
127 files changed, 48469 insertions, 607 deletions
diff --git a/usr/src/man/man7/FSS.7 b/usr/src/man/man7/FSS.7 deleted file mode 100644 index 8583d0831e..0000000000 --- a/usr/src/man/man7/FSS.7 +++ /dev/null @@ -1,231 +0,0 @@ -.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved -.\" Copyright 2019 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] -.\" -.Dd December 17, 2019 -.Dt FSS 7 -.Os -.Sh NAME -.Nm FSS -.Nd Fair share scheduler -.Sh DESCRIPTION -The fair share scheduler (FSS) guarantees application performance by explicitly -allocating shares of CPU resources to projects. -A share indicates a project's -entitlement to available CPU resources. -Because shares are meaningful only in -comparison with other project's shares, the absolute quantity of shares is not -important. -Any number that is in proportion with the desired CPU entitlement -can be used. -.Pp -The goals of the FSS scheduler differ from the traditional time-sharing -scheduling class (TS). -In addition to scheduling individual LWPs, the FSS -scheduler schedules projects against each other, making it impossible for any -project to acquire more CPU cycles simply by running more processes -concurrently. -.Pp -A project's entitlement is individually calculated by FSS independently for -each processor set if the project contains processes bound to them. -If a -project is running on more than one processor set, it can have different -entitlements on every set. -A project's entitlement is defined as a ratio -between the number of shares given to a project and the sum of shares of all -active projects running on the same processor set. -An active project is one -that has at least one running or runnable process. -Entitlements are recomputed -whenever any project becomes active or inactive, or whenever the number of -shares is changed. -.Pp -Processor sets represent virtual machines in the FSS scheduling class and -processes are scheduled independently in each processor set. -That is, processes -compete with each other only if they are running on the same processor set. -When a processor set is destroyed, all processes that were bound to it are -moved to the default processor set, which always exists. -Empty processor sets -(that is, sets without processors in them) have no impact on the FSS scheduler -behavior. -.Pp -If a processor set contains a mix of TS/IA and FSS processes, the fairness of -the FSS scheduling class can be compromised because these classes use the same -range of priorities. -Fairness is most significantly affected if processes -running in the TS scheduling class are CPU-intensive and are bound to -processors within the processor set. -As a result, you should avoid having -processes from TS/IA and FSS classes share the same processor set. -RT and FSS -processes use disjoint priority ranges and therefore can share processor sets. -.Pp -As projects execute, their CPU usage is accumulated over time. -The FSS -scheduler periodically decays CPU usages of every project by multiplying it -with a decay factor, ensuring that more recent CPU usage has greater weight -when taken into account for scheduling. -The FSS scheduler continually adjusts -priorities of all processes to make each project's relative CPU usage converge -with its entitlement. -.Pp -While FSS is designed to fairly allocate cycles over a long-term time period, -it is possible that projects will not receive their allocated shares worth of -CPU cycles due to uneven demand. -This makes one-shot, instantaneous analysis of -FSS performance data unreliable. -.Pp -Note that share is not the same as utilization. -A project may be allocated 50% -of the system, although on the average, it uses just 20%. -Shares serve to cap a -project's CPU usage only when there is competition from other projects running -on the same processor set. -When there is no competition, utilization may be -larger than entitlement based on shares. -Allocating a small share to a busy -project slows it down but does not prevent it from completing its work if the -system is not saturated. -.Pp -The configuration of CPU shares is managed by the name server as a property of -the -.Xr project 4 -database. -In the following example, an entry in the -.Pa /etc/project -file sets the number of shares for project -.Sy x-files -to 10: -.Bd -literal -offset 2n -x-files:100::::project.cpu-shares=(privileged,10,none) -.Ed -.Pp -Projects with undefined number of shares are given one share each. -This means -that such projects are treated with equal importance. -Projects with 0 shares -only run when there are no projects with non-zero shares competing for the same -processor set. -The maximum number of shares that can be assigned to one project -is 65535. -.Pp -You can use the -.Xr prctl 1 -command to determine the current share -assignment for a given project: -.Bd -literal -offset 2n -$ prctl -n project.cpu-shares -i project x-files -.Ed -.Pp -or to change the amount of shares if you have root privileges: -.Bd -literal -offset 2n -# prctl -r -n project.cpu-shares -v 5 -i project x-files -.Ed -.Pp -See the -.Xr prctl 1 -man page for additional information on how to modify and -examine resource controls associated with active processes, tasks, or projects -on the system. -See -.Xr resource_controls 5 -for a description of the resource -controls supported in the current release of the Solaris operating system. -.Pp -By default, project -.Sy system -(project ID 0) includes all system daemons -started by initialization scripts and has an -.Dq unlimited -amount of shares. -That -is, it is always scheduled first no matter how many shares are given to other -projects. -.Pp -The following command sets FSS as the default scheduler for the system: -.Bd -literal -offset 2n -# dispadmin -d FSS -.Ed -.Pp -This change will take effect on the next reboot. -Alternatively, you can move -processes from the time-share scheduling class (as well as the special case of -init) into the FSS class without changing your default scheduling class and -rebooting by becoming -.Sy root , -and then using the -.Xr priocntl 1 -command, as shown in the following example: -.Bd -literal -offset 2n -# priocntl -s -c FSS -i class TS -# priocntl -s -c FSS -i pid 1 -.Ed -.Sh CONFIGURING SCHEDULER WITH DISPADMIN -You can use the -.Xr dispadmin 1M -command to examine and tune the FSS -scheduler's time quantum value. -Time quantum is the amount of time that a -thread is allowed to run before it must relinquish the processor. -The following -example dumps the current time quantum for the fair share scheduler: -.Bd -literal -offset 2n -$ dispadmin -g -c FSS - # - # Fair Share Scheduler Configuration - # - RES=1000 - # - # Time Quantum - # - QUANTUM=110 -.Ed -.Pp -The value of the QUANTUM represents some fraction of a second with the -fractional value determined by the reciprocal value of RES. -With the default -value of RES = 1000, the reciprocal of 1000 is \&.001, or milliseconds. -Thus, by -default, the QUANTUM value represents the time quantum in milliseconds. -.Pp -If you change the RES value using -.Xr dispadmin 1M -with the -.Fl r -option, you also change the QUANTUM value. -For example, instead of quantum of 110 with RES -of 1000, a quantum of 11 with a RES of 100 results. -The fractional unit is different while the amount of time is the same. -.Pp -You can use the -.Fl s -option to change the time quantum value. -Note that such changes are not preserved across reboot. -Please refer to the -.Xr dispadmin 1M -man page for additional information. -.Sh SEE ALSO -.Xr prctl 1 , -.Xr priocntl 1 , -.Xr dispadmin 1M , -.Xr psrset 1M , -.Xr priocntl 2 , -.Xr project 4 , -.Xr resource_controls 5 -.Pp -.%T System Administration Guide: Virtualization Using the Solaris Operating System diff --git a/usr/src/man/man7/Intro.7 b/usr/src/man/man7/Intro.7 index 3e08d1344b..0b3632c773 100644 --- a/usr/src/man/man7/Intro.7 +++ b/usr/src/man/man7/Intro.7 @@ -1,209 +1,87 @@ -.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved. +'\" te .\" Copyright 1989 AT&T -.\" Copyright 2020 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] -.\" -.Dd January 6, 2020 -.Dt INTRO 7 -.Os -.Sh NAME -.Nm Intro , -.Nm intro -.Nd introduction to special files -.Sh DESCRIPTION -This section describes various device and network interfaces available on the -sysstem. -The types of interfaces described include character and block -devices, -.Sy STREAMS -modules, network protocols, file systems, and ioctl requests -for driver subsystems and classes. -.Pp -This section contains the following major collections: -.Bl -tag -width "xxxxx" -.It Pq Sy 7D -The system provides drivers for a variety of hardware devices, such as disk, -magnetic tapes, serial communication lines, mice, and frame buffers, as well -as virtual devices such as pseudo-terminals and windows. -.Pp -This section describes special files that refer to specific hardware -peripherals and device drivers. -.Sy STREAMS -device drivers are also described. -Characteristics of both the hardware device and the corresponding device driver -are discussed where applicable. -.Pp -An application accesses a device through that device's special file. -This -section specifies the device special file to be used to access the device as -well as application programming interface (API) information relevant to the use -of the device driver. -All device special files are located under the -.Pa /devices -directory. -The -.Pa /devices -directory hierarchy attempts to mirror the hierarchy of system -busses, controllers, and devices configured on the system. -Logical device names for special files in -.Pa /devices -are located under the -.Pa /dev -directory. -Although not every special file under -.Pa /devices -will have a corresponding logical entry under -.Pa /dev , -whenever possible, an -application should reference a device using the logical name for the device. -Logical device names are listed in the -.Sy FILES -section of the page for the device in question. -.Pp -This section also describes driver configuration where applicable. -Many device drivers have a driver configuration file of the form -.Em driver_name Ns \&.conf -associated with them (see -.Xr driver.conf 4 ) . -The configuration information stored in the driver -configuration file is used to configure the driver and the device. -Driver configuration files are located in -.Pa /kernel/drv -and -.Pa /usr/kernel/drv . -Driver configuration files for platform dependent -drivers are located in -.Pa /platform/`uname\ -i`/kernel/drv -where -.Pa `uname\ -i` -is the output of the -.Xr uname 1 -command with the -.Fl i -option. -.Pp -Some driver configuration files may contain user configurable properties. -Changes in a driver's configuration file will not take effect until the system -is rebooted or the driver has been removed and re-added (see -.Xr rem_drv 1M -and -.Xr add_drv 1M ) . -.It Pq Sy 7FS -This section describes the programmatic interface for several file systems -supported by SunOS. -.It Pq Sy 7I -This section describes ioctl requests which apply to a class of drivers or -subsystems. -For example, ioctl requests which apply to most tape devices are -discussed in -.Xr mtio 7I . -Ioctl requests relevant to only a specific -device are described on the man page for that device. -The page for the device -in question should still be examined for exceptions to the ioctls listed in -section 7I. -.It Pq Sy 7M -This section describes -.Sy STREAMS -modules. -Note that -.Sy STREAMS -drivers are discussed in section 7D. -.Xr streamio 7I -contains a list of ioctl requests used to manipulate -.Sy STREAMS -modules and interface with the -.Sy STREAMS -framework. -.Xr ioctl 2 -requests specific to a -.Sy STREAMS -module will be discussed on the man page for that module. -.It Pq Sy 7P -This section describes various network protocols available in SunOS. -SunOS supports both socket-based and -.Sy STREAMS Ns -based -network communications. -.Pp -The Internet protocol family, described in -.Xr inet 7P , -is the primary protocol family supported by SunOS, although the system can -support a number of others. -The raw interface provides low-level services, such as -packet fragmentation and reassembly, routing, addressing, and basic transport -for socket-based implementations. -Facilities for communicating using an -Internet-family protocol are generally accessed by specifying the -.Dv AF_INET -address family when binding a socket; see -.Xr socket 3SOCKET -for details. -.Pp -Major protocols in the Internet family include: -.Bl -bullet -offset indent -.It -The Internet Protocol (IP) itself, which supports the universal datagram -format, as described in -.Xr ip 7P . -This is the default protocol for -.Dv SOCK_RAW -type sockets within the -.Dv AF_INET -domain. -.It -The Transmission Control Protocol (TCP); see -.Xr tcp 7P . -This is the default protocol for -.Dv SOCK_STREAM -type sockets. -.It -The User Datagram Protocol (UDP); see -.Xr udp 7P . -This is the default -protocol for -.Dv SOCK_DGRAM -type sockets. -.It -The Address Resolution Protocol (ARP); see -.Xr arp 7P . -.It -The Internet Control Message Protocol (ICMP); see -.Xr icmp 7P . -.El -.El -.Sh SEE ALSO -.Xr add_drv 1M , -.Xr rem_drv 1M , -.Xr ioctl 2 , -.Xr Intro 3 , -.Xr socket 3SOCKET , -.Xr driver.conf 4 , -.Xr st 7D , -.Xr mtio 7I , -.Xr streamio 7I , -.Xr arp 7P , -.Xr icmp 7P , -.Xr inet 7P , -.Xr ip 7P , -.Xr tcp 7P , -.Xr udp 7P -.Pp -.%T System Administration Guide: IP Services -.Pp -.%T STREAMS Programming Guide -.Pp -.%T Writing Device Drivers +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH INTRO 7 "Nov 17, 2008" +.SH NAME +Intro, intro \- introduction to miscellany +.SH DESCRIPTION +.sp +.LP +Among the topics presented in this section are: +.sp +.ne 2 +.na +\fBStandards\fR +.ad +.RS 16n +The POSIX (IEEE) Standards and the X/Open Specifications are described on the +\fBstandards\fR page. +.RE + +.sp +.ne 2 +.na +\fBEnvironments\fR +.ad +.RS 16n +The user environment (\fBenviron\fR), the subset of the user environment that +depends on language and cultural conventions (\fBlocale\fR), the large file +compilation environment (\fBlfcompile\fR), and the transitional compilation +environment (\fBlfcompile64\fR) are described. +.RE + +.sp +.ne 2 +.na +\fBMacros\fR +.ad +.RS 16n +The macros to format Reference Manual pages (\fBman\fR and \fBmansun\fR) as +well as other text format macros (\fBme\fR, \fBmm\fR, and \fBms\fR) are +described. +.RE + +.sp +.ne 2 +.na +\fBCharacters\fR +.ad +.RS 16n +Tables of character sets (\fBascii\fR, \fBcharmap\fR, \fBeqnchar\fR, and +\fBiconv\fR), file format notation (\fBformats\fR), file name pattern matching +(\fBfnmatch\fR), and regular expressions (\fBregex\fR and \fBregexp\fR) are +presented. +.RE + +.SH ACKNOWLEDGMENTS +.sp +.LP +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/\&. +.sp +.LP +The Institute of Electrical and Electronics Engineers and The Open Group, have +given us permission to reprint portions of their documentation. +.sp +.LP +In the following statement, the phrase ``this text'' refers to portions of the +system documentation. +.sp +.LP +Portions of this text are reprinted and reproduced in electronic form in the +SunOS 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 and Electronics Engineers, Inc and The Open Group. In the event of +any discrepancy between these versions and the original IEEE and The Open Group +Standard, the original IEEE and The Open Group Standard is the referee +document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html\&. +.sp +.LP +This notice shall appear on any product containing this material. diff --git a/usr/src/man/man7/Makefile b/usr/src/man/man7/Makefile index 929693a927..2527fc1008 100644 --- a/usr/src/man/man7/Makefile +++ b/usr/src/man/man7/Makefile @@ -11,23 +11,223 @@ # # Copyright 2011, Richard Lowe -# Copyright 2013 Nexenta Systems, Inc. All rights reserved. +# 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. +# Copyright 2018 Gary Mills +# Copyright 2019 OmniOS Community Edition (OmniOSce) Association. +# Copyright 2019 Peter Tribble # include $(SRC)/Makefile.master -MANSECT= 7 +MANSECT= 7 +_MANFILES= Intro.7 \ + acl.7 \ + ad.7 \ + ascii.7 \ + attributes.7 \ + audit_binfile.7 \ + audit_remote.7 \ + audit_syslog.7 \ + brands.7 \ + byteorder.7 \ + cancellation.7 \ + charmap.7 \ + condition.7 \ + crypt_bsdbf.7 \ + crypt_bsdmd5.7 \ + crypt_sha256.7 \ + crypt_sha512.7 \ + crypt_sunmd5.7 \ + crypt_unix.7 \ + device_clean.7 \ + dhcp.7 \ + environ.7 \ + epoll.7 \ + eqn.7 \ + eqnchar.7 \ + eventfd.7 \ + extendedFILE.7 \ + filesystem.7 \ + fnmatch.7 \ + formats.7 \ + fsattr.7 \ + grub.7 \ + gss_auth_rules.7 \ + hal.7 \ + iconv.7 \ + iconv_unicode.7 \ + ieee802.3.7 \ + ieee802.11.7 \ + ipfilter.7 \ + isalist.7 \ + kerberos.7 \ + krb5_auth_rules.7 \ + krb5envvar.7 \ + largefile.7 \ + lf64.7 \ + lfcompile.7 \ + lfcompile64.7 \ + locale.7 \ + man.7 \ + mandoc_char.7 \ + mandoc_roff.7 \ + mansun.7 \ + mdoc.7 \ + me.7 \ + mech_spnego.7 \ + mm.7 \ + ms.7 \ + mutex.7 \ + nfssec.7 \ + overlay.7 \ + pam_allow.7 \ + pam_authtok_check.7 \ + pam_authtok_get.7 \ + pam_authtok_store.7 \ + pam_deny.7 \ + pam_dhkeys.7 \ + pam_dial_auth.7 \ + pam_krb5.7 \ + pam_krb5_migrate.7 \ + pam_ldap.7 \ + pam_list.7 \ + pam_passwd_auth.7 \ + pam_rhosts_auth.7 \ + pam_roles.7 \ + pam_sample.7 \ + pam_smb_passwd.7 \ + pam_smbfs_login.7 \ + pam_timestamp.7 \ + pam_tsol_account.7 \ + pam_unix_account.7 \ + pam_unix_auth.7 \ + pam_unix_cred.7 \ + pam_unix_session.7 \ + pkcs11_kernel.7 \ + pkcs11_softtoken.7 \ + pkcs11_tpm.7 \ + privileges.7 \ + prof.7 \ + rbac.7 \ + regex.7 \ + regexp.7 \ + resource_controls.7 \ + security-flags.7 \ + smf.7 \ + smf_bootstrap.7 \ + smf_method.7 \ + smf_restarter.7 \ + smf_security.7 \ + smf_template.7 \ + standards.7 \ + sticky.7 \ + tbl.7 \ + tecla.7 \ + term.7 \ + threads.7 \ + timerfd.7 \ + trusted_extensions.7 \ + vgrindefs.7 \ + zones.7 \ + zpool-features.7 -MANFILES= FSS.7 \ - Intro.7 \ - cpr.7 \ - ibmf.7 +sparc_MANFILES= -MANLINKS= intro.7 +i386_MANFILES= beastie.4th.7 \ + brand.4th.7 \ + check-password.4th.7 \ + color.4th.7 \ + delay.4th.7 \ + gptzfsboot.7 \ + isoboot.7 \ + loader.7 \ + loader.4th.7 \ + menu.4th.7 \ + menusets.4th.7 \ + pxeboot.7 \ + version.4th.7 + +MANLINKS= ANSI.7 \ + C++.7 \ + C.7 \ + CSI.7 \ + ISO.7 \ + MT-Level.7 \ + POSIX.1.7 \ + POSIX.2.7 \ + POSIX.7 \ + RBAC.7 \ + SUS.7 \ + SUSv2.7 \ + SUSv3.7 \ + SVID.7 \ + SVID3.7 \ + XNS.7 \ + XNS4.7 \ + XNS5.7 \ + XPG.7 \ + XPG3.7 \ + XPG4.7 \ + XPG4v2.7 \ + advance.7 \ + architecture.7 \ + availability.7 \ + compile.7 \ + endian.7 \ + intro.7 \ + pthreads.7 \ + stability.7 \ + standard.7 \ + step.7 \ + teclarc.7 + +MANFILES= $(_MANFILES) $($(MACH)_MANFILES) intro.7 := LINKSRC = Intro.7 +CSI.7 := LINKSRC = attributes.7 +MT-Level.7 := LINKSRC = attributes.7 +architecture.7 := LINKSRC = attributes.7 +availability.7 := LINKSRC = attributes.7 +stability.7 := LINKSRC = attributes.7 +standard.7 := LINKSRC = attributes.7 + +endian.7 := LINKSRC = byteorder.7 + +RBAC.7 := LINKSRC = rbac.7 + +advance.7 := LINKSRC = regexp.7 +compile.7 := LINKSRC = regexp.7 +step.7 := LINKSRC = regexp.7 + +ANSI.7 := LINKSRC = standards.7 +C++.7 := LINKSRC = standards.7 +C.7 := LINKSRC = standards.7 +ISO.7 := LINKSRC = standards.7 +POSIX.1.7 := LINKSRC = standards.7 +POSIX.2.7 := LINKSRC = standards.7 +POSIX.7 := LINKSRC = standards.7 +SUS.7 := LINKSRC = standards.7 +SUSv2.7 := LINKSRC = standards.7 +SUSv3.7 := LINKSRC = standards.7 +SVID.7 := LINKSRC = standards.7 +SVID3.7 := LINKSRC = standards.7 +XNS.7 := LINKSRC = standards.7 +XNS4.7 := LINKSRC = standards.7 +XNS5.7 := LINKSRC = standards.7 +XPG.7 := LINKSRC = standards.7 +XPG3.7 := LINKSRC = standards.7 +XPG4.7 := LINKSRC = standards.7 +XPG4v2.7 := LINKSRC = standards.7 + +teclarc.7 := LINKSRC = tecla.7 + +pthreads.7 := LINKSRC = threads.7 + .KEEP_STATE: include $(SRC)/man/Makefile.man diff --git a/usr/src/man/man7/acl.7 b/usr/src/man/man7/acl.7 new file mode 100644 index 0000000000..3dd58041df --- /dev/null +++ b/usr/src/man/man7/acl.7 @@ -0,0 +1,847 @@ +'\" te +.\" Copyright (c) 2020 Peter Tribble. +.\" Copyright 2014 Nexenta Systems, Inc. All rights reserved. +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ACL 7 "Feb 8, 2020" +.SH NAME +acl \- Access Control Lists +.SH DESCRIPTION +Access control lists (ACLs) are discretionary access control mechanisms that +grant and deny access to files and directories. Two different ACL models are +supported in this release: POSIX-draft ACLs and NFSv4 ACLs. +.sp +.LP +The older, POSIX-draft model is supported by the UFS file system. This model is +based on a withdrawn ACL POSIX specification that was never standardized. It +was subsequently withdrawn by the POSIX committee. +.sp +.LP +The other model is based on the standards of the NFSv4 working group and is an +approved standard from the Internet Engineering Task Force (IETF). The ZFS file +system uses the NFSv4 model, and provides richer semantics and finer grained +permission capabilities than the POSIX-draft model. +.SS "POSIX-draft ACLs" +POSIX-draft ACLs provide an alternative security mechanism to basic UNIX file +permissions. Their purpose is to further restrict access +to files and directories or to extend permissions to a particular user. ACLs +can be used to change the permissions for the standard owner, group and other +class bits of a file's mode. ACLs can give additional users and groups access +to the file. A directory can also have a special kind of ACL called a +\fBdefault\fR ACL, which defines ACL entries to be inherited by descendents of +the directory. POSIX-draft ACLs have an ACL entry called \fBmask\fR. The mask +defines the maximum permissions that can be granted to additional user and +group entries. Whenever a file is created or its mode is changed by +\fBchmod\fR(1) or \fBchmod\fR(2), the mask is recomputed. It is recomputed to +be the group permission defined in the mode passed to \fBchmod\fR(2). +.sp +.LP +The POSIX-draft ACL model uses the standard \fBrwx\fR model of traditional UNIX +permissions. +.sp +.LP +An ACL is represented as follows: +.sp +.in +2 +.nf +\fIacl_entry\fR[,\fIacl_entry\fR]... +.fi +.in -2 +.sp + +.sp +.LP +Each \fIacl_entry\fR contains one ACL entry. An ACL entry is represented by two +or three colon-separated(\fB:\fR) fields. +.sp +.ne 2 +.na +\fB\fIuser\fR:[\fIuid\fR]:\fIperms\fR\fR +.ad +.RS 21n +If \fIuid\fR blank, it represents the file owner. +.RE + +.sp +.ne 2 +.na +\fB\fIgroup\fR:[\fIgid\fR]:\fIperms\fR\fR +.ad +.RS 21n +If \fIgid\fR is blank, it represents the owning group. +.RE + +.sp +.ne 2 +.na +\fB\fIother\fR:\fIperms\fR\fR +.ad +.RS 21n +Represents the file other class. +.RE + +.sp +.ne 2 +.na +\fB\fImask\fR:\fIperms\fR\fR +.ad +.RS 21n +Defines the \fBMAX\fR permission to hand out. +.RE + +.sp +.LP +For example to give user \fBjoe\fR read and write permissions, the ACL entry is +specified as: +.sp +.in +2 +.nf +user:joe:rw- +.fi +.in -2 +.sp + +.SS "NFSv4 ACLs" +The NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4 ACLs +provide a much richer ACL model than POSIX-draft ACLs. +.sp +.LP +The major differences between NFSv4 and POSIX-draft ACLs are as follows: +.RS +4 +.TP +.ie t \(bu +.el o +NFSv4 ACLs provide finer grained permissions than the \fBrwx\fR model. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +NFSv4 ACLs allow for both \fBALLOW\fR and \fBDENY\fR entries. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +NFSv4 ACLs provide a rich set of inheritance semantics. POSIX ACLs also have +inheritance, but with the NFSv4 model you can control the following inheritance +features: +.RS +4 +.TP +.ie t \(bu +.el o +Whether inheritance cascades to both files and directories or only to files or +directories. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +In the case of directories, you can indicate whether inheritance is applied to +the directory itself, to just one level of subdirectories, or cascades to all +subdirectories of the directory. +.RE +.RE +.RS +4 +.TP +.ie t \(bu +.el o +NFSv4 ACLs provide a mechanism for hooking into a system's audit trail. +Currently, illumos does not support this mechanism. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +NFSv4 ACLs enable administrators to specify the order in which ACL entries are +checked. With POSIX-draft ACLs the file system reorders ACL entries into a well +defined, strict access, checking order. +.RE +.sp +.LP +POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However, only some +NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs. +.sp +.LP +Permissions can be specified in three different \fBchmod\fR ACL formats: +verbose, compact, or positional. The verbose format uses words to indicate that +the permissions are separated with a forward slash (\fB/\fR) character. Compact +format uses the permission letters and positional format uses the permission +letters or the hyphen (\fB-\fR) to identify no permissions. +.sp +.LP +The permissions for verbose mode and their abbreviated form in parentheses for +compact and positional mode are described as follows: +.sp +.ne 2 +.na +\fBread_data (\fBr\fR)\fR +.ad +.RS 24n +Permission to read the data of the file +.RE + +.sp +.ne 2 +.na +\fBlist_directory (\fBr\fR)\fR +.ad +.RS 24n +Permission to list the contents of a directory. +.RE + +.sp +.ne 2 +.na +\fBwrite_data (\fBw\fR)\fR +.ad +.RS 24n +Permission to modify a file's data anywhere in the file's offset range. This +includes the ability to grow the file or write to any arbitrary offset. +.RE + +.sp +.ne 2 +.na +\fBadd_file (\fBw\fR)\fR +.ad +.RS 24n +Permission to add a new file to a directory. +.RE + +.sp +.ne 2 +.na +\fBappend_data (\fBp\fR)\fR +.ad +.RS 24n +The ability to modify the file's data, but only starting at EOF. Currently, +this permission is not supported. +.RE + +.sp +.ne 2 +.na +\fBadd_subdirectory (\fBp\fR)\fR +.ad +.RS 24n +Permission to create a subdirectory to a directory. +.RE + +.sp +.ne 2 +.na +\fBread_xattr (\fBR\fR)\fR +.ad +.RS 24n +The ability to read the extended attributes of a file or do a lookup in the +extended attributes directory. +.RE + +.sp +.ne 2 +.na +\fBwrite_xattr (\fBW\fR)\fR +.ad +.RS 24n +The ability to create extended attributes or write to the extended attributes +directory. +.RE + +.sp +.ne 2 +.na +\fBexecute (\fBx\fR)\fR +.ad +.RS 24n +Permission to execute a file. +.RE + +.sp +.ne 2 +.na +\fBread_attributes (\fBa\fR)\fR +.ad +.RS 24n +The ability to read basic attributes (non-ACLs) of a file. Basic attributes are +considered to be the stat level attributes. Allowing this access mask bit means +that the entity can execute \fBls\fR(1) and \fBstat\fR(2). +.RE + +.sp +.ne 2 +.na +\fBwrite_attributes (\fBA\fR)\fR +.ad +.RS 24n +Permission to change the times associated with a file or directory to an +arbitrary value. +.RE + +.sp +.ne 2 +.na +\fBdelete (\fBd\fR)\fR +.ad +.RS 24n +Permission to delete the file. +.RE + +.sp +.ne 2 +.na +\fBdelete_child (\fBD\fR)\fR +.ad +.RS 24n +Permission to delete a file within a directory. +.RE + +.sp +.ne 2 +.na +\fBread_acl (\fBc\fR)\fR +.ad +.RS 24n +Permission to read the ACL. +.RE + +.sp +.ne 2 +.na +\fBwrite_acl (\fBC\fR)\fR +.ad +.RS 24n +Permission to write the ACL or the ability to execute \fBchmod\fR(1) or +\fBsetfacl\fR(1). +.RE + +.sp +.ne 2 +.na +\fBwrite_owner (\fBo\fR)\fR +.ad +.RS 24n +Permission to change the owner or the ability to execute \fBchown\fR(1) or +\fBchgrp\fR(1). +.RE + +.sp +.ne 2 +.na +\fBsynchronize (\fBs\fR)\fR +.ad +.RS 24n +Permission to access a file locally at the server with synchronous reads and +writes. Currently, this permission is not supported. +.RE + +.sp +.LP +The following inheritance flags are supported by NFSv4 ACLs: +.sp +.ne 2 +.na +\fBfile_inherit (\fBf\fR)\fR +.ad +.RS 26n +Inherit to all newly created files in a directory. +.RE + +.sp +.ne 2 +.na +\fBdir_inherit (\fBd\fR)\fR +.ad +.RS 26n +Inherit to all newly created directories in a directory. +.RE + +.sp +.ne 2 +.na +\fBinherit_only (\fBi\fR)\fR +.ad +.RS 26n +Placed on a directory, but does not apply to the directory itself, only to +newly created files and directories. This flag requires file_inherit +and/or dir_inherit to indicate what to inherit. +.RE + +.sp +.ne 2 +.na +\fBno_propagate (\fBn\fR)\fR +.ad +.RS 26n +Placed on directories and indicates that ACL entries should only be inherited +one level of the tree. This flag requires file_inherit and/or dir_inherit to +indicate what to inherit. +.RE + +.sp +.ne 2 +.na +\fBsuccessful_access (\fBS\fR)\fR +.ad +.RS 26n +Indicates whether an alarm or audit record should be initiated upon successful +accesses. Used with audit/alarm ACE types. +.RE + +.sp +.ne 2 +.na +\fBfailed_access (\fBF\fR)\fR +.ad +.RS 26n +Indicates whether an alarm or audit record should be initiated when access +fails. Used with audit/alarm ACE types. +.RE + +.sp +.ne 2 +.na +\fBinherited (\fBI\fR)\fR +.ad +.RS 26n +ACE was inherited. +.RE + +.sp +.ne 2 +.na +\fB\fB-\fR\fR +.ad +.RS 26n +No permission granted. +.RE + +.sp +.LP +An NFSv4 ACL is expressed using the following syntax: +.sp +.in +2 +.nf +\fIacl_entry\fR[,\fIacl_entry\fR]... + + owner@:<perms>[:inheritance flags]:<allow|deny> + group@:<perms>[:inheritance flags]:<allow|deny> + everyone@:<perms>[:inheritance flags]:<allow|deny> + user:<username>:<perms>[:inheritance flags]:<allow|deny> + usersid:<sid string>:<perms>[:inheritance flags]:<allow|deny> + group:<groupname>:<perms>[:inheritance flags]:<allow|deny> + groupsid:<sid string>:<perms>[:inheritance flags]:<allow|deny> + sid:<sid string>:<perms>[:inheritance flags]:<allow|deny> +.fi +.in -2 + +.sp +.ne 2 +.na +\fBowner@\fR +.ad +.RS 10n +File owner +.RE + +.sp +.ne 2 +.na +\fBgroup@\fR +.ad +.RS 10n +Group owner +.RE + +.sp +.ne 2 +.na +\fBuser\fR +.ad +.RS 10n +Permissions for a specific user +.RE + +.sp +.ne 2 +.na +\fBgroup\fR +.ad +.RS 10n +Permissions for a specific group +.RE + +.sp +.LP +Permission and inheritance flags are separated by a \fB/\fR character. +.sp +.LP +ACL specification examples: +.sp +.in +2 +.nf +user:fred:read_data/write_data/read_attributes:file_inherit:allow +owner@:read_data:allow,group@:read_data:allow,user:tom:read_data:deny +.fi +.in -2 +.sp + +.sp +.LP +Using the compact ACL format, permissions are specified by using 14 unique +letters to indicate permissions. +.sp +.LP +Using the positional ACL format, permissions are specified as positional +arguments similar to the \fBls -V\fR format. The hyphen (\fB-\fR), which +indicates that no permission is granted at that position, can be omitted and +only the required letters have to be specified. +.sp +.LP +The letters above are listed in the order they would be specified in positional +notation. +.sp +.LP +With these letters you can specify permissions in the following equivalent +ways. +.sp +.in +2 +.nf +user:fred:rw------R------:file_inherit:allow +.fi +.in -2 +.sp + +.sp +.LP +Or you can remove the \fB-\fR and scrunch it together. +.sp +.in +2 +.nf +user:fred:rwR:file_inherit:allow +.fi +.in -2 +.sp + +.sp +.LP +The inheritance flags can also be specified in a more compact manner, as +follows: +.sp +.in +2 +.nf +user:fred:rwR:f:allow +user:fred:rwR:f------:allow +.fi +.in -2 +.sp + +.SS "Shell-level API" +Several utilities support the manipulation of ACLs. The following +utilities accommodate both ACL models: +.sp +.ne 2 +.na +\fB\fBchmod\fR\fR +.ad +.RS 12n +The \fBchmod\fR utility has been enhanced to allow for the setting and deleting +of ACLs. This is achieved by extending the symbolic-mode argument to support +ACL manipulation. See \fBchmod\fR(1) for details. +.RE + +.sp +.ne 2 +.na +\fB\fBcompress\fR\fR +.ad +.RS 12n +When a file is compressed any ACL associated with the original file is +preserved with the compressed file. +.RE + +.sp +.ne 2 +.na +\fB\fBcp\fR\fR +.ad +.RS 12n +By default, \fBcp\fR ignores ACLs, unless the \fB-p\fR option is specified. +When \fB-p\fR is specified the owner and group id, permission modes, +modification and access times, ACLs, and extended attributes if applicable are +preserved. +.RE + +.sp +.ne 2 +.na +\fB\fBcpio\fR\fR +.ad +.RS 12n +ACLs are preserved when the \fB-P\fR option is specified. +.RE + +.sp +.ne 2 +.na +\fB\fBfind\fR\fR +.ad +.RS 12n +Find locates files with ACLs when the \fB-acl\fR flag is specified. +.RE + +.sp +.ne 2 +.na +\fB\fBls\fR\fR +.ad +.RS 12n +By default \fBls\fR does not display ACL information. When the \fB-v\fR option +is specified, a file's ACL is displayed. +.RE + +.sp +.ne 2 +.na +\fB\fBmv\fR\fR +.ad +.RS 12n +When a file is moved, all attributes are carried along with the renamed file. +When a file is moved across a file system boundary, the ACLs are replicated. If +the ACL information cannot be replicated, the move fails and the source file is +not removed. +.RE + +.sp +.ne 2 +.na +\fB\fBpack\fR\fR +.ad +.RS 12n +When a file is packed, any ACL associated with the original file is preserved +with the packed file. +.RE + +.sp +.ne 2 +.na +\fB\fBrcp\fR\fR +.ad +.RS 12n +\fBrcp\fR has been enhanced to support copying. A file's ACL is only preserved +when the remote host supports ACLs. +.RE + +.sp +.ne 2 +.na +\fB\fBtar\fR\fR +.ad +.RS 12n +ACLs are preserved when the \fB-p\fR option is specified. +.RE + +.sp +.ne 2 +.na +\fB\fBunpack\fR\fR +.ad +.RS 12n +When a file with an ACL is unpacked, the unpacked file retains the ACL +information. +.RE + +.SS "Application-level API" +The primary interfaces required to access file system ACLs at the programmatic +level are the \fBacl_get()\fR and \fBacl_set()\fR functions. These functions +support both POSIX-draft ACLs and NFSv4 ACLs. +.SS "Retrieving a file's ACL" +.in +2 +.nf +int acl_get(const char *path, int flag, acl_t **aclp); +int facl_get(int fd, int flag, acl_t **aclp); +.fi +.in -2 + +.sp +.LP +The \fBacl_get\fR(3SEC) and \fBfacl_get\fR(3SEC) functions retrieve an ACL on +a file whose name is given by path or referenced by the open file descriptor +fd. The flag argument specifies whether a trivial ACL should be retrieved. When +the flag argument equals \fBACL_NO_TRIVIAL\fR only ACLs that are not +trivial are retrieved. The ACL is returned in the \fBaclp\fR argument. +.SS "Freeing ACL structure" +.in +2 +.nf +void acl_free(acl_t *aclp); +.fi +.in -2 + +.sp +.LP +The \fBacl_free()\fR function frees up memory allocated for the argument +\fBaclp\fR. +.SS "Setting an ACL on a file" +.in +2 +.nf +int acl_set(const char *path, acl_t *aclp); +int facl_set(int fd, acl_t *aclp); +.fi +.in -2 + +.sp +.LP +The \fBacl_set\fR(3SEC) and \fBfacl_get\fR(3SEC) functions are used for setting +an ACL on a file whose name is given by path or referenced by the open file +descriptor \fBfd\fR. The \fBaclp\fR argument specifies the ACL to set. The +\fBacl_set\fR(3SEC) function translates a POSIX-draft ACL into a NFSv4 ACL when +the target file system supports NFSv4 ACLs. No translation is performed when +trying to set an NFSv4 ACL on a POSIX-draft ACL supported file system. +.SS "Determining an ACL's trivialness" +.in +2 +.nf +int acl_trivial(const char *path); +.fi +.in -2 + +.sp +.LP +The \fBacl_trivial()\fR function is used to determine whether a file has a +trivial ACL. +.SS "Removing all ACLs from a file" +.in +2 +.nf +int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode); +.fi +.in -2 + +.sp +.LP +The \fBacl_strip()\fR function removes all ACLs from a file and replaces them +with a trivial ACL based off of the passed in argument mode. After replacing +the ACL the owner and group of the file are set to the values specified in the +uid and gid parameters. +.SS "Converting ACLs to/from external representation" +.in +2 +.nf +int acl_fromtext(const char *path, acl_t **aclp); +char *acl_totext(acl_t *aclp, int flags); +.fi +.in -2 + +.sp +.LP +The \fBacl_totext()\fR function converts an internal ACL representation pointed +to by aclp into an external representation. See \fBDESCRIPTION\fR for details +about external representation. +.sp +.LP +The \fBacl_fromtext()\fR function converts an external representation into an +internal representation. See \fBDESCRIPTION\fR for details about external +representation. +.SH EXAMPLES +The following examples demonstrate how the API can be used to perform basic +operations on ACLs. +.LP +\fBExample 1 \fRRetrieving and Setting an ACL +.sp +.LP +Use the following to retrieve an ACL and set it on another file: + +.sp +.in +2 +.nf +error = acl_get("file", ACL_NO_TRIVIAL, &aclp); + +if (error == 0 && aclp != NULL) { +.in +8 +error = acl_set("file2", aclp); +acl_free(aclp); +.in -8 +} +\&... +.fi +.in -2 + +.LP +\fBExample 2 \fRRetrieving and Setting Any ACLs +.sp +.LP +Use the following to retrieve any ACL, including trivial ACLs, and set it on +another file: + +.sp +.in +2 +.nf +error = acl_get("file3", 0, &aclp); +if (error == 0) { +.in +8 +error = acl_set("file4", aclp); +acl_free(aclp); +.in -8 +} +\&... +.fi +.in -2 + +.LP +\fBExample 3 \fRDetermining if a File has a Trivial ACL +.sp +.LP +Use the following to determine if a file has a trivial ACL: + +.sp +.in +2 +.nf +char *file = "file5"; +istrivial = acl_trivial(file); + +if (istrivial == 0) +.in +8 +printf("file %s has a trivial ACL\en", file); +.in -8 +else +.in +8 +printf("file %s has a NON-trivial ACL\en", file); +.in -8 +\&... +.fi +.in -2 + +.LP +\fBExample 4 \fRRemoving all ACLs from a File +.sp +.LP +Use the following to remove all ACLs from a file, and set a new mode, owner, +and group: + +.sp +.in +2 +.nf +error = acl_strip("file", 10, 100, 0644); +\&... +.fi +.in -2 + +.SH SEE ALSO +.BR chgrp (1), +.BR chmod (1), +.BR chown (1), +.BR cp (1), +.BR cpio (1), +.BR find (1), +.BR ls (1), +.BR mv (1), +.BR setfacl (1), +.BR tar (1), +.BR acl (2), +.BR chmod (2), +.BR stat (2), +.BR acl_free (3SEC), +.BR acl_fromtext (3SEC), +.BR acl_get (3SEC), +.BR acl_strip (3SEC), +.BR acl_trivial (3SEC), +.BR aclsort (3SEC) diff --git a/usr/src/man/man7/ad.7 b/usr/src/man/man7/ad.7 new file mode 100644 index 0000000000..4b082881cd --- /dev/null +++ b/usr/src/man/man7/ad.7 @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH AD 7 "May 23, 2021" +.SH NAME +ad \- Active Directory as a naming repository +.SH DESCRIPTION +Solaris clients can obtain naming information from Active Directory (AD) +servers. +.sp +.LP +The Solaris system must first join an AD domain and then add the \fBad\fR +keyword to the appropriate entries in the \fBnsswitch.conf\fR(5) file. The +Solaris system joins the AD domain by using the \fBkclient\fR(8) utility. The +AD name service only supports the naming databases for \fBpasswd\fR and +\fBgroup\fR. +.sp +.LP +Windows users are not able to log in. The \fBuser_attr\fR(5) database has no +entries for Windows users, and the \fBpasswd\fR(1) command does not support the +synchronization of user passwords with AD. +.sp +.LP +The Solaris AD client uses auto-discovery techniques to find AD directory +servers, such as domain controllers and global catalog servers. The client also +uses the LDAP v3 protocol to access naming information from AD servers. The AD +server schema requires no modification because the AD client works with native +AD schema. The Solaris AD client uses the \fBidmap\fR(8) service to map +between Windows security identifiers (SIDs) and Solaris user identifiers (UIDs) +and group identifiers (GIDs). User names and group names are taken from the +\fBsAMAccountName\fR attribute of the AD user and group objects and then tagged +with the domain where the objects reside. The domain name is separated from the +user name or group name by the \fB@\fR character. +.sp +.LP +The client uses the SASL/GSSAPI/KRB5 security model. The \fBkclient\fR utility +is used to join the client to AD. During the join operation, \fBkclient\fR +configures Kerberos v5 on the client. See \fBkclient\fR(8). +.SH FILES +.ne 2 +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 24n +Configuration file for the name-service switch. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/nsswitch.ad\fR\fR +.ad +.RS 24n +Sample configuration file for the name-service switch configured with ad, dns +and files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/nss_ad.so.1\fR\fR +.ad +.RS 24n +Name service switch module for AD. +.RE + +.SH SEE ALSO +.BR passwd (1), +.BR svcs (1), +.BR nsswitch.conf (5), +.BR user_attr (5), +.BR smf (7), +.BR idmap (8), +.BR idmapd (8), +.BR kclient (8), +.BR svcadm (8), +.BR svccfg (8) diff --git a/usr/src/man/man7/ascii.7 b/usr/src/man/man7/ascii.7 new file mode 100644 index 0000000000..97ae2a69dd --- /dev/null +++ b/usr/src/man/man7/ascii.7 @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" 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 ASCII 7 "Apr 19, 2002" +.SH NAME +ascii \- map of ASCII character set +.SH SYNOPSIS +.LP +.nf +\fBcat\fR \fB/usr/pub/ascii\fR +.fi + +.SH DESCRIPTION +.sp +.LP +\fB/usr/pub/ascii\fR is a map of the \fBASCII\fR character set, to be printed +as needed. It contains octal and hexadecimal values for each character. While +not included in that file, a chart of decimal values is also shown here. +.sp +.in +2 +.nf + Octal \(mi Character + +000 NUL 001 SOH 002 STX 003 ETX 004 EOT 005 ENQ 006 ACK 007 BEL +010 BS 011 HT 012 NL 013 VT 014 NP 015 CR 016 SO 017 SI +020 DLE 021 DC1 022 DC2 023 DC3 024 DC4 025 NAK 026 SYN 027 ETB +030 CAN 031 EM 032 SUB 033 ESC 034 FS 035 GS 036 RS 037 US +040 SP 041 ! 042 " 043 # 044 $ 045 % 046 & 047 \&' +050 ( 051 ) 052 * 053 + 054 , 055 \(mi 056 . 057 / +060 0 061 1 062 2 063 3 064 4 065 5 066 6 067 7 +070 8 071 9 072 : 073 ; 074 < 075 = 076 > 077 ? +100 @ 101 A 102 B 103 C 104 D 105 E 106 F 107 G +110 H 111 I 112 J 113 K 114 L 115 M 116 N 117 O +120 P 121 Q 122 R 123 S 124 T 125 U 126 V 127 W +130 X 131 Y 132 Z 133 [ 134 \e 135 ] 136 ^ 137 _ +140 ` 141 a 142 b 143 c 144 d 145 e 146 f 147 g +150 h 151 i 152 j 153 k 154 l 155 m 156 n 157 o +160 p 161 q 162 r 163 s 164 t 165 u 166 v 167 w +170 x 171 y 172 z 173 { 174 | 175 } 176 ~ 177 DEL +.fi +.in -2 +.sp + +.sp +.in +2 +.nf + Hexadecimal \(mi Character + +00 NUL 01 SOH 02 STX 03 ETX 04 EOT 05 ENQ 06 ACK 07 BEL +08 BS 09 HT 0A NL 0B VT 0C NP 0D CR 0E SO 0F SI +10 DLE 11 DC1 12 DC2 13 DC3 14 DC4 15 NAK 16 SYN 17 ETB +18 CAN 19 EM 1A SUB 1B ESC 1C FS 1D GS 1E RS 1F US +20 SP 21 ! 22 " 23 # 24 $ 25 % 26 & 27 \&' +28 ( 29 ) 2A * 2B + 2C , 2D \(mi 2E . 2F / +30 0 31 1 32 2 33 3 34 4 35 5 36 6 37 7 +38 8 39 9 3A : 3B ; 3C < 3D = 3E > 3F ? +40 @ 41 A 42 B 43 C 44 D 45 E 46 F 47 G +48 H 49 I 4A J 4B K 4C L 4D M 4E N 4F O +50 P 51 Q 52 R 53 S 54 T 55 U 56 V 57 W +58 X 59 Y 5A Z 5B [ 5C \e 5D ] 5E ^ 5F _ +60 ` 61 a 62 b 63 c 64 d 65 e 66 f 67 g +68 h 69 i 6A j 6B k 6C l 6D m 6E n 6F o +70 p 71 q 72 r 73 s 74 t 75 u 76 v 77 w +78 x 79 y 7A z 7B { 7C | 7D } 7E ~ 7F DEL +.fi +.in -2 +.sp + +.sp +.in +2 +.nf + Decimal \(mi Character + + 0 NUL 1 SOH 2 STX 3 ETX 4 EOT 5 ENQ 6 ACK 7 BEL + 8 BS 9 HT 10 NL 11 VT 12 NP 13 CR 14 SO 15 SI + 16 DLE 17 DC1 18 DC2 19 DC3 20 DC4 21 NAK 22 SYN 23 ETB + 24 CAN 25 EM 26 SUB 27 ESC 28 FS 29 GS 30 RS 31 US + 32 SP 33 ! 34 " 35 # 36 $ 37 % 38 & 39 \&' + 40 ( 41 ) 42 * 43 + 44 , 45 \(mi 46 . 47 / + 48 0 49 1 50 2 51 3 52 4 53 5 54 6 55 7 + 56 8 57 9 58 : 59 ; 60 < 61 = 62 > 63 ? + 64 @ 65 A 66 B 67 C 68 D 69 E 70 F 71 G + 72 H 73 I 74 J 75 K 76 L 77 M 78 N 79 O + 80 P 81 Q 82 R 83 S 84 T 85 U 86 V 87 W + 88 X 89 Y 90 Z 91 [ 92 \e 93 ] 94 ^ 95 _ + 96 ` 97 a 98 b 99 c 100 d 101 e 102 f 103 g +104 h 105 i 106 j 107 k 108 l 109 m 110 n 111 o +112 p 113 q 114 r 115 s 116 t 117 u 118 v 119 w +120 x 121 y 122 z 123 { 124 | 125 } 126 ~ 127 DEL +.fi +.in -2 +.sp + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/pub/ascii\fR \fR +.ad +.RS 19n +On-line chart of octal and hexadecimal values for the \fBASCII\fR character +set. +.RE + diff --git a/usr/src/man/man7/attributes.7 b/usr/src/man/man7/attributes.7 new file mode 100644 index 0000000000..9f7b086566 --- /dev/null +++ b/usr/src/man/man7/attributes.7 @@ -0,0 +1,722 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ATTRIBUTES 7 "May 13, 2017" +.SH NAME +attributes, architecture, availability, CSI, stability, MT-Level, standard \- +attributes of interfaces +.SH DESCRIPTION +.LP +The \fBATTRIBUTES\fR section of a manual page contains a table defining +attribute types and their corresponding values. The following is an example of +an attributes table. Not all attribute types are appropriate for all types of +interfaces. +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Architecture SPARC +_ +CSI Enabled +_ +Interface Stability Committed +_ +MT-Level Safe +_ +Standard See \fBstandards\fR(7). +.TE + +.SS "Architecture" +.LP +Architecture defines processor or specific hardware. See \fB-p\fR option of +\fBuname\fR(1). In some cases, it may indicate required adapters or +peripherals. +.SS "Code Set Independence (CSI)" +.LP +\fBOS\fR utilities and libraries free of dependencies on the properties of any +code sets are said to have Code Set Independence (CSI). They have the attribute +of being \fBCSI\fR enabled. This is in contrast to many commands and utilities, +for example, that work only with Extended Unix Codesets (EUC), an encoding +method that allows concurrent support for up to four code sets and is commonly +used to represent Asian character sets. +.sp +.LP +For practical reasons, however, this independence is not absolute. Certain +assumptions are still applied to the current \fBCSI\fR implementation: +.RS +4 +.TP +.ie t \(bu +.el o +File code is a superset of \fBASCII\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +To support multi-byte characters and null-terminated \fBUNIX\fR file names, +the \fINULL\fR and \fB/\fR (slash) characters cannot be part of any multi-byte +characters. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Only "stateless" file code encodings are supported. Stateless encoding avoids +shift, locking shift, designation, invocation, and so forth, although single +shift is not excluded. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Process code (\fBwchar_t\fR values) is implementation dependent and can change +over time or between implementations or between locales. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Not every object can have names composed of arbitrary characters. The names of +the following objects must be composed of \fBASCII\fR characters: +.RS +4 +.TP +.ie t \(bu +.el o +User names, group name, and passwords +.RE +.RS +4 +.TP +.ie t \(bu +.el o +System name +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Names of printers and special devices +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Names of terminals (/\fBdev/tty*\fR) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Process \fBID\fR numbers +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Message queues, semaphores, and shared memory labels. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The following may be composed of \fBISO\fR Latin-1 or \fBEUC\fR characters: +.RS +4 +.TP +.ie t \(bu +.el o +File names +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Directory names +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Command names +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Shell variables and environmental variable names +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Mount points for file systems +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBNIS\fR key names and domain names +.RE +.RE +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The names of \fBNFS\fR shared files should be composed of \fBASCII\fR +characters. Although files and directories may have names and contents composed +of characters from non-\fBASCII\fR code sets, using only the \fBASCII\fR +codeset allows \fBNFS\fR mounting across any machine, regardless of +localization. For the commands and utilities that are \fBCSI\fR enabled, all +can handle single-byte and multi-byte locales released in 2.6. For applications +to get full support of internationalization services, dynamic binding has to be +applied. Statically bound programs will only get support for C and POSIX +locales. +.RE +.SS "Interface Stability" +.LP +Sun often provides developers with early access to new technologies, which +allows developers to evaluate with them as soon as possible. Unfortunately, new +technologies are prone to changes and standardization often results in +interface incompatibility from previous versions. +.sp +.LP +To make reasonable risk assessments, developers need to know how likely an +interface is to change in future releases. To aid developers in making these +assessments, interface stability information is included on some manual pages +for commands, entry-points, and file formats. +.sp +.LP +The more stable interfaces can safely be used by nearly all applications, +because Sun will endeavor to ensure that these continue to work in future minor +releases. Applications that depend only on Committed interfaces should reliably +continue to function correctly on future minor releases (but not necessarily on +earlier major releases). +.sp +.LP +The less stable interfaces allow experimentation and prototyping, but should be +used only with the understanding that they might change incompatibly or even be +dropped or replaced with alternatives in future minor releases. +.sp +.LP +"Interfaces" that Sun does not document (for example, most kernel data +structures and some symbols in system header files) may be implementation +artifacts. Such internal interfaces are not only subject to incompatible change +or removal, but we are unlikely to mention such a change in release notes. +.SS "Release Levels" +.LP +Products are given release levels, as well as names, to aid compatibility +discussions. Each release level may also include changes suitable for lower +levels. +.sp + +.sp +.TS +c c c +l l l . +Release Version Significance +_ +Major x.0 T{ +Likely to contain major feature additions; adhere to different, possibly incompatible standard revisions; and though unlikely, could change, drop, or replace Committed interfaces. Initial product releases are usually 1.0. +T} +_ +Minor x.y T{ +Compared to an x.0 or earlier release (y!=0), it is likely to contain: feature additions, compatible changes to Committed interfaces, or likely incompatible changes to Uncommitted or Volatile interfaces. +T} +_ +Micro x.y.z T{ +Intended to be interface compatible with the previous release (z!=0), but likely to add bug fixes, performance enhancements, and support for additional hardware. Incompatible changes to Volatile interfaces are possible. +T} +.TE + +.sp +.LP +In the context of interface stability, update releases (occasionally referred +to as patch releases) should be considered equivalent to Micro Releases. +.SS "Classifications" +.LP +The following table summarizes how stability level classifications relate to +release level. The first column lists the Stability Level. The second column +lists the Release Level for Incompatible Changes, and the third column lists +other comments. For a complete discussion of individual classifications, see +the appropriate subsection below. +.sp + +.sp +.TS +c c c +l l l . +Stability Release Comments +_ +Committed Major (x.0) Incompatibilities are exceptional. +_ +Uncommitted Minor (x.y) Incompatibilities are common. +_ +Volatile Micro (x.y.z) Incompatibilities are common. +.TE + +.sp +.LP +The interface stability level classifications described on this manual page +apply to both source and binary interfaces unless otherwise stated. All +stability level classifications are public, with the exception of the +\fBPrivate\fR classification. The precise stability level of a public interface +(one that is documented in the manual pages) is unspecified unless explicitly +stated. The stability level of an undocumented interface is implicitly +\fBPrivate\fR. +.sp +.LP +The existence of documentation other than the documentation that is a component +of the Solaris product should not be construed to imply any level of stability +for interfaces provided by the Solaris product. The only source of stability +level information is Solaris manual pages. +.sp +.ne 2 +.na +\fB\fBCommitted\fR\fR +.ad +.sp .6 +.RS 4n +The intention of a Committed interface is to enable third parties to develop +applications to these interfaces, release them, and have confidence that they +will run on all releases of the product after the one in which the interface +was introduced, and within the same Major release. Even at a Major release, +incompatible changes are expected to be rare, and to have strong +justifications. +.sp +Interfaces defined and controlled as industry standards are most often treated +as Committed interfaces. In this case, the controlling body and/or public, +versioned document is typically noted in a "Standard" entry in the Attributes +table or elsewhere in the documentation. +.sp +Although a truly exceptional event, incompatible changes are possible in any +release if the associated defect is serious enough as outlined in the +Exceptions section of this document or in a Minor release by following the End +of Feature process. If support of a Committed interface must be discontinued, +Sun will attempt to provide notification and the stability level will be marked +Obsolete. +.RE + +.sp +.ne 2 +.na +\fB\fBUncommitted\fR\fR +.ad +.sp .6 +.RS 4n +No commitment is made about either source or binary compatibility of these +interfaces from one Minor release to the next. Even the drastic incompatible +change of removal of the interface in a Minor release is possible. Uncommitted +interfaces are generally not appropriate for use by release-independent +products. +.sp +Incompatible changes to the interface are intended to be motivated by true +improvement to the interface which may include ease of use considerations. The +general expectation should be that Uncommitted interfaces are not likely to +change incompatibly and if such changes occur they will be small in impact and +may often have a mitigation plan. +.sp +Uncommitted interfaces generally fall into one of the following subcategories: +.RS +4 +.TP +1. +Interfaces that are experimental or transitional. They are typically used to +give outside developers early access to new or rapidly changing technology, or +to provide an interim solution to a problem where a more general solution is +anticipated. +.RE +.RS +4 +.TP +2. +Interfaces whose specification is controlled by an outside body yet Sun +expects to make a reasonable effort to maintain compatibility with previous +releases until the next Minor release at which time Sun expects to synchronize +with the external specification. +.RE +.RS +4 +.TP +3. +Interfaces whose target audience values innovation (and possibly ease of +use) over stability. This attribute is often associated with administrative +interfaces for higher tier components. +.RE +For Uncommitted interfaces, Sun makes no claims about either source or binary +compatibility from one minor release to another. Applications developed based +on these interfaces may not work in future minor releases. +.RE + +.sp +.ne 2 +.na +\fB\fBVolatile\fR\fR +.ad +.sp .6 +.RS 4n +Volatile interfaces can change at any time and for any reason. +.sp +The Volatile interface stability level allows Sun products to quickly track a +fluid, rapidly evolving specification. In many cases, this is preferred to +providing additional stability to the interface, as it may better meet the +expectations of the consumer. +.sp +The most common application of this taxonomy level is to interfaces that are +controlled by a body other than Sun, but unlike specifications controlled by +standards bodies or Free or Open Source Software (FOSS) communities which value +interface compatibility, it can not be asserted that an incompatible change to +the interface specification would be exceedingly rare. It may also be applied +to FOSS controlled software where it is deemed more important to track the +community with minimal latency than to provide stability to our customers. +.sp +It also common to apply the Volatile classification level to interfaces in the +process of being defined by trusted or widely accepted organization. These are +generically referred to as draft standards. An "IETF Internet draft" is a well +understood example of a specification under development. +.sp +Volatile can also be applied to experimental interfaces. +.sp +No assertion is made regarding either source or binary compatibility of +Volatile interfaces between any two releases, including patches. Applications +containing these interfaces might fail to function properly in any future +release. +.RE + +.sp +.ne 2 +.na +\fB\fBNot-an-Interface\fR\fR +.ad +.sp .6 +.RS 4n +The situation occasionally occurs where there exists an entity that could be +inferred to be an interface, but actually is not. Common examples are output +from CLIs intended only for human consumption and the exact layout of a GUI. +.sp +This classification is a convenience term to be used to clarify such situations +where such confusion is identified as likely. Failure to apply this term to an +entity is not an indication that the entity is some form of interface. It only +indicates that the potential for confusion was not identified. +.RE + +.sp +.ne 2 +.na +\fB\fBPrivate\fR\fR +.ad +.sp .6 +.RS 4n +A Private interface is an interface provided by a component (or product) +intended only for the use of that component. A Private interface might still be +visible to or accessible by other components. Because the use of interfaces +private to another component carries great stability risks, such use is +explicitly not supported. Components not supplied by Sun Microsystems should +not use Private interfaces. +.sp +Most Private interfaces are not documented. It is an exceptional case when a +Private interface is documented. Reasons for documenting a Private interface +include, but are not limited to, the intention that the interface might be +reclassified to one of the public stability level classifications in the future +or the fact that the interface is inordinately visible. +.RE + +.sp +.ne 2 +.na +\fB\fBObsolete\fR\fR +.ad +.sp .6 +.RS 4n +Obsolete is a modifier that can appear in conjunction with the above +classification levels. The Obsolete modifier indicates an interface that is +"deprecated" and/or no longer advised for general use. An existing interface +may be downgraded from some other status (such as Committed or Uncommitted) by +the application of the Obsolete modifier to encourage customers to migrate from +that interface before it may be removed (or incompatibly changed). +.sp +An Obsolete interface is supported in the current release, but is scheduled to +be removed in a future (minor) release. When support of an interface is to be +discontinued, Sun will attempt to provide notification before discontinuing +support. Use of an Obsolete interface may produce warning messages. +.RE + +.SS "Exceptions" +.LP +There are rare instances when it is in the best interest of both Sun and the +customer to break the interface stability commitment. The following list +contains the common, known reasons for the interface provider to violate an +interface stability commitment, but does not preclude others. +.RS +4 +.TP +1. +Security holes where the vulnerability is inherent in the interface. +.RE +.RS +4 +.TP +2. +Data corruption where the vulnerability is inherent in the interface. +.RE +.RS +4 +.TP +3. +Standards violations uncovered by a change in interpretation or enhancement +of conformance tests. +.RE +.RS +4 +.TP +4. +An interface specification which isn't controlled by Sun has been changed +incompatibly and the vast majority of interface consumers expect the newer +interface. +.RE +.RS +4 +.TP +5. +Not making the incompatible change would be incomprehensible to our +customers. One example of this would to have not incompatibly changed pcfs +when the DOS 8.3 naming restrictions were abandoned. +.RE +.sp +.LP +Incompatible changes allowed by exception will always be delivered in the "most +major" release vehicle possible. However, often the consequences of the +vulnerabilities or contractual branding requirements will force delivery in a +patch. +.SS "Compatibility with Earlier Interface Classification Schemes" +.LP +In releases up to and including Solaris 10, a different interface +classification scheme was used. The following table summarizes the mapping +between the old and new classification schemes. +.sp + +.sp +.TS +c c c +l l l . +Old New Comments +_ +Standard Committed T{ +An entry in the attributes table for the Standard attribute type should appear. +T} +Stable Committed Name change. +Evolving Uncommitted Actual commitments match. +Unstable Uncommitted Name change. +External Volatile T{ +Name change with expansion of allowed usage. +T} +Obsolete (Obsolete) Was a classification, now a modifier. +.TE + +.sp +.LP +The increased importance of Free or Open Source Software motivated the name +change from Stable/Unstable to Committed/Uncommitted. Stable conflicted with +the common use of the term in FOSS communities. +.sp +.LP +Ambiguity in the definition of Evolving was causing difficulty in +interpretation. As part of the migration to the new classification scheme, many +formerly Evolving interfaces were upgraded to Committed. However, upon +encountering the term Evolving, Uncommitted should be inferred. +.SS "MT-Level" +.LP +Libraries are classified into categories that define their ability to support +multiple threads. Manual pages containing functions that are of multiple or +differing levels describe this in their \fBNOTES\fR or \fBUSAGE\fR section. +.sp +.ne 2 +.na +\fB\fBSafe\fR\fR +.ad +.sp .6 +.RS 4n +Safe is an attribute of code that can be called from a multithreaded +application. The effect of calling into a Safe interface or a safe code segment +is that the results are valid even when called by multiple threads. Often +overlooked is the fact that the result of this Safe interface or safe code +segment can have global consequences that affect all threads. For example, the +action of opening or closing a file from one thread is visible by all the +threads within a process. A multithreaded application has the responsibility +for using these interfaces in a safe manner, which is different from whether or +not the interface is Safe. For example, a multithreaded application that closes +a file that is still in use by other threads within the application is not +using the \fBclose\fR(2) interface safely. +.RE + +.sp +.ne 2 +.na +\fB\fBUnsafe\fR\fR +.ad +.sp .6 +.RS 4n +An Unsafe library contains global and static data that is not protected. It is +not safe to use unless the application arranges for only one thread at time to +execute within the library. Unsafe libraries might contain functions that are +Safe; however, most of the library's functions are unsafe to call. Some +functions that are Unsafe have reentrant counterparts that are MT-Safe. +Reentrant functions are designated by the \fB_r\fR suffix appended to the +function name. +.RE + +.sp +.ne 2 +.na +\fB\fBMT-Safe\fR\fR +.ad +.sp .6 +.RS 4n +An MT-Safe library is fully prepared for multithreaded access. It protects its +global and static data with locks, and can provide a reasonable amount of +concurrency. A library can be safe to use, but not MT-Safe. For example, +surrounding an entire library with a monitor makes the library Safe, but it +supports no concurrency so it is not considered MT-Safe. An MT-Safe library +must permit a reasonable amount of concurrency. (This definition's purpose is +to give precision to what is meant when a library is described as Safe. The +definition of a Safe library does not specify if the library supports +concurrency. The MT-Safe definition makes it clear that the library is Safe, +and supports some concurrency. This clarifies the Safe definition, which can +mean anything from being single threaded to being any degree of multithreaded.) +.RE + +.sp +.ne 2 +.na +\fB\fBAsync-Signal-Safe\fR\fR +.ad +.sp .6 +.RS 4n +Async-Signal-Safe refers to particular library functions that can be safely +called from a signal handler. A thread that is executing an Async-Signal-Safe +function will not deadlock with itself if interrupted by a signal. Signals are +only a problem for MT-Safe functions that acquire locks. +.sp +Async-Signal-Safe functions are also MT-Safe. Signals are disabled when locks +are acquired in Async-Signal-Safe functions. These signals prevent a signal +handler that might acquire the same lock from being called. +.RE + +.sp +.ne 2 +.na +\fB\fBMT-Safe with Exceptions\fR\fR +.ad +.sp .6 +.RS 4n +See the \fBNOTES\fR or \fBUSAGE\fR sections of these pages for a description of +the exceptions. +.RE + +.sp +.ne 2 +.na +\fB\fBSafe with Exceptions\fR\fR +.ad +.sp .6 +.RS 4n +See the \fBNOTES\fR or \fBUSAGE\fR sections of these pages for a description of +the exceptions. +.RE + +.sp +.ne 2 +.na +\fB\fBFork-Safe\fR\fR +.ad +.sp .6 +.RS 4n +The \fBfork\fR(2) function replicates only the calling thread in the child +process. The \fBfork1\fR(2) function exists for compatibility with the past and +is synonymous with \fBfork()\fR. If a thread other than the one performing the +fork holds a lock when \fBfork()\fR is called, the lock will still be held in +the child process but there will be no lock owner since the owning thread was +not replicated. A child calling a function that attempts to acquire the lock +will deadlock itself. +.sp +When \fBfork()\fR is called, a Fork-Safe library arranges to have all of its +internal locks held only by the thread performing the fork. This is usually +accomplished with \fBpthread_atfork\fR(3C), which is called when the library is +initialized. +.sp +The \fBforkall\fR(2) function provides the capability for the rare case when a +process needs to replicate all of its threads when performing a fork. No +\fBpthread_atfork()\fR actions are performed when \fBforkall()\fR is called. +There are dangers associated with calling \fBforkall()\fR. If some threads in a +process are performing I/O operations when another thread calls +\fBforkall()\fR, they will continue performing the same I/O operations in both +the parent and child processes, possibly causing data corruption. For this and +other race-condition reasons, the use of \fBforkall()\fR is discouraged. +.sp +In all Solaris releases prior to Solaris 10, the behavior of \fBfork()\fR +depended on whether or not the application was linked with \fB-lpthread\fR +(POSIX threads, see \fBstandards\fR(7)). If linked with \fB-lpthread\fR, +\fBfork()\fR behaved like \fBfork1()\fR; otherwise it behaved like +\fBforkall()\fR. To avoid any confusion concerning the behavior of +\fBfork()\fR, applications can specifically call \fBfork1()\fR or +\fBforkall()\fR as appropriate. +.RE + +.sp +.ne 2 +.na +\fB\fBCancel-Safety\fR\fR +.ad +.sp .6 +.RS 4n +If a multithreaded application uses \fBpthread_cancel\fR(3C) to cancel (that +is, kill) a thread, it is possible that the target thread is killed while +holding a resource, such as a lock or allocated memory. If the thread has not +installed the appropriate cancellation cleanup handlers to release the +resources appropriately (see \fBpthread_cancel\fR(3C)), the application is +"cancel-unsafe", that is, it is not safe with respect to cancellation. This +unsafety could result in deadlocks due to locks not released by a thread that +gets cancelled, or resource leaks; for example, memory not being freed on +thread cancellation. All applications that use \fBpthread_cancel\fR(3C) should +ensure that they operate in a Cancel-Safe environment. Libraries that have +cancellation points and which acquire resources such as locks or allocate +memory dynamically, also contribute to the cancel-unsafety of applications that +are linked with these libraries. This introduces another level of safety for +libraries in a multithreaded program: Cancel-Safety. There are two +sub-categories of Cancel-Safety: Deferred-Cancel-Safety, and +Asynchronous-Cancel-Safety. An application is considered to be +Deferred-Cancel-Safe when it is Cancel-Safe for threads whose cancellation type +is \fBPTHREAD_CANCEL_DEFERRED\fR. An application is considered to be +Asynchronous-Cancel-Safe when it is Cancel-Safe for threads whose cancellation +type is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR. Deferred-Cancel-Safety is easier to +achieve than Asynchronous-Cancel-Safety, since a thread with the deferred +cancellation type can be cancelled only at well-defined cancellation points, +whereas a thread with the asynchronous cancellation type can be cancelled +anywhere. Since all threads are created by default to have the deferred +cancellation type, it might never be necessary to worry about asynchronous +cancel safety. Most applications and libraries are expected to always be +Asynchronous-Cancel-Unsafe. An application which is Asynchronous-Cancel-Safe is +also, by definition, Deferred-Cancel-Safe. +.RE + +.SS "Standard" +.LP +Many interfaces are defined and controlled as industry standards. When this is +the case, the controlling body and/or public, versioned document is noted in +this section. +.sp +.LP +Programmers producing portable applications should rely on the interface +descriptions present in the standard or specification to which the application +is intended to conform, rather than the manual page descriptions of interfaces +based upon a public standard. When the standard or specification allows +alternative implementation choices, the manual page usually only describes the +alternative implemented by Sun. The manual page also describes any compatible +extensions to the base definition of Standard interfaces provided by Sun. +.sp +.LP +No endorsement of the referenced controlling body or document should be +inferred by its presence as a "Standard" entry. The controlling body may be a +very formal organization, as in ISO or ANSII, a less formal, but generally +accepted organization such as IETF, or as informal as the sole contributor in +the case of FOSS (Free or Open Source Software). +.SH SEE ALSO +.LP +.BR uname (1), +.BR Intro (3), +.BR standards (7) diff --git a/usr/src/man/man7/audit_binfile.7 b/usr/src/man/man7/audit_binfile.7 new file mode 100644 index 0000000000..0099c05698 --- /dev/null +++ b/usr/src/man/man7/audit_binfile.7 @@ -0,0 +1,80 @@ +'\" te +.\" Copyright (c) 2017 Peter Tribble +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH AUDIT_BINFILE 7 "Mar 6, 2017" +.SH NAME +audit_binfile \- generation of audit logs +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/audit_binfile.so\fR +.fi + +.SH DESCRIPTION +.LP +The \fBaudit_binfile\fR plugin module for audit, +\fB/usr/lib/security/audit_binfile.so\fR, writes binary audit data to files as +specified in the plugin's attributes configured by \fBauditconfig\fR(8); it +is the default plugin for the audit daemon \fBauditd\fR(8). Its output is +described by \fBaudit.log\fR(5). +.SH OBJECT ATTRIBUTES +.LP +The \fBp_dir\fR attribute specifies a comma-separated list of +directories to be used for storing audit files. +.sp +.LP +The \fBp_minfree\fR attribute specifies the percentage of free space required. +If free space falls below this threshold, the audit daemon \fBauditd\fR(8) +invokes the shell script \fBaudit_warn\fR(8). The default threshold is 0%. +.sp +.LP +The \fBp_fsize\fR attribute defines the maximum size in bytes that an audit +file can become before it is automatically closed and a new audit file opened. +This is equivalent to an administrator issuing an \fBaudit\fR \fB-n\fR command +when the audit file contains the specified number of bytes. The default size is +zero (0), which allows the file to grow without bound. The value specified must +be within the range of [512,000, 2,147,483,647]. +.SH EXAMPLES +.LP +The following commands cause \fBaudit_binfile.so\fR to be activated, specify the +directories for writing audit logs, and specify the percentage of required free +space per directory. Note that using \fBauditconfig\fR(8) only allows one +attribute to be set at a time. +.sp +.in +2 +.nf +# auditconfig -setplugin audit_binfile active p_minfree=20 +# auditconfig -setplugin audit_binfile active \e +p_dir=/var/audit/jedgar/eggplant,\e +/var/audit/jedgar.aux/eggplant,\e +/var/audit/global/eggplant +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level MT-Safe +_ +Interface Stability Committed +.TE + +.SH SEE ALSO +.LP +.BR audit.log (5), +.BR attributes (7), +.BR auditconfig (8), +.BR auditd (8) diff --git a/usr/src/man/man7/audit_remote.7 b/usr/src/man/man7/audit_remote.7 new file mode 100644 index 0000000000..395378ffa8 --- /dev/null +++ b/usr/src/man/man7/audit_remote.7 @@ -0,0 +1,353 @@ +'\" te +.\" Copyright (c) 2021 Peter Tribble +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH AUDIT_REMOTE 7 "November 22, 2021" +.SH NAME +audit_remote \- send audit logs to a remote server +.SH SYNOPSIS +.nf +\fB/usr/lib/security/audit_remote.so\fR +.fi + +.SH DESCRIPTION +The \fBaudit_remote\fR plugin module for audit, +\fB/usr/lib/security/audit_remote.so\fR, sends binary audit records +(\fBaudit.log\fR(5)) to audit servers specified in the plugin's attributes +configured by \fBauditconfig\fR(8). +.SS "Object Attributes" +The following attributes specify the configuration of the \fBaudit_remote\fR +plugin: +.sp +.ne 2 +.na +\fB\fBp_hosts\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.in +2 +.nf +\fIhost1\fR[:[\fIport1\fR][:\fImech1\fR]][,\fIhost2\fR[:[\fIport2\fR][:\fImech2\fR]],... \e + \fIhostn\fR[:[\fIportn\fR][:\fImechn\fR]]] +.fi +.in -2 +.sp + +A list of audit hosts/servers. Audit records are sent to the first available +host. If a host is unreachable or a timeout occurs while sending data, the next +host in the list is tried. If connection to all hosts fails, the list is tried +again from the beginning. +.sp +The \fIhost\fR part of a \fBp_hosts\fR entry can be in any form acceptable to +\fBgetipnodebyname\fR(3SOCKET). +.sp +The \fIport\fR part of a \fBp_hosts\fR entry is the port on host that is +contacted to initiate an audit server connection. If not specified, the port +number is that assigned to the \fBsolaris-audit\fR service. See +\fBgetservbyname\fR(3XNET). +.sp +The \fBmech\fR part of a \fBp_host\fR entry is the GSS-API mechanism name +(\fBmech\fR(5)). If not specified, the local host's default mechanism is used. +The recommended mechanism is \fBkerberos_v5\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBp_retries\fR\fR +.ad +.sp .6 +.RS 4n +The number of retries for connecting to and sending data to a server. +.sp +The default value is \fB3\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBp_timeout\fR\fR +.ad +.sp .6 +.RS 4n +The number of seconds in which a connection/sending data timeouts. +.sp +The default value is \fB5\fR seconds. +.RE + +.sp +.ne 2 +.na +\fB\fBqsize\fR\fR +.ad +.sp .6 +.RS 4n +The maximum number of outstanding audit records to keep. +.sp +The default is the value of the kernel queue control high water mark. See +\fBauditconfig\fR(8). +.RE + +.SS "GSS SESSION" +The \fBaudit_remote plugin\fR is a TCP client that authenticates configured +audit servers using the GSS-API (\fBlibgss\fR(3LIB)). Binary Audit +records are sent with integrity and confidentiality protection as per-message +tokens generated by \fBgss_wrap\fR(3GSS). +.sp +.LP +The plugin initiates a TCP connection to an audit server (\fIhost:port:mech\fR) +and establishes a GSS security context (with \fBgss_init_sec_context\fR(3GSS)), +with appropriate security mechanism (\fBmech\fR(5)). +.sp +.LP +If no port is specified, the service name \fBsolaris-audit\fR is looked up to +obtain a TCP port number. If no mechanism is specified, the \fBGSS_C_NO_OID\fR +is used as a \fBmech_type\fR parameter of \fBgss_init_sec_context\fR(3GSS), and +causes the underlying \fBGSS-API\fR to use the local default mechanism. +.sp +.LP +\fBgss_init_sec_context\fR(3GSS) uses \fBGSS_C_NO_CREDENTIAL\fR as the +initiator credential handle and a target name of the form +\fBaudit@<ost_fqdn>\fR. The server is expected to use +\fBgss_accept_sec_context\fR(3GSS) to complete the context establishment. +.sp +.LP +Once the security context is established, the client (\fBaudit_remote\fR +plugin) calls \fBgss_wrap\fR(3GSS) to achieve the confidentiality of the +transferred payload - the audit records. The server is expected to use +\fBgss_unwrap\fR(3GSS) to unwrap the received data and \fBgss_get_mic\fR(3GSS) +to obtain the MIC (Message Integrity Code) to be later sent back to the plugin +as a message retrieval acknowledgment. +.sp +.LP +For example, if the \fBkerberos_v5\fR mechanism is configured as \fBGSS_API\fR +mechanism on the client and both sides agree on using this mechanism, the +client side has to be eligible to non-interactively gain session keys for the +\fBaudit/<host_fqdn>@<REALM>\fR principal from the Kerberos KDC/TGS. At the +same time the identity running the audit server application has to have the +long term keys associated with the \fBaudit/<host_fqdn>@<REALM>\fR principal +stored in the \fBkeytab\fR file (\fBkrb5.conf\fR(5)) to be able to decrypt the +session keys. +.sp +.LP +The \fBaudit_remote\fR plugin initiates a connection to first server in the +\fBp_hosts\fR list. If the connection fails or audit record sends are not +responded to in \fBp_timeout\fR seconds, after \fBp_retries\fR attempts the +plugin tries to connect to the next server. If the connection to the last +server fails, the plugin retries to connect to the first host in the list. +\fBaudit_warn\fR(8) is executed at every unsuccessful attempt to connect to +the server or send timeout with the plugin option plugin \fBaudit_remote.so +retry <count> <error>.<error>\fR is connection \fB<host:port> <the network +error>\fR\&. An \fBEPROTO\fR network error indicates that the client plugin did +not get a successful protocol version handshake. +.SS "PROTOCOL DESCRIPTION" +All protocol messages are preceded by the 4 octets of the size of the data to +follow. This size is in network byte order. +.sp +.LP +The protocol begins with version negotiation followed by a \fBGSS-API\fR +security context token exchange. On error the connection is closed (and any +output token optionally sent). +.sp +.LP +The version negotiation takes place in the clear with the plugin sending an +octet array of the comma (\fB,\fR) separated list of versions supported. The +current version number is the characters \fB01\fR. The receiver is expected to +respond with the version that they accept (in the current case that is the +characters \fB01\fR). A mismatch is considered an error and the connection is +closed. +.sp +.LP +The version octet array sent by the plugin and the version characters accepted +by the receiver are concatenated together to make up the application data field +of the channel bindings of the GSS security context establishment. +.sp +.in +2 +.nf +<plugin version characters> || <server accepted version characters>" +||" represents concatenation +.fi +.in -2 + +.sp +.LP +Subsequent tokens contain a 64 bit sequence number in network byte order and a +single audit record (\fBaudit.log\fR(5)); the client uses confidentiality +protection. wrap (64 bit sequence number || audit record) +.sp +.LP +The server acknowledges the receipt (and is then responsible for any data loss) +with the received 64 bit sequence number and a MIC token of the unwrapped 64 +bit sequence number and audit record. MIC verification on the client side +acknowledges the audit record can be freed and not saved for possible +retransmission. +.sp +.in +2 +.nf +64 bit sequence number || mic (64 bit sequence number || audit record) +.fi +.in -2 + +.sp +.LP +Secure remote audit client/server communication flow: +.sp +.in +2 +.nf +1) Client <--> Server - TCP handshake + +2) Client <--> Server - protocol version negotiation: + a) Client --> Server - send data size - uint32_t value (2) + b) Client --> Server - send clear text message of the versions + supported comma separated, e.g., + "01,02,03" for versions 1 and 2 and 3. + The only version supported at present is + "01" + c) Client <-- Server - send data size - uint32_t value (2) + d) Client <-- Server - send clear text version selected + ("01") + :no version match; close connection; try next host + +3) Security context initiation: + a) Client - Construct channel bindings application data value + (4 octets "0101") + b) Client --> Server - send token (data) size - uint32_t value + c) Client --> Server - GSS-API per-context token + d) Client <-- Server - send token (data) size + e) Client <-- Server - GSS-API per-context token + :repeat a-e until security context is initialized; if unsuccessful, + close connection; try next host + +4) Client - transmit thread, when audit record to be sent: + a) Client --> Server - send data size + b) Client --> Server - GSS-API per-message token + wrap (sequence number || audit record) + :repeat a-b while less than max (qsize) outstanding records + + 5) Client - receive thread: + a) Client <-- Server - receive data size - uint32_t value + b) Client <-- Server - receive sequence number - uint64_t value + c) Client <-- Server - receive MIC + d) Client - MIC verification - OK + e) Client - remove particular audit record + pointed by the sequence number from the + retransmit buffer + :repeat a-e, on error close connection; try next host; + retransmit unacknowledged audit records + +6) Server - receive thread: + a) Client --> Server - receive data size + b) Client --> Server - GSS-API receive, uwrap, store + per-message token + +7) Server - transmit thread: + a) Server - MIC generation - message integrity code + mic (sequence number || audit record) + b) Client <-- Server - send data size + c) Client < -- Server - send sequence number + d) Client <-- Server - send MIC +.fi +.in -2 + +.SH EXAMPLES +\fBExample 1 \fRActivating \fBaudit_remote.so\fR and Specifying attributes +.sp +.LP +The following commands cause \fBaudit_remote.so\fR to be activated and set +the \fBp_retries\fR and \fBp_timeout\fR attributes. Note that using +\fBauditconfig\fR(8) only allows one attribute to be set at a time. + +.sp +.in +2 +.nf +# auditconfig -setplugin audit_remote active p_retries=2 +# auditconfig -setplugin audit_remote active p_timeout=90 +.fi +.in -2 + +.LP +\fBExample 2 \fRActivating \fBaudit_remote.so\fR and Specifying the Remote Audit +Servers +.sp +.LP +The following command causes \fBaudit_remote.so\fR to be activated and specifies +the remote audit servers to where the audit records are sent. The +\fBkerberos_v5\fR security mechanism is defined to be used when communicating +with the servers. + +.sp +.in +2 +.nf +# auditconfig -setplugin audit_remote active \e +p_hosts=eggplant.eng.example.com::kerberos_v5,\e +purple.ebay.example.com:4592:kerberos_v5 +.fi +.in -2 + +.LP +\fBExample 3 \fRUsing the Configuration of Usage Default Security Mechanism +.sp +.LP +The following example shows the configuration of usage of default security +mechanism. It also shows use of default port on one of the configured servers: + +.sp +.in +2 +.nf +# auditconfig -setplugin audit_remote active \e +p_hosts=jedger.eng.example.com,\e +jbadams.ebay.example.com:4592 +.fi +.in -2 +.sp + +.SH ATTRIBUTES +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level MT-Safe +_ +Interface Stability See below. +.TE + +.sp +.LP +The plugin configuration parameters are Committed. The client/server protocol +(version \fB"01"\fR) is Contracted Project Private. See \fBaudit.log\fR(5) for +the audit record format and content stability. +.SH SEE ALSO +.BR gss_accept_sec_context (3GSS), +.BR gss_get_mic (3GSS), +.BR gss_init_sec_context (3GSS), +.BR gss_unwrap (3GSS), +.BR gss_wrap (3GSS), +.BR libgss (3LIB), +.BR libsocket (3LIB), +.BR getipnodebyname (3SOCKET), +.BR getservbyname (3XNET), +.BR tcp (4P), +.BR audit.log (5), +.BR krb5.conf (5), +.BR mech (5), +.BR attributes (7), +.BR kerberos (7), +.BR audit_warn (8), +.BR auditconfig (8), +.BR auditd (8) +.SH NOTES +\fBaudit_remote\fR authenticates itself to the remote audit service by way of +GSS-API (\fBlibgss\fR(3LIB)). Default gss credentials are used as provided by +the \fBgss\fR implementation mechanism, such as Kerberos. +.sp +.LP +The \fBsolaris-audit\fR service port assigned by IANA is \fB16162\fR. diff --git a/usr/src/man/man7/audit_syslog.7 b/usr/src/man/man7/audit_syslog.7 new file mode 100644 index 0000000000..ec56ce6f61 --- /dev/null +++ b/usr/src/man/man7/audit_syslog.7 @@ -0,0 +1,268 @@ +'\" te +.\" Copyright (c) 2017 Peter Tribble +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH AUDIT_SYSLOG 7 "Mar 6, 2017" +.SH NAME +audit_syslog \- realtime conversion of audit data to syslog messages +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/audit_syslog.so\fR +.fi + +.SH DESCRIPTION +.LP +The \fBaudit_syslog\fR plugin module for audit, +\fB/usr/lib/security/audit_syslog.so\fR, provides realtime conversion of +audit data to syslog-formatted (text) data and sends it to a syslog +daemon as configured in \fBsyslog.conf\fR(5). +.sp +.LP +Messages to \fBsyslog\fR are written if the \fBaudit_syslog\fR plugin is +activated and configured using \fBauditconfig\fR(8). +.sp +.LP +Syslog messages are generated with the facility code of +\fBLOG_AUDIT\fR (\fBaudit\fR in \fBsyslog.conf\fR(5)) and severity of +\fBLOG_NOTICE\fR. Audit \fBsyslog\fR messages contain data selected from the +tokens described for the binary audit log. (See \fBaudit.log\fR(5)). As with +all \fBsyslog\fR messages, each line in a \fBsyslog\fR file consists of two +parts, a \fBsyslog\fR header and a message. +.sp +.LP +The syslog header contains the date and time the message was generated, the +host name from which it was sent, \fBauditd\fR to indicate that it was +generated by the audit daemon, an ID field used internally by \fBsyslogd\fR, +and \fBaudit.notice\fR indicating the \fBsyslog\fR facility and severity +values. The \fBsyslog\fR header ends with the characters \fB]\fR, that is, a +closing square bracket and a space. +.sp +.LP +The message part starts with the event type from the header token. All +subsequent data appears only if contained in the original audit record and +there is room in the 1024-byte maximum length \fBsyslog\fR line. In the +following example, the backslash (\fB\e\fR) indicates a continuation; actual +\fBsyslog\fR messages are contained on one line: +.sp +.in +2 +.nf +Oct 31 11:38:08 smothers auditd: [ID 917521 audit.notice] chdir(2) ok\e +session 401 by joeuser as root:other from myultra obj /export/home +.fi +.in -2 +.sp + +.sp +.LP +In the preceding example, \fBchdir(2)\fR is the event type. Following this +field is additional data, described below. This data is omitted if it is not +contained in the source audit record. +.sp +.ne 2 +.na +\fB\fBok\fR or \fBfailed\fR\fR +.ad +.RS 21n +Comes from the return or exit token. +.RE + +.sp +.ne 2 +.na +\fB\fBsession \fI<#>\fR\fR\fR +.ad +.RS 21n +\fI<#>\fR is the session ID from the subject token. +.RE + +.sp +.ne 2 +.na +\fB\fBby \fI<name>\fR\fR\fR +.ad +.RS 21n +\fI<name>\fR is the audit ID from the subject token. +.RE + +.sp +.ne 2 +.na +\fB\fBas \fI<name>\fR:\fI<group>\fR\fR\fR +.ad +.RS 21n +\fI<name>\fR is the effective user ID and \fI<group>\fR is the effective group +ID from the subject token. +.RE + +.sp +.ne 2 +.na +\fB\fBin\fR \fI<zone name>\fR\fR +.ad +.RS 21n +The zone name. This field is generated only if the \fBzonename\fR audit policy +is set. +.RE + +.sp +.ne 2 +.na +\fB\fBfrom \fI<terminal>\fR\fR\fR +.ad +.RS 21n +\fI<terminal>\fR is the text machine address from the subject token. +.RE + +.sp +.ne 2 +.na +\fB\fBobj \fI<path>\fR\fR\fR +.ad +.RS 21n +\fI<path>\fR is the path from the path token The path can be truncated from the +left if necessary to fit it on the line. Truncation is indicated by leading +ellipsis (\fB\&...\fR). +.RE + +.sp +.ne 2 +.na +\fB\fBproc_uid \fI<owner>\fR\fR\fR +.ad +.RS 21n +\fI<owner>\fR is the effective user ID of the process owner. +.RE + +.sp +.ne 2 +.na +\fB\fBproc_auid \fI<owner>\fR\fR\fR +.ad +.RS 21n +\fI<owner>\fR is the audit ID of the process owner. +.RE + +.sp +.LP +The following are example \fBsyslog\fR messages: +.sp +.in +2 +.nf +Nov 4 8:27:07 smothers auditd: [ID 175219 audit.notice] \e +system booted + +Nov 4 9:28:17 smothers auditd: [ID 752191 audit.notice] \e +login - rlogin ok session 401 by joeuser as joeuser:staff from myultra + +Nov 4 10:29:27 smothers auditd: [ID 521917 audit.notice] \e +access(2) ok session 255 by janeuser as janeuser:staff from \e +129.146.89.30 obj /etc/passwd +.fi +.in -2 +.sp + +.SH OBJECT ATTRIBUTES +.LP +The \fBp_flags\fR attribute is used to further filter audit data being sent +to the \fBsyslog\fR daemon beyond the default and non-attributable +audit flags. The parameter is a comma-separated list; each +item represents an audit class (see \fBaudit_class\fR(5)) and is specified +using the same syntax used by \fBauditconfig\fR for the \fB-setflags\fR and +\fB-setnaflags\fR options. The default (no \fBp_flags\fR set) is that no +audit records are generated. +.SH EXAMPLES +.LP +\fBExample 1 \fREnabling the plugin and selecting events +.sp +.LP +The command below enables the \fBaudit_syslog\fR plugin and sets the +\fBp_flags\fR filter to allow class records for \fBlo\fR but +allows class records for \fBam\fR for failures only. Because no other +classes are listed, not other audit records will be sent to +syslog. You cannot add classes to those defined by means of +\fBflags\fR and \fBnaflags\fR. You can only remove them. + +.sp +.in +2 +.nf +# autditconf -setplugin audit_syslog active p_flags=lo,-am +.fi +.in -2 +.sp + +\fBExample 2 \fRViewing the plugin configuration +.sp +.LP +The command below enables shows the \fBaudit_syslog\fR plugin configuration. + +.sp +.in +2 +.nf +# auditconfig -getplugin audit_syslog +Plugin: audit_syslog (active) + Attributes: p_flags=lo,-am; +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level MT-Safe +_ +Interface Stability See below. +.TE + +.sp +.LP +The message format and message content are Uncommitted. The configuration +parameters are Committed. +.SH SEE ALSO +.LP +.BR audit_class (5), +.BR syslog.conf (5), +.BR attributes (7), +.BR auditconfig (8), +.BR auditd (8) +.SH NOTES +.LP +Use of the \fBplugin\fR configuration line to include \fBaudit_syslog.so\fR +requires that \fB/etc/syslog.conf\fR is configured to store \fBsyslog\fR +messages of facility \fBaudit\fR and severity \fBnotice\fR or above in a file +intended for audit records. An example of such a line in +\fBsyslog.conf\fR is: +.sp +.in +2 +.nf +audit.notice /var/audit/audit.log +.fi +.in -2 +.sp + +.sp +.LP +Messages from \fBsyslog\fR are sent to remote \fBsyslog\fR servers by means of +UDP, which does not guarantee delivery or ensure the correct order of arrival +of messages. +.sp +.LP +If the \fBp_flags\fR attribute results in no classes +being preselected, an error is reported by means of a \fBsyslog\fR alert with +the \fBLOG_DAEMON\fR facility code. +.sp +.LP +The time field in the \fBsyslog\fR header is generated by \fBsyslog\fR(3C) and +only approximates the time given in the binary audit log. Normally the time +field shows the same whole second or at most a few seconds difference. diff --git a/usr/src/man/man7/beastie.4th.7 b/usr/src/man/man7/beastie.4th.7 new file mode 100644 index 0000000000..44129ebcb9 --- /dev/null +++ b/usr/src/man/man7/beastie.4th.7 @@ -0,0 +1,146 @@ +.\" Copyright (c) 2011-2012 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt BEASTIE.4TH 7 +.Os +.Sh NAME +.Nm beastie.4th +.Nd loader ASCII art boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to draw the ASCII art FreeBSD mascot +\(en known simply as +.Em beastie +\(en to the right of the boot loader menu. +In illumos based systems, the distribution specific logo is used. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include beastie.4th +.Pp +This line is present in the default +.Pa /boot/loader.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic draw-beastie +Draws the logo. +.Pp +The logo that is drawn is configured by setting the +.Ic loader_logo +variable in +.Xr loader.conf 5 . +.Pp +The position of the logo can be configured by setting the +.Ic loader_logo_x +and +.Ic loader_logo_y +variables in +.Xr loader.conf 5 . +The default values are 46 (x) and 4 (y). +.Pp +.It Ic clear-beastie +Clears the screen of beastie. +.Pp +.It Ic beastie-start +Initializes the interactive boot loader menu. +.Pp +The +.Ic loader_delay +variable can be configured in +.Xr loader.conf 5 +to the number of seconds you would like to delay loading the boot menu. +During the delay the user can press Ctrl-C to fall back to +.Ic autoboot +or ENTER to proceed. +The default behavior is to not delay. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_logo +Selects the desired logo in the beastie boot menu. +.It Va loader_logo_x +Sets the desired column position of the logo. +Default is 46. +.It Va loader_logo_y +Sets the desired row position of the logo. +Default is 4. +.It Va beastie_disable +If set to +.Dq YES , +the beastie boot menu will be skipped. +The beastie boot menu is always skipped if running non-x86 hardware. +.It Va loader_delay +If set to a number higher than zero, introduces a delay before starting the +beastie boot menu. +During the delay the user can press either Ctrl-C to skip the menu or ENTER to +proceed to the menu. +The default is to not delay when loading the menu. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/beastie.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +Standard i386 +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/beastie.4th +beastie-start +.Ed +.Pp +Set a different logo in +.Xr loader.conf 5 : +.Pp +.Bd -literal -offset indent -compact +loader_logo="beastie" +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr loader 7 , +.Xr loader.4th 7 diff --git a/usr/src/man/man7/brand.4th.7 b/usr/src/man/man7/brand.4th.7 new file mode 100644 index 0000000000..ccb2f8a898 --- /dev/null +++ b/usr/src/man/man7/brand.4th.7 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2011 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt BRAND.4TH 7 +.Os +.Sh NAME +.Nm brand.4th +.Nd loader ASCII art boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to draw the ASCII art illumos brand above the +boot loader menu. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include brand.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic draw-brand +Draws the illumos brand. +.Pp +The brand that is drawn is configured by setting the +.Ic loader_brand +variable in +.Xr loader.conf 5 +to one of +.Dq Li illumos +(the default) or +.Dq Li none . +.Pp +The position of the logo can be configured by setting the +.Ic loader_brand_x +and +.Ic loader_brand_y +variables in +.Xr loader.conf 5 . +The default values are 2 (x) and 1 (y). +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_brand +Selects the desired brand in the beastie boot menu. +Possible values are: +.Dq Li illumos +(default) or +.Dq Li none . +.It Va loader_brand_x +Sets the desired column position of the brand. +Default is 2. +.It Va loader_brand_y +Sets the desired row position of the brand. +Default is 1. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/brand.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +Set illumos brand in +.Xr loader.conf 5 : +.Pp +.Bd -literal -offset indent -compact +loader_brand="illumos" +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr loader 7 diff --git a/usr/src/man/man7/brands.7 b/usr/src/man/man7/brands.7 new file mode 100644 index 0000000000..a094db5edc --- /dev/null +++ b/usr/src/man/man7/brands.7 @@ -0,0 +1,77 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH BRANDS 7 "May 23, 2021" +.SH NAME +brands \- alternate operating environments for non-global zones +.SH DESCRIPTION +The branded zone (BrandZ) framework extends the Solaris Zones infrastructure +described in \fBzones\fR(7) to include the creation of brands, which provide +non-global zones that contain non-native operating environments. +.sp +.LP +The term "brand" can refer to a wide range of operating environments. All brand +management is performed as extensions to the current zones structure. +.sp +.LP +Every zone is configured with an associated brand. The brand type is used to +determine which scripts are executed when a zone is installed and booted. In +addition, a zone's brand is used to properly identify the correct application +type at application launch time. The default brand is determined by the +installed distribution in the global zone. +.sp +.LP +A branded zone will support exactly one brand of non-native binary, which means +that a branded zone provides a single operating environment. Once a zone has +been assigned a brand, that brand cannot be changed or removed. +.sp +.LP +BrandZ extends the zones tools in the following ways: +.RS +4 +.TP +.ie t \(bu +.el o +A brand is an attribute of a zone, set at zone create time. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The zonecfg tool (see \fBzonecfg\fR(8)) is used to set a zone's brand type and +configure the zone. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The zoneadm tool (see \fBzoneadm\fR(8)) is used to report a zone's brand type +and administer the zone. +.RE +.SS "Device Support" +The devices supported by each zone are documented in the man pages and other +documentation for that brand. The zones infrastructure detects any attempt to +add an unsupported device and issues a warning to the administrator. If the +administrator chooses to add an unsupported device despite that warning, that +device might or might not work as expected. The configuration will be untested +and unsupported. +.SH ATTRIBUTES +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +.TE + +.SH SEE ALSO +.BR attributes (7), +.BR zones (7), +.BR zoneadm (8), +.BR zonecfg (8) diff --git a/usr/src/man/man7/byteorder.7 b/usr/src/man/man7/byteorder.7 new file mode 100644 index 0000000000..33ab61636c --- /dev/null +++ b/usr/src/man/man7/byteorder.7 @@ -0,0 +1,270 @@ +.\" +.\" 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 2016 Joyent, Inc. +.\" +.Dd August 2, 2018 +.Dt BYTEORDER 7 +.Os +.Sh NAME +.Nm byteorder , +.Nm endian +.Nd byte order and endianness +.Sh DESCRIPTION +Integer values which occupy more than 1 byte in memory can be laid out +in different ways on different platforms. +In particular, there is a major split between those which place the least +significant byte of an integer at the lowest address, and those which place the +most significant byte there instead. +As this difference relates to which end of the integer is found in memory first, +the term +.Em endian +is used to refer to a particular byte order. +.Pp +A platform is referred to as using a +.Em big-endian +byte order when it places the most significant byte at the lowest +address, and +.Em little-endian +when it places the least significant byte first. +Some platforms may also switch between big- and little-endian mode and run code +compiled for either. +.Pp +Historically, there have also been some systems that utilized +.Em middle-endian +byte orders for integers larger than 2 bytes. +Such orderings are not in common use today. +.Pp +Endianness is also of particular importance when dealing with values +that are being read into memory from an external source. +For example, network protocols such as IP conventionally define the fields in a +packet as being always stored in big-endian byte order. +This means that a little-endian machine will have to perform transformations on +these fields in order to process them. +.Ss Examples +To illustrate endianness in memory, let us consider the decimal integer +2864434397. +This number fits in 32 bits of storage (4 bytes). +.Pp +On a big-endian system, this integer would be written into memory as +the bytes 0xAA, 0xBB, 0xCC, 0xDD, in order from lowest memory address to +highest. +.Pp +On a little-endian system, it would be written instead as the bytes +0xDD, 0xCC, 0xBB, 0xAA, in that order. +.Pp +If both the big- and little-endian systems were asked to store this +integer at address 0x100, we would see the following in each of their +memory: +.Bd -literal + + Big-Endian + + ++------++------++------++------++ + || 0xAA || 0xBB || 0xCC || 0xDD || + ++------++------++------++------++ + ^^ ^^ ^^ ^^ + 0x100 0x101 0x102 0x103 + vv vv vv vv + ++------++------++------++------++ + || 0xDD || 0xCC || 0xBB || 0xAA || + ++------++------++------++------++ + + Little-Endian +.Ed +.Pp +It is particularly important to note that even though the byte order is +different between these two machines, the bit ordering within each byte, +by convention, is still the same. +.Pp +For example, take the decimal integer 4660, which occupies in 16 bits (2 +bytes). +.Pp +On a big-endian system, this would be written into memory as 0x12, then +0x34. +.Pp +On a little-endian system, it would be written as 0x34, then 0x12. +Note that this is not at all the same as seeing 0x43 then 0x21 in memory -- +only the bytes are re-ordered, not any bits (or nybbles) within them. +.Pp +As before, storing this at address 0x100: +.Bd -literal + Big-Endian + + ++------++------++ + || 0x12 || 0x34 || + ++------++------++ + ^^ ^^ + 0x100 0x101 + vv vv + ++------++------++ + || 0x34 || 0x12 || + ++------++------++ + + Little-Endian +.Ed +.Pp +This example shows how an eight byte number, 0xBADCAFEDEADBEEF is stored +in both big and little-endian: +.Bd -literal + Big-Endian + + +------+------+------+------+------+------+------+------+ + | 0xBA | 0xDC | 0xAF | 0xFE | 0xDE | 0xAD | 0xBE | 0xEF | + +------+------+------+------+------+------+------+------+ + ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^ + 0x100 0x101 0x102 0x103 0x104 0x105 0x106 0x107 + vv vv vv vv vv vv vv vv + +------+------+------+------+------+------+------+------+ + | 0xEF | 0xBE | 0xAD | 0xDE | 0xFE | 0xAF | 0xDC | 0xBA | + +------+------+------+------+------+------+------+------+ + + Little-Endian + +.Ed +.Pp +The treatment of different endian values would not be complete without +discussing +.Em PDP-endian , +which is also known as +.Em middle-endian . +While the PDP-11 was a 16-bit little-endian system, it laid out 32-bit +values in a different way from current little-endian systems. +First, it would divide a 32-bit number into two 16-bit numbers. +Each 16-bit number would be stored in little-endian; however, the two 16-bit +words would be stored with the larger 16-bit word appearing first in memory, +followed by the latter. +.Pp +The following image illustrates PDP-endian and compares it against +little-endian values. +Here, we'll start with the value 0xAABBCCDD and show how the four bytes for it +will be laid out, starting at 0x100. +.Bd -literal + PDP-Endian + + ++------++------++------++------++ + || 0xBB || 0xAA || 0xDD || 0xCC || + ++------++------++------++------++ + ^^ ^^ ^^ ^^ + 0x100 0x101 0x102 0x103 + vv vv vv vv + ++------++------++------++------++ + || 0xDD || 0xCC || 0xBB || 0xAA || + ++------++------++------++------++ + + Little-Endian + +.Ed +.Ss Network Byte Order +The term 'network byte order' refers to big-endian ordering, and +originates from the IEEE. +Early disagreements over which byte ordering to use for network traffic prompted +RFC1700 to define that all IETF-specified network protocols use big-endian +ordering unless noted explicitly otherwise. +The Internet protocol family (IP, and thus TCP and UDP etc) particularly adhere +to this convention. +.Ss Determining the System's Byte Order +The operating system supports both big-endian and little-endian CPUs. +To make it easier for programs to determine the endianness of the platform they +are being compiled for, functions and macro constants are provided in the system +header files. +.Pp +The endianness of the system can be obtained by including the header +.In sys/types.h +and using the pre-processor macros +.Sy _LITTLE_ENDIAN +and +.Sy _BIG_ENDIAN . +See +.Xr types.h 3HEAD +for more information. +.Pp +Additionally, the header +.In endian.h +defines an alternative means for determining the endianness of the +current system. +See +.Xr endian.h 3HEAD +for more information. +.Pp +illumos runs on both big- and little-endian systems. +When writing software for which the endianness is important, one must always +check the byte order and convert it appropriately. +.Ss Converting Between Byte Orders +The system provides two different sets of functions to convert values +between big-endian and little-endian. +They are defined in +.Xr byteorder 3C +and +.Xr endian 3C . +.Pp +The +.Xr byteorder 3C +family of functions convert data between the host's native byte order +and big- or little-endian. +The functions operate on either 16-bit, 32-bit, or 64-bit values. +Functions that convert from network byte order to the host's byte order +start with the string +.Sy ntoh , +while functions which convert from the host's byte order to network byte +order, begin with +.Sy hton . +For example, to convert a 32-bit value, a long, from network byte order +to the host's, one would use the function +.Xr ntohl 3C . +.Pp +These functions have been standardized by POSIX. +However, the 64-bit variants, +.Xr ntohll 3C +and +.Xr htonll 3C +are not standardized and may not be found on other systems. +For more information on these functions, see +.Xr byteorder 3C . +.Pp +The second family of functions, +.Xr endian 3C , +provide a means to convert between the host's byte order +and big-endian and little-endian specifically. +While these functions are similar to those in +.Xr byteorder 3C , +they more explicitly cover different data conversions. +Like them, these functions operate on either 16-bit, 32-bit, or 64-bit values. +When converting from big-endian, to the host's endianness, the functions +begin with +.Sy betoh . +If instead, one is converting data from the host's native endianness to +another, then it starts with +.Sy htobe . +When working with little-endian data, the prefixes +.Sy letoh +and +.Sy htole +convert little-endian data to the host's endianness and from the host's +to little-endian respectively. +.Pp +These functions are not standardized and the header they appear in varies +between the BSDs and GNU/Linux. +Applications that wish to be portable, should instead use the +.Xr byteorder 3C +functions. +.Pp +All of these functions in both families simply return their input when +the host's native byte order is the same as the desired order. +For example, when calling +.Xr htonl 3C +on a big-endian system the original data is returned with no conversion +or modification. +.Sh SEE ALSO +.Xr byteorder 3C , +.Xr endian 3C , +.Xr endian.h 3HEAD , +.Xr inet 3HEAD diff --git a/usr/src/man/man7/cancellation.7 b/usr/src/man/man7/cancellation.7 new file mode 100644 index 0000000000..4b3362127b --- /dev/null +++ b/usr/src/man/man7/cancellation.7 @@ -0,0 +1,438 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" +.TH CANCELLATION 7 "Oct 4, 2005" +.SH NAME +cancellation \- overview of concepts related to POSIX thread cancellation +.SH DESCRIPTION +.TS +box; +c | c +l | l . +FUNCTION ACTION +_ +\fBpthread_cancel()\fR Cancels thread execution. +\fBpthread_setcancelstate()\fR Sets the cancellation \fIstate\fR of a thread. +\fBpthread_setcanceltype()\fR Sets the cancellation \fItype\fR of a thread. +\fBpthread_testcancel()\fR T{ +Creates a cancellation point in the calling thread. +T} +\fBpthread_cleanup_push()\fR Pushes a cleanup handler routine. +\fBpthread_cleanup_pop()\fR Pops a cleanup handler routine. +.TE + +.SS "Cancellation" +.LP +Thread cancellation allows a thread to terminate the execution of any +application thread in the process. Cancellation is useful when further +operations of one or more threads are undesirable or unnecessary. +.sp +.LP +An example of a situation that could benefit from using cancellation is an +asynchronously-generated cancel condition such as a user requesting to close or +exit some running operation. Another example is the completion of a task +undertaken by a number of threads, such as solving a maze. While many threads +search for the solution, one of the threads might solve the puzzle while the +others continue to operate. Since they are serving no purpose at that point, +they should all be canceled. +.SS "Planning Steps" +.LP +Planning and programming for most cancellations follow this pattern: +.RS +4 +.TP +1. +Identify which threads you want to cancel, and insert +\fBpthread_cancel\fR(3C) statements. +.RE +.RS +4 +.TP +2. +Identify system-defined cancellation points where a thread that might be +canceled could have changed system or program state that should be restored. +See the \fBCancellation Points\fR for a list. +.RE +.RS +4 +.TP +3. +When a thread changes the system or program state just before a cancellation +point, and should restore that state before the thread is canceled, place a +cleanup handler before the cancellation point with +\fBpthread_cleanup_push\fR(3C). Wherever a thread restores the changed state, +pop the cleanup handler from the cleanup stack with +\fBpthread_cleanup_pop\fR(3C). +.RE +.RS +4 +.TP +4. +Know whether the threads you are canceling call into cancel-unsafe +libraries, and disable cancellation with \fBpthread_setcancelstate\fR(3C) +before the call into the library. See \fBCancellation State\fR and +\fBCancel-Safe\fR. +.RE +.RS +4 +.TP +5. +To cancel a thread in a procedure that contains no cancellation points, +insert your own cancellation points with \fBpthread_testcancel\fR(3C). This +function creates cancellation points by testing for pending cancellations and +performing those cancellations if they are found. Push and pop cleanup handlers +around the cancellation point, if necessary (see Step 3, above). +.RE +.SS "Cancellation Points" +.LP +The system defines certain points at which cancellation can occur (cancellation +points), and you can create additional cancellation points in your application +with \fBpthread_testcancel()\fR. +.sp +.LP +The following cancellation points are defined by the system (system-defined +cancellation points): \fBcreat\fR(2), \fBaio_suspend\fR(3C), \fBclose\fR(2), +\fBcreat\fR(2), \fBgetmsg\fR(2), \fBgetpmsg\fR(2), \fBlockf\fR(3C), +\fBmq_receive\fR(3C), \fBmq_send\fR(3C), \fBmsgrcv\fR(2), \fBmsgsnd\fR(2), +\fBmsync\fR(3C), \fBnanosleep\fR(3C), \fBopen\fR(2), \fBpause\fR(2), +\fBpoll\fR(2), \fBpread\fR(2), \fBpthread_cond_timedwait\fR(3C), +\fBpthread_cond_wait\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_testcancel\fR(3C), \fBputmsg\fR(2), \fBputpmsg\fR(2), +\fBpwrite\fR(2), \fBread\fR(2), \fBreadv\fR(2), \fBselect\fR(3C), +\fBsem_wait\fR(3C), \fBsigpause\fR(3C), \fBsigwaitinfo\fR(3C), +\fBsigsuspend\fR(2), \fBsigtimedwait\fR(3C), \fBsigwait\fR(2), \fBsleep\fR(3C), +\fBsync\fR(2), \fBsystem\fR(3C), \fBtcdrain\fR(3C), \fBusleep\fR(3C), +\fBwait\fR(3C), \fBwaitid\fR(2), \fBwait3\fR(3C), \fBwaitpid\fR(3C), +\fBwrite\fR(2), \fBwritev\fR(2), and \fBfcntl\fR(2), when specifying +\fBF_SETLKW\fR as the command. +.sp +.LP +When cancellation is asynchronous, cancellation can occur at any time (before, +during, or after the execution of the function defined as the cancellation +point). When cancellation is deferred (the default case), cancellation occurs +only within the scope of a function defined as a cancellation point (after the +function is called and before the function returns). See \fBCancellation +Type\fR for more information about deferred and asynchronous cancellation. +.sp +.LP +Choosing where to place cancellation points and understanding how cancellation +affects your program depend upon your understanding of both your application +and of cancellation mechanics. +.sp +.LP +Typically, any call that might require a long wait should be a cancellation +point. Operations need to check for pending cancellation requests when the +operation is about to block indefinitely. This includes threads waiting in +\fBpthread_cond_wait()\fR and \fBpthread_cond_timedwait()\fR, threads waiting +for the termination of another thread in \fBpthread_join()\fR, and threads +blocked on \fBsigwait()\fR. +.sp +.LP +A mutex is explicitly not a cancellation point and should be held for only the +minimal essential time. +.sp +.LP +Most of the dangers in performing cancellations deal with properly restoring +invariants and freeing shared resources. For example, a carelessly canceled +thread might leave a mutex in a locked state, leading to a deadlock. Or it +might leave a region of memory allocated with no way to identify it and +therefore no way to free it. +.SS "Cleanup Handlers" +.LP +When a thread is canceled, it should release resources and clean up the state +that is shared with other threads. So, whenever a thread that might be canceled +changes the state of the system or of the program, be sure to push a cleanup +handler with \fBpthread_cleanup_push\fR(3C) before the cancellation point. +.sp +.LP +When a thread is canceled, all the currently-stacked cleanup handlers are +executed in last-in-first-out (LIFO) order. Each handler is run in the scope in +which it was pushed. When the last cleanup handler returns, the thread-specific +data destructor functions are called. Thread execution terminates when the last +destructor function returns. +.sp +.LP +When, in the normal course of the program, an uncanceled thread restores state +that it had previously changed, be sure to pop the cleanup handler (that you +had set up where the change took place) using \fBpthread_cleanup_pop\fR(3C). +That way, if the thread is canceled later, only currently-changed state will be +restored by the handlers that are left in the stack. +.sp +.LP +The \fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR functions can +be implemented as macros. The application must ensure that they appear as +statements, and in pairs within the same lexical scope (that is, the +\fBpthread_cleanup_push()\fR macro can be thought to expand to a token list +whose first token is '{' with \fBpthread_cleanup_pop()\fR expanding to a token +list whose last token is the corresponding '}'). +.sp +.LP +The effect of the use of \fBreturn\fR, \fBbreak\fR, \fBcontinue\fR, and +\fBgoto\fR to prematurely leave a code block described by a pair of +\fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR function calls is +undefined. +.SS "Cancellation State" +.LP +Most programmers will use only the default cancellation state of +\fBPTHREAD_CANCEL_ENABLE\fR, but can choose to change the state by using +\fBpthread_setcancelstate\fR(3C), which determines whether a thread is +cancelable at all. With the default \fIstate\fR of +\fBPTHREAD_CANCEL_ENABLE\fR, cancellation is enabled and the thread is +cancelable at points determined by its cancellation \fItype\fR. See +\fBCancellation Type\fR. +.sp +.LP +If the \fIstate\fR is \fBPTHREAD_CANCEL_DISABLE\fR, cancellation is disabled, +the thread is not cancelable at any point, and all cancellation requests to it +are held pending. +.sp +.LP +You might want to disable cancellation before a call to a cancel-unsafe +library, restoring the old cancel state when the call returns from the library. +See \fBCancel-Safe\fR for explanations of cancel safety. +.SS "Cancellation Type" +.LP +A thread's cancellation \fBtype\fR is set with \fBpthread_setcanceltype\fR(3C), +and determines whether the thread can be canceled anywhere in its execution or +only at cancellation points. +.sp +.LP +With the default \fItype\fR of \fBPTHREAD_CANCEL_DEFERRED\fR, the thread is +cancelable only at cancellation points, and then only when cancellation is +enabled. +.sp +.LP +If the \fItype\fR is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR, the thread is +cancelable at any point in its execution (assuming, of course, that +cancellation is enabled). Try to limit regions of asynchronous cancellation to +sequences with no external dependencies that could result in dangling resources +or unresolved state conditions. Using asynchronous cancellation is discouraged +because of the danger involved in trying to guarantee correct cleanup handling +at absolutely every point in the program. +.sp + +.sp +.TS +box; +c | c | c +l | l | l . +Cancellation Type/State Table +Type State + Enabled (Default) Disabled +_ +Deferred (Default) T{ +Cancellation occurs when the target thread reaches a cancellation point and a cancel is pending. (Default) +T} T{ +All cancellation requests to the target thread are held pending. +T} +Asynchronous T{ +Receipt of a \fBpthread_cancel()\fR call causes immediate cancellation. +T} T{ +All cancellation requests to the target thread are held pending; as +soon as cancellation is re-enabled, pending cancellations are executed +immediately. +T} +.TE + +.SS "Cancel-Safe" +.LP +With the arrival of POSIX cancellation, the Cancel-Safe level has been added to +the list of MT-Safety levels. See \fBattributes\fR(7). An application or +library is Cancel-Safe whenever it has arranged for cleanup handlers to restore +system or program state wherever cancellation can occur. The application or +library is specifically Deferred-Cancel-Safe when it is Cancel-Safe for threads +whose cancellation type is \fBPTHREAD_CANCEL_DEFERRED\fR. See \fBCancellation +State\fR. It is specifically Asynchronous-Cancel-Safe when it is Cancel-Safe +for threads whose cancellation type is \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR. +.sp +.LP +It is easier to arrange for deferred cancel safety, as this requires system and +program state protection only around cancellation points. In general, expect +that most applications and libraries are not Asynchronous-Cancel-Safe. +.SS "POSIX Threads Only" +.LP +The cancellation functions described in this manual page are available for +POSIX threads, only (the Solaris threads interfaces do not provide cancellation +functions). +.SH EXAMPLES +.LP +\fBExample 1 \fRCancellation example +.sp +.LP +The following short C++ example shows the pushing/popping of cancellation +handlers, the disabling/enabling of cancellation, the use of +\fBpthread_testcancel()\fR, and so on. The \fBfree_res()\fR cancellation +handler in this example is a dummy function that simply prints a message, but +that would free resources in a real application. The function \fBf2()\fR is +called from the main thread, and goes deep into its call stack by calling +itself recursively. + +.sp +.LP +Before \fBf2()\fR starts running, the newly created thread has probably posted +a cancellation on the main thread since the main thread calls \fBthr_yield()\fR +right after creating thread2. Because cancellation was initially disabled in +the main thread, through a call to \fBpthread_setcancelstate()\fR, the call to +\fBf2()\fR from \fBmain()\fR continues and constructs X at each recursive +call, even though the main thread has a pending cancellation. + +.sp +.LP +When \fBf2()\fR is called for the fifty-first time (when \fB"i == 50"\fR), +\fBf2()\fR enables cancellation by calling \fBpthread_setcancelstate()\fR. It +then establishes a cancellation point for itself by calling +\fBpthread_testcancel()\fR. (Because a cancellation is pending, a call to a +cancellation point such as \fBread\fR(2) or \fBwrite\fR(2) would also cancel +the caller here.) + +.sp +.LP +After the \fBmain()\fR thread is canceled at the fifty-first iteration, all the +cleanup handlers that were pushed are called in sequence; this is indicated by +the calls to \fBfree_res()\fR and the calls to the destructor for \fIX\fR. At +each level, the C++ runtime calls the destructor for \fIX\fR and then the +cancellation handler, \fBfree_res()\fR. The print messages from +\fBfree_res()\fR and \fIX\fR's destructor show the sequence of calls. + +.sp +.LP +At the end, the main thread is joined by thread2. Because the main thread was +canceled, its return status from \fBpthread_join()\fR is +\fBPTHREAD_CANCELED\fR. After the status is printed, thread2 returns, killing +the process (since it is the last thread in the process). + +.sp +.in +2 +.nf +#include <pthread.h> +#include <sched.h> +extern "C" void thr_yield(void); + +extern "C" void printf(...); + +struct X { + int x; + X(int i){x = i; printf("X(%d) constructed.\en", i);} + ~X(){ printf("X(%d) destroyed.\en", x);} +}; + +void +free_res(void *i) +{ + printf("Freeing `%d`\en",i); +} + +char* f2(int i) +{ + try { + X dummy(i); + pthread_cleanup_push(free_res, (void *)i); + if (i == 50) { + pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); + pthread_testcancel(); + } + f2(i+1); + pthread_cleanup_pop(0); + } + catch (int) { + printf("Error: In handler.\en"); + } + return "f2"; +} + +void * +thread2(void *tid) +{ + void *sts; + + printf("I am new thread :%d\en", pthread_self()); + + pthread_cancel((pthread_t)tid); + + pthread_join((pthread_t)tid, &sts); + + printf("main thread cancelled due to %d\en", sts); + + return (sts); +} + +main() +{ + pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + pthread_create(NULL, NULL, thread2, (void *)pthread_self()); + thr_yield(); + printf("Returned from %s\en",f2(0)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO +.LP +.BR read (2), +.BR sigwait (2), +.BR write (2), +.BR Intro (3), +.BR pthread_cleanup_pop (3C), +.BR pthread_cleanup_push (3C), +.BR pthread_exit (3C), +.BR pthread_join (3C), +.BR pthread_setcancelstate (3C), +.BR pthread_setcanceltype (3C), +.BR pthread_testcancel (3C), +.BR setjmp (3C), +.BR attributes (7), +.BR condition (7), +.BR standards (7) diff --git a/usr/src/man/man7/charmap.7 b/usr/src/man/man7/charmap.7 new file mode 100644 index 0000000000..e4accf134d --- /dev/null +++ b/usr/src/man/man7/charmap.7 @@ -0,0 +1,362 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" +.TH CHARMAP 7 "Dec 1, 2003" +.SH NAME +charmap \- character set description file +.SH DESCRIPTION +.sp +.LP +A character set description file or \fIcharmap\fR defines characteristics for a +coded character set. Other information about the coded character set may also +be in the file. Coded character set character values are defined using symbolic +character names followed by character encoding values. +.sp +.LP +The character set description file provides: +.RS +4 +.TP +.ie t \(bu +.el o +The capability to describe character set attributes (such as collation order or +character classes) independent of character set encoding, and using only the +characters in the portable character set. This makes it possible to create +generic \fBlocaledef\fR(1) source files for all codesets that share the +portable character set. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Standardized symbolic names for all characters in the portable character set, +making it possible to refer to any such character regardless of encoding. +.RE +.SS "Symbolic Names" +.sp +.LP +Each symbolic name is included in the file and is mapped to a unique encoding +value (except for those symbolic names that are shown with identical glyphs). +If the control characters commonly associated with the symbolic names in the +following table are supported by the implementation, the symbolic names and +their corresponding encoding values are included in the file. Some of the +encodings associated with the symbolic names in this table may be the same as +characters in the portable character set table. +.sp + +.sp +.TS +box; +l l l l l l +l l l l l l . +<ACK> <DC2> <ENQ> <FS> <IS4> <SOH> +<BEL> <DC3> <EOT> <GS> <LF> <STX> +<BS> <DC4> <ESC> <HT> <NAK> <SUB> +<CAN> <DEL> <ETB> <IS1> <RS> <SYN> +<CR> <DLE> <ETX> <IS2> <SI> <US> +<DC1> <EM> <FF> <IS3> <SO> <VT> +.TE + +.SS "Declarations" +.sp +.LP +The following declarations can precede the character definitions. Each must +consist of the symbol shown in the following list, starting in column 1, +including the surrounding brackets, followed by one or more blank characters, +followed by the value to be assigned to the symbol. +.sp +.ne 2 +.na +\fB<\fIcode_set_name\fR>\fR +.ad +.RS 19n +The name of the coded character set for which the character set description +file is defined. +.RE + +.sp +.ne 2 +.na +\fB<\fImb_cur_max\fR>\fR +.ad +.RS 19n +The maximum number of bytes in a multi-byte character. This defaults to +\fB1\fR. +.RE + +.sp +.ne 2 +.na +\fB<\fImb_cur_min\fR>\fR +.ad +.RS 19n +An unsigned positive integer value that defines the minimum number of bytes in +a character for the encoded character set. +.RE + +.sp +.ne 2 +.na +\fB<\fIescape_char\fR>\fR +.ad +.RS 19n +The escape character used to indicate that the characters following will be +interpreted in a special way, as defined later in this section. This defaults +to backslash ('\fB\e\fR\&'), which is the character glyph used in all the +following text and examples, unless otherwise noted. +.RE + +.sp +.ne 2 +.na +\fB<\fIcomment_char\fR>\fR +.ad +.RS 19n +The character that when placed in column 1 of a charmap line, is used to +indicate that the line is to be ignored. The default character is the number +sign (#). +.RE + +.SS "Format" +.sp +.LP +The character set mapping definitions will be all the lines immediately +following an identifier line containing the string \fBCHARMAP\fR starting in +column 1, and preceding a trailer line containing the string \fBEND\fR +\fBCHARMAP\fR starting in column 1. Empty lines and lines containing a +\fI<comment_char>\fR in the first column will be ignored. Each non-comment line +of the character set mapping definition, that is, between the \fBCHARMAP\fR and +\fBEND CHARMAP\fR lines of the file), must be in either of two forms: +.sp +.in +2 +.nf +\fB"%s %s %s\en",\fR<\fIsymbolic-name\fR>,<\fIencoding\fR>,<\fIcomments\fR> +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +\fB"%s...%s %s %s\en",\fR<\fIsymbolic-name\fR>,<\fIsymbolic-name\fR>, <\fIencoding\fR>,\e + <\fIcomments\fR> +.fi +.in -2 + +.sp +.LP +In the first format, the line in the character set mapping definition defines a +single symbolic name and a corresponding encoding. A character following an +escape character is interpreted as itself; for example, the sequence +"<\fB\e\e\e\fR>>" represents the symbolic name "\fI\e>\fR" enclosed between +angle brackets. +.sp +.LP +In the second format, the line in the character set mapping definition defines +a range of one or more symbolic names. In this form, the symbolic names must +consist of zero or more non-numeric characters, followed by an integer formed +by one or more decimal digits. The characters preceding the integer must be +identical in the two symbolic names, and the integer formed by the digits in +the second symbolic name must be equal to or greater than the integer formed by +the digits in the first name. This is interpreted as a series of symbolic names +formed from the common part and each of the integers between the first and the +second integer, inclusive. As an example, \fB<j0101>...<j0104>\fR is +interpreted as the symbolic names \fB<j0101>\fR, \fB<j0102>\fR, \fB<j0103>\fR, +and \fB<j0104>\fR, in that order. +.sp +.LP +A character set mapping definition line must exist for all symbolic names and +must define the coded character value that corresponds to the character glyph +indicated in the table, or the coded character value that corresponds with the +control character symbolic name. If the control characters commonly associated +with the symbolic names are supported by the implementation, the symbolic name +and the corresponding encoding value must be included in the file. Additional +unique symbolic names may be included. A coded character value can be +represented by more than one symbolic name. +.sp +.LP +The encoding part is expressed as one (for single-byte character values) or +more concatenated decimal, octal or hexadecimal constants in the following +formats: +.sp +.in +2 +.nf +\fB"%cd%d",\fR<\fIescape_char\fR>,<\fIdecimal byte value\fR> + +\fB"%cx%x",\fR<\fIescape_char\fR>,<\fIhexadecimal byte value\fR> + +\fB"%c%o",\fR<\fIescape_char\fR>,<\fIoctal byte value\fR> +.fi +.in -2 + +.SS "Decimal Constants" +.sp +.LP +Decimal constants must be represented by two or three decimal digits, preceded +by the escape character and the lower-case letter \fBd\fR; for example, +\fB\ed05\fR, \fB\ed97\fR, or \fB\ed143\fR\&. Hexadecimal constants must be +represented by two hexadecimal digits, preceded by the escape character and the +lower-case letter \fBx\fR; for example, \fB\ex05\fR, \fB\ex61\fR, or +\fB\ex8f\fR\&. Octal constants must be represented by two or three octal +digits, preceded by the escape character; for example, \fB\e05\fR, \fB\e141\fR, +or \fB\e217\fR\&. In a portable charmap file, each constant must represent an +8-bit byte. Implementations supporting other byte sizes may allow constants to +represent values larger than those that can be represented in 8-bit bytes, and +to allow additional digits in constants. When constants are concatenated for +multi-byte character values, they must be of the same type, and interpreted in +byte order from first to last with the least significant byte of the multi-byte +character specified by the last constant. +.SS "Ranges of Symbolic Names" +.sp +.LP +In lines defining ranges of symbolic names, the encoded value is the value for +the first symbolic name in the range (the symbolic name preceding the +ellipsis). Subsequent symbolic names defined by the range will have encoding +values in increasing order. Bytes are treated as unsigned octets and carry is +propagated between the bytes as necessary to represent the range. However, +because this causes a null byte in the second or subsequent bytes of a +character, such a declaration should not be specified. For example, the line +.sp +.in +2 +.nf +<j0101>...<j0104> \ed129\ed254 +.fi +.in -2 + +.sp +.LP +is interpreted as: +.sp +.in +2 +.nf +<j0101> \ed129\ed254 +<j0102> \ed129\ed255 +<j0103> \ed130\ed00 +<j0104> \ed130\ed01 +.fi +.in -2 + +.sp +.LP +The expanded declaration of the symbol \fB<j0103>\fR in the above example is an +invalid specification, because it contains a null byte in the second byte of a +character. +.sp +.LP +The comment is optional. +.SS "Width Specification" +.sp +.LP +The following declarations can follow the character set mapping definitions +(after the "\fBEND CHARMAP\fR" statement). Each consists of the keyword shown +in the following list, starting in column 1, followed by the value(s) to be +associated to the keyword, as defined below. +.sp +.ne 2 +.na +\fB\fBWIDTH\fR\fR +.ad +.RS 17n +A non-negative integer value defining the column width for the printable +character in the coded character set mapping definitions. Coded character set +character values are defined using symbolic character names followed by column +width values. Defining a character with more than one \fBWIDTH\fR produces +undefined results. The \fBEND WIDTH\fR keyword is used to terminate the +\fBWIDTH\fR definitions. Specifying the width of a non-printable character in a +\fBWIDTH\fR declaration produces undefined results. +.RE + +.sp +.ne 2 +.na +\fB\fBWIDTH_DEFAULT\fR\fR +.ad +.RS 17n +A non-negative integer value defining the default column width for any +printable character not listed by one of the \fBWIDTH\fR keywords. If no +\fBWIDTH_DEFAULT\fR keyword is included in the charmap, the default character +width is \fB1\fR. +.RE + +.sp +.LP +Example: +.sp +.LP +After the "\fBEND CHARMAP\fR" statement, a syntax for a width definition would +be: +.sp +.in +2 +.nf +WIDTH +<A> 1 +<B> 1 +<C>...<Z> 1 +\&... +<fool>...<foon> 2 +\&... +END WIDTH +.fi +.in -2 +.sp + +.sp +.LP +In this example, the numerical code point values represented by the symbols +\fB<A>\fR and \fB<B>\fR are assigned a width of \fB1\fR. The code point values +\fB< C>\fR to \fB<Z>\fR inclusive, that is, \fB<C>\fR, \fB<D>\fR, \fB<E>\fR, +and so on, are also assigned a width of \fB1\fR. Using \fB<A>...<Z>\fR would +have required fewer lines, but the alternative was shown to demonstrate +flexibility. The keyword \fBWIDTH_DEFAULT\fR could have been added as +appropriate. +.SH SEE ALSO +.sp +.LP +.BR locale (1), +.BR localedef (1), +.BR nl_langinfo (3C), +.BR extensions (7), +.BR locale (7) diff --git a/usr/src/man/man7/check-password.4th.7 b/usr/src/man/man7/check-password.4th.7 new file mode 100644 index 0000000000..fd165cb29a --- /dev/null +++ b/usr/src/man/man7/check-password.4th.7 @@ -0,0 +1,130 @@ +.\" Copyright (c) 2011-2015 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt CHECK-PASSWORD.4TH 7 +.Os +.Sh NAME +.Nm check-password.4th +.Nd loader password-checking boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to do one or more of the following: +.Pp +.Dl o Prevent booting without password +.Dl o Prevent modification of boot options without password +.Pp +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include check-password.4th +.Pp +This line is present in +.Pa /boot/forth/loader.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic check-password +Multi-purpose function that can protect the interactive boot menu, +prevent boot without password +.Pq depending on Xr loader.conf 5 settings . +.Pp +First checks +.Va bootlock_password +and if-set, the user cannot continue until the correct password is entered. +.Pp +Last, checks +.Va password +and if-set, tries to +.Ic autoboot +and only prompts for password on failure or user-interrupt. +See +.Xr loader.conf 5 +for additional information. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootlock_password -offset indent +.It Va bootlock_password +Sets the bootlock password (up to 16 characters long) that is required by +.Ic check-password +to be entered before the system is allowed to boot. +.It Va password +Sets the password (up to 16 characters long) that is required by +.Ic check-password +before the user is allowed to visit the boot menu. +.El +.Sh FILES +.Bl -tag -width /boot/forth/check-password.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/check-password.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +Standard i386 +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/loader.4th +check-password +.Ed +.Pp +Set a password in +.Xr loader.conf 5 +to prevent modification of boot options: +.Pp +.Bd -literal -offset indent -compact +password="abc123" +.Ed +.Pp +Set a password in +.Xr loader.conf 5 +to prevent booting without password: +.Pp +.Bd -literal -offset indent -compact +bootlock_password="boot" +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr loader 7 , +.Xr loader.4th 7 diff --git a/usr/src/man/man7/color.4th.7 b/usr/src/man/man7/color.4th.7 new file mode 100644 index 0000000000..e3884d170d --- /dev/null +++ b/usr/src/man/man7/color.4th.7 @@ -0,0 +1,103 @@ +.\" Copyright (c) 2011-2013 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt COLOR.4TH 7 +.Os +.Sh NAME +.Nm color.4th +.Nd loader color-detection boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to simplify color logic. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include color.4th +.Pp +This line is present in +.Pa /boot/forth/loader.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic loader_color? +Returns FALSE if the +.Ic loader_color +environment variable is set to +.Dq NO +(case-insensitive) or +.Dq 0 . +Otherwise returns TRUE +.Pq unless booting serial . +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_color +If set to +.Dq NO +(case-insensitive) or +.Dq 0 , +causes +.Ic loader_color? +to return FALSE, indicating to many modules that color should not be used. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/color.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +Standard i386 +.Pa /boot/loader.conf : +.Pp +Use color where applicable: +.Pp +.Bd -literal -offset indent -compact +loader_color="YES" +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr loader 7 , +.Xr loader.4th 7 diff --git a/usr/src/man/man7/condition.7 b/usr/src/man/man7/condition.7 new file mode 100644 index 0000000000..017ffbbeb5 --- /dev/null +++ b/usr/src/man/man7/condition.7 @@ -0,0 +1,154 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. +.\" +.TH CONDITION 7 "May 16, 2020" +.SH NAME +condition \- concepts related to condition variables +.SH DESCRIPTION +Occasionally, a thread running within a mutex needs to wait for an event, in +which case it blocks or sleeps. When a thread is waiting for another thread to +communicate its disposition, it uses a condition variable in conjunction with a +mutex. Although a mutex is exclusive and the code it protects is sharable (at +certain moments), condition variables enable the synchronization of differing +events that share a mutex, but not necessarily data. Several condition +variables may be used by threads to signal each other when a task is complete, +which then allows the next waiting thread to take ownership of the mutex. +.sp +.LP +A condition variable enables threads to atomically block and test the condition +under the protection of a mutual exclusion lock (mutex) until the condition is +satisfied. If the condition is false, a thread blocks on a condition variable +and atomically releases the mutex that is waiting for the condition to change. +If another thread changes the condition, it may wake up waiting threads by +signaling the associated condition variable. The waiting threads, upon +awakening, reacquire the mutex and re-evaluate the condition. +.SS "Initialize" +Condition variables and mutexes should be global. Condition variables that are +allocated in writable memory can synchronize threads among processes if they +are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized +for this purpose. +.sp +.LP +The scope of a condition variable is either intra-process or inter-process. +This is dependent upon whether the argument is passed implicitly or explicitly +to the initialization of that condition variable. A condition variable does +not need to be explicitly initialized. A condition variable is initialized with +all zeros, by default, and its scope is set to within the calling process. For +inter-process synchronization, a condition variable must be initialized once, +and only once, before use. +.sp +.LP +A condition variable must not be simultaneously initialized by multiple threads +or re-initialized while in use by other threads. +.sp +.LP +Condition variables attributes may be set to the default or customized at +initialization. POSIX threads even allow the default values to be customized. +Establishing these attributes varies depending upon whether POSIX or Solaris +threads are used. Similar to the distinctions between POSIX and Solaris thread +creation, POSIX condition variables implement the default, intra-process, +unless an attribute object is modified for inter-process prior to the +initialization of the condition variable. Solaris condition variables also +implement as the default, intra-process; however, they set this attribute +according to the argument, \fItype\fR, passed to their initialization function. +.SS "Condition Wait" +The condition wait interface allows a thread to wait for a condition and +atomically release the associated mutex that it needs to hold to check the +condition. The thread waits for another thread to make the condition true and +that thread's resulting call to signal and wakeup the waiting thread. +.SS "Condition Signaling" +A condition signal allows a thread to unblock the next thread waiting on the +condition variable, whereas, a condition broadcast allows a thread to unblock +all threads waiting on the condition variable. +.SS "Destroy" +The condition destroy functions destroy any state, but not the space, +associated with the condition variable. +.SH ATTRIBUTES +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO +.BR fork (2), +.BR mmap (2), +.BR setitimer (2), +.BR shmop (2), +.BR cond_broadcast (3C), +.BR cond_destroy (3C), +.BR cond_init (3C), +.BR cond_signal (3C), +.BR cond_timedwait (3C), +.BR cond_wait (3C), +.BR pthread_cond_broadcast (3C), +.BR pthread_cond_destroy (3C), +.BR pthread_cond_init (3C), +.BR pthread_cond_signal (3C), +.BR pthread_cond_timedwait (3C), +.BR pthread_cond_wait (3C), +.BR pthread_condattr_init (3C), +.BR signal (3C), +.BR attributes (7), +.BR mutex (7), +.BR standards (7) +.SH NOTES +If more than one thread is blocked on a condition variable, the order in which +threads are unblocked is determined by the scheduling policy. +.sp +.LP +\fBUSYNC_THREAD\fR does not support multiple mappings to the same logical +synch object. If you need to \fBmmap()\fR a synch object to different locations +within the same address space, then the synch object should be initialized as a +shared object \fBUSYNC_PROCESS\fR for Solaris, and +\fBPTHREAD_PROCESS_PRIVATE\fR for POSIX. diff --git a/usr/src/man/man7/cpr.7 b/usr/src/man/man7/cpr.7 deleted file mode 100644 index 5faeaa68f2..0000000000 --- a/usr/src/man/man7/cpr.7 +++ /dev/null @@ -1,114 +0,0 @@ -.\" Copyright (c) 2001, Sun Microsystems, Inc. -.\" All Rights Reserved -.\" -.\" Copyright 2020 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] -.\" -.Dd January 12, 2020 -.Dt CPR 7 -.Os -.Sh NAME -.Nm cpr -.Nd Suspend and resume module -.Sh SYNOPSIS -.Pa /platform/i86pc/kernel/misc/amd64/cpr -.Pa /platform/sun4u/kernel/misc/sparcv9/cpr -.Sh DESCRIPTION -The -.Nm -module is a loadable module used to suspend and resume the entire system. -You may wish to suspend a system to save power or to power off -temporarily for transport. -The -.Nm -module should not be used in place of -a normal shutdown when performing any hardware reconfiguration or replacement. -In order for the resume operation to succeed, it is important that the hardware -configuration remain the same. -When the system is suspended, the entire system -state is preserved in non-volatile storage until a resume operation is -conducted. -.Pp -.Xr pmconfig 1M -and -.Xr power.conf 4 -are used to configure the suspend-resume feature. -.Pp -The speed of suspend and resume operations can range from 15 seconds to -several minutes, depending on the system speed, memory size, and load. -.Pp -During resume operation, the -.Dv SIGTHAW -signal is sent to all processes to -allow them to do any special processing in response to suspend-resume -operation. -Normally applications are not required to do any special processing -because of suspend-resume, but some specialized processes can use -.Dv SIGTHAW -to restore the state prior to suspend. -For example, -.Sy X -can refresh the screen in response to -.Dv SIGTHAW . -.Pp -In some cases the -.Nm -module may be unable to perform the suspend operation. -If a system contains additional devices outside the standard shipped -configuration, it is possible that device drivers for these additional devices -might not support suspend-resume operations. -In this case, the suspend fails and an error message is displayed. -These devices must be removed or their -device drivers unloaded for the suspend operation to succeed. -Contact the -device manufacturer to obtain a new version of device driver that supports -suspend-resume. -.Pp -A suspend may also fail when devices or processes are performing critical or -time-sensitive operations (such as realtime operations). -The system will remain in its current running state. -Messages reporting the failure will be displayed -on the console and status returned to the caller. -Once the system is -successfully suspended the resume operation will succeed, barring external -influences such as a hardware reconfiguration. -.Pp -Some network-based applications may fail across a suspend and resume cycle. -This largely depends on the underlying network protocol and the applications -involved. -In general, applications that retry and automatically reestablish -connections will continue to operate transparently on a resume operation; -those applications that do not will likely fail. -.Sh INTERFACE STABILITY -Unstable -.Sh SEE ALSO -.Xr pmconfig 1M , -.Xr uadmin 1M , -.Xr uadmin 2 , -.Xr power.conf 4 , -.Xr attributes 5 -.Pp -.%T Writing Device Drivers -.Sh NOTES -Certain device operations such as tape and floppy disk activities are not -resumable due to the nature of removable media. -These activities are detected -at suspend time, and must be stopped before the suspend operation will -complete successfully. -.Pp -Suspend-resume is currently supported only on a limited set of hardware -platforms. diff --git a/usr/src/man/man7/crypt_bsdbf.7 b/usr/src/man/man7/crypt_bsdbf.7 new file mode 100644 index 0000000000..7e4ca9f966 --- /dev/null +++ b/usr/src/man/man7/crypt_bsdbf.7 @@ -0,0 +1,52 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH CRYPT_BSDBF 7 "Sep 13, 2009" +.SH NAME +crypt_bsdbf \- password hashing module using Blowfish cryptographic algorithm +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/$ISA/crypt_bsdbf.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_bsdbf\fR module is a one-way password hashing module for use with +\fBcrypt\fR(3C) that uses the Blowfish cryptographic algorithm. The algorithm +identifier for \fBcrypt.conf\fR(5) and \fBpolicy.conf\fR(5) is \fB2a\fR. +.sp +.LP +The maximum password length for \fBcrypt_bsdbf\fR is 72 characters. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR crypt (3C), +.BR crypt_genhash_impl (3C), +.BR crypt_gensalt (3C), +.BR crypt_gensalt_impl (3C), +.BR getpassphrase (3C), +.BR crypt.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR attributes (7) diff --git a/usr/src/man/man7/crypt_bsdmd5.7 b/usr/src/man/man7/crypt_bsdmd5.7 new file mode 100644 index 0000000000..7785e6e691 --- /dev/null +++ b/usr/src/man/man7/crypt_bsdmd5.7 @@ -0,0 +1,53 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH CRYPT_BSDMD5 7 "Aug 6, 2003" +.SH NAME +crypt_bsdmd5 \- password hashing module using MD5 message hash algorithm +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/$ISA/crypt_bsdmd5.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_bsdmd5\fR module is a one-way password hashing module for use with +\fBcrypt\fR(3C) that uses the MD5 message hash algorithm. The algorithm +identifier for \fBcrypt.conf\fR(5) and \fBpolicy.conf\fR(5) is \fB1\fR. The +output is compatible with \fBmd5crypt\fR on BSD and Linux systems. +.sp +.LP +The maximum password length for \fBcrypt_bsdmd5\fR is 255 characters. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR crypt (3C), +.BR crypt_genhash_impl (3C), +.BR crypt_gensalt (3C), +.BR crypt_gensalt_impl (3C), +.BR getpassphrase (3C), +.BR crypt.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR attributes (7) diff --git a/usr/src/man/man7/crypt_sha256.7 b/usr/src/man/man7/crypt_sha256.7 new file mode 100644 index 0000000000..a5637642ff --- /dev/null +++ b/usr/src/man/man7/crypt_sha256.7 @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH CRYPT_SHA256 7 "May 8, 2008" +.SH NAME +crypt_sha256 \- password hashing module using SHA-256 message hash algorithm +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/$ISA/crypt_sha256.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_sha256\fR module is a one-way password hashing module for use with +\fBcrypt\fR(3C) that uses the SHA-256 message hash algorithm. The algorithm +identifier for \fBcrypt.conf\fR(5) and \fBpolicy.conf\fR(5) is \fB5\fR. +.sp +.LP +This module is designed to make it difficult to crack passwords that use brute +force attacks based on high speed SHA-256 implementations that use code +inlining, unrolled loops, and table lookup. +.sp +.LP +The maximum password length for \fBcrypt_sha256\fR is 255 characters. +.sp +.LP +The following options can be passed to the module by means of +\fBcrypt.conf\fR(5): +.sp +.ne 2 +.na +\fB\fBrounds=\fR\fI<positive_number>\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the number of rounds of SHA-256 to use in generation of the salt; the +default number of rounds is 5000. Negative values have no effect and are +ignored. The minimum number of rounds cannot be below 1000. +.sp +The number of additional rounds is stored in the salt string returned by +\fBcrypt_gensalt\fR(3C). For example: +.sp +.in +2 +.nf +$5,rounds=6000$nlxmTTpz$ +.fi +.in -2 + +When \fBcrypt_gensalt\fR(3C) is being used to generate a new salt, if the +number of additional rounds configured in \fBcrypt.conf\fR(5) is greater than +that in the old salt, the value from \fBcrypt.conf\fR(5) is used instead. This +allows for migration to stronger (but more time-consuming) salts on password +change. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR crypt (3C), +.BR crypt_genhash_impl (3C), +.BR crypt_gensalt (3C), +.BR crypt_gensalt_impl (3C), +.BR getpassphrase (3C), +.BR crypt.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR attributes (7) diff --git a/usr/src/man/man7/crypt_sha512.7 b/usr/src/man/man7/crypt_sha512.7 new file mode 100644 index 0000000000..1d8e968d4e --- /dev/null +++ b/usr/src/man/man7/crypt_sha512.7 @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH CRYPT_SHA512 7 "May 8, 2008" +.SH NAME +crypt_sha512 \- password hashing module using SHA-512 message hash algorithm +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/$ISA/crypt_sha512.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_sha512\fR module is a one-way password hashing module for use with +\fBcrypt\fR(3C) that uses the SHA-512 message hash algorithm. The algorithm +identifier for \fBcrypt.conf\fR(5) and \fBpolicy.conf\fR(5) is \fB6\fR. +.sp +.LP +This module is designed to make it difficult to crack passwords that use brute +force attacks based on high speed SHA-512 implementations that use code +inlining, unrolled loops, and table lookup. +.sp +.LP +The maximum password length for \fBcrypt_sha512\fR is 255 characters. +.sp +.LP +The following options can be passed to the module by means of +\fBcrypt.conf\fR(5): +.sp +.ne 2 +.na +\fB\fBrounds=\fR\fI<positive_number>\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the number of rounds of SHA-512 to use in generation of the salt; the +default number of rounds is 5000. Negative values have no effect and are +ignored. The minimum number of rounds cannot be below 1000. +.sp +The number of additional rounds is stored in the salt string returned by +\fBcrypt_gensalt\fR(3C). For example: +.sp +.in +2 +.nf +$6,rounds=6000$nlxmTTpz$ +.fi +.in -2 + +When \fBcrypt_gensalt\fR(3C) is being used to generate a new salt, if the +number of additional rounds configured in \fBcrypt.conf\fR(5) is greater than +that in the old salt, the value from \fBcrypt.conf\fR(5) is used instead. This +allows for migration to stronger (but more time-consuming) salts on password +change. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR crypt (3C), +.BR crypt_genhash_impl (3C), +.BR crypt_gensalt (3C), +.BR crypt_gensalt_impl (3C), +.BR getpassphrase (3C), +.BR crypt.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR attributes (7) diff --git a/usr/src/man/man7/crypt_sunmd5.7 b/usr/src/man/man7/crypt_sunmd5.7 new file mode 100644 index 0000000000..81737179b0 --- /dev/null +++ b/usr/src/man/man7/crypt_sunmd5.7 @@ -0,0 +1,87 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH CRYPT_SUNMD5 7 "Dec 23, 2003" +.SH NAME +crypt_sunmd5 \- password hashing module using MD5 message hash algorithm +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/$ISA/crypt_sunmd5.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_sunmd5\fR module is a one-way password hashing module for use with +\fBcrypt\fR(3C) that uses the MD5 message hash algorithm. The algorithm +identifier for \fBcrypt.conf\fR(5) and \fBpolicy.conf\fR(5) is \fBmd5\fR. +.sp +.LP +This module is designed to make it difficult to crack passwords that use brute +force attacks based on high speed MD5 implementations that use code inlining, +unrolled loops, and table lookup. +.sp +.LP +The maximum password length for \fBcrypt_sunmd5\fR is 255 characters. +.sp +.LP +The following options can be passed to the module by means of +\fBcrypt.conf\fR(5): +.sp +.ne 2 +.na +\fB\fBrounds=\fR\fI<positive_number>\fR\fR +.ad +.RS 28n +Specifies the number of additional rounds of MD5 to use in generation of the +salt; the default number of rounds is 4096. Negative values have no effect and +are ignored, that is, the number of rounds cannot be lowered below 4096. +.sp +The number of additional rounds is stored in the salt string returned by +\fBcrypt_gensalt\fR(3C). For example: +.sp +.in +2 +.nf +$md5,rounds=1000$nlxmTTpz$ +.fi +.in -2 + +When \fBcrypt_gensalt\fR(3C) is being used to generate a new salt, if the +number of additional rounds configured in \fBcrypt.conf\fR(5) is greater than +that in the old salt, the value from \fBcrypt.conf\fR(5) is used instead. This +allows for migration to stronger (but more time-consuming) salts on password +change. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR crypt (3C), +.BR crypt_genhash_impl (3C), +.BR crypt_gensalt (3C), +.BR crypt_gensalt_impl (3C), +.BR getpassphrase (3C), +.BR crypt.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR attributes (7) diff --git a/usr/src/man/man7/crypt_unix.7 b/usr/src/man/man7/crypt_unix.7 new file mode 100644 index 0000000000..299840cf82 --- /dev/null +++ b/usr/src/man/man7/crypt_unix.7 @@ -0,0 +1,73 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH CRYPT_UNIX 7 "Aug 6, 2003" +.SH NAME +crypt_unix \- traditional UNIX crypt algorithm +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_unix\fR algorithm is the traditional UNIX crypt algorithm. It is +not considered sufficiently secure for current systems and is provided for +backwards compatibility. The \fBcrypt_sunmd5\fR(7), \fBcrypt_bsdmd5\fR(7), or +\fBcrypt_bsdbf\fR(7) algorithm should be used instead. +.sp +.LP +The algorithm identifier for \fBpolicy.conf\fR(5) is \fB__unix__\fR. There is +no entry in \fBcrypt.conf\fR(5) for this algorithm. +.sp +.LP +The \fBcrypt_unix\fR algorithm is internal to \fBlibc\fR and provides the +string encoding function used by \fBcrypt\fR(3C) when the first character of +the salt is not a "$". +.sp +.LP +This algorithm is based on a one-way encryption algorithm with variations +intended (among other things) to frustrate use of hardware implementations of a +key search. Only the first eight characters of the key passed to \fBcrypt()\fR +are used with this algorithm; the rest are silently ignored. The salt is a +two-character string chosen from the set [a-zA-Z0-9./]. This string is used to +perturb the hashing algorithm in one of 4096 different ways. +.sp +.LP +The maximum password length for \fBcrypt_unix\fR is 8 characters. +.SH USAGE +.sp +.LP +The return value of the \fBcrypt_unix\fR algorithm might not be portable among +standard-conforming systems. See \fBstandards\fR(7). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR crypt (3C), +.BR crypt_genhash_impl (3C), +.BR crypt_gensalt (3C), +.BR crypt_gensalt_impl (3C), +.BR getpassphrase (3C), +.BR crypt.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR attributes (7), +.BR crypt_bsdbf (7), +.BR crypt_bsdmd5 (7), +.BR crypt_sunmd5 (7), +.BR standards (7) diff --git a/usr/src/man/man7/delay.4th.7 b/usr/src/man/man7/delay.4th.7 new file mode 100644 index 0000000000..16729e01b4 --- /dev/null +++ b/usr/src/man/man7/delay.4th.7 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2011 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt DELAY.4TH 7 +.Os +.Sh NAME +.Nm delay.4th +.Nd loader debugging boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to add debugging capabilities to +.Xr loader 7 . +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include delay.4th +.Pp +This line is present in +.Pa /boot/forth/beastie.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic delay_execute +Executes the [string] procedure stored in the +.Ic delay_command +environment variable after +.Ic loader_delay +seconds. +.Pp +If the optional +.Ic delay_showdots +environment variable is set, a continuous series of dots is printed. +.Pp +During the duration, the user can either press Ctrl-C (or Esc) to abort or +ENTER to proceed immediately. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va delay_command +The command to be executed by +.Ic delay_execute . +.It Va loader_delay +The duration (in seconds) to delay before executing +.Ic delay_command . +.It Va delay_showdots +If set, will cause +.Ic delay_execute +to print a continuous series of dots during the delay duration. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/delay.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +Introducing a 5-second delay before including another file from +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/delay.4th +set delay_command="include /boot/forth/other.4th" +set delay_showdots +set loader_delay=5 +delay_execute +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr beastie.4th 7 , +.Xr loader 7 , +.Xr loader.4th 7 diff --git a/usr/src/man/man7/device_clean.7 b/usr/src/man/man7/device_clean.7 new file mode 100644 index 0000000000..9157841c2b --- /dev/null +++ b/usr/src/man/man7/device_clean.7 @@ -0,0 +1,308 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH DEVICE_CLEAN 7 "Jun 14, 2007" +.SH NAME +device_clean \- device clean programs +.SH DESCRIPTION +.sp +.LP +Each allocatable device has a device clean program associated with it. Device +clean programs are invoked by \fBdeallocate\fR(1) to clean device states, +registers, and any residual information in the device before the device is +allocated to a user. Such cleaning is required by the object reuse policy. +.sp +.LP +Use \fBlist_devices\fR(1) to obtain the names and types of allocatable devices +as well as the cleaning program and the authorizations that are associated with +each device. +.sp +.LP +On a system configured with Trusted Extensions, device clean programs are also +invoked by \fBallocate\fR(1), in which case the program can optionally mount +appropriate media for the caller. +.sp +.LP +The following device clean programs reside in \fB/etc/security/lib\fR. +.sp +.ne 2 +.na +\fB\fBaudio_clean\fR\fR +.ad +.RS 15n +audio devices +.RE + +.sp +.ne 2 +.na +\fB\fBfd_clean\fR\fR +.ad +.RS 15n +floppy devices +.RE + +.sp +.ne 2 +.na +\fB\fBst_clean\fR\fR +.ad +.RS 15n +tape devices +.RE + +.sp +.ne 2 +.na +\fB\fBsr_clean\fR\fR +.ad +.RS 15n +CD-ROM devices +.RE + +.sp +.LP +On a system configured with Trusted Extensions, the following additional +cleaning programs and wrappers are available. +.sp +.ne 2 +.na +\fB\fBdisk_clean\fR\fR +.ad +.RS 23n +floppy, CD-ROM, and other removable media devices. This program mounts the +device during the execution of \fBallocate\fR, if required. +.RE + +.sp +.ne 2 +.na +\fB\fBaudio_clean_wrapper\fR\fR +.ad +.RS 23n +wrapper to make audio_clean work with CDE +.RE + +.sp +.ne 2 +.na +\fB\fBwdwwrapper\fR\fR +.ad +.RS 23n +wrapper to make other cleaning programs work with CDE +.RE + +.sp +.ne 2 +.na +\fB\fBwdwmsg\fR\fR +.ad +.RS 23n +CDE dialog boxes for cleaning programs +.RE + +.sp +.LP +Administrators can create device clean programs for their sites. These programs +must adhere to the syntax described below. +.sp +.in +2 +.nf +/etc/security/lib/\fIdevice-clean-program\fR [\(mii | \(mif | \(mis | \(miI] \e +\(mim \fImode\fR \(miu \fIuser-name\fR \(miz \fIzone-name\fR \(mip \fIzone-path\fR \fIdevice-name\fR +.fi +.in -2 +.sp + +.sp +.LP +where: +.sp +.ne 2 +.na +\fB\fIdevice-name\fR\fR +.ad +.RS 15n +The name of the device that is to be cleaned. Use \fBlist_devices\fR to obtain +the list of allocatable devices. +.RE + +.sp +.ne 2 +.na +\fB\fB-i\fR\fR +.ad +.RS 15n +Invoke boot-time initialization. +.RE + +.sp +.ne 2 +.na +\fB\fB-f\fR\fR +.ad +.RS 15n +Force cleanup by the administrator. +.RE + +.sp +.ne 2 +.na +\fB\fB-s\fR\fR +.ad +.RS 15n +Invoke standard cleanup by the user. +.RE + +.sp +.ne 2 +.na +\fB\fB-I\fR\fR +.ad +.RS 15n +Same as \fB-i\fR, with no error or warning. +.RE + +.sp +.LP +The following options are supported only when the system is configured with +Trusted Extensions. +.sp +.ne 2 +.na +\fB\fB-m\fR \fImode\fR\fR +.ad +.RS 16n +Specify the mode in which the clean program is invoked. Valid values are allo- +cate and deallocate. The default mode is allocate. +.RE + +.sp +.ne 2 +.na +\fB\fB-u\fR \fIuser-name\fR\fR +.ad +.RS 16n +Specify the name of user who executes the device clean program. The default +user is the caller. +.RE + +.sp +.ne 2 +.na +\fB\fB-z\fR \fIzone-name\fR\fR +.ad +.RS 16n +Specify the name of the zone in which the device is to be allocated or +deallocated. The default zone is the global zone. +.RE + +.sp +.ne 2 +.na +\fB\fB-p\fR \fIzone-path\fR\fR +.ad +.RS 16n +Establish the root path of the zone that is specified by \fIzone-name\fR. +Default is "/". +.RE + +.SH EXIT STATUS +.sp +.LP +The following exit values are returned: +.sp +.ne 2 +.na +\fB\fB0\fR\fR +.ad +.sp .6 +.RS 4n +Successful completion. +.RE + +.sp +.ne 2 +.na +\fB\fB1\fR\fR +.ad +.sp .6 +.RS 4n +An error. Caller can place device in error state. +.RE + +.sp +.ne 2 +.na +\fB\fB2\fR\fR +.ad +.sp .6 +.RS 4n +A system error. Caller can place device in error state. +.RE + +.sp +.LP +On a system configured with Trusted Extensions, the following additional exit +values are returned: +.sp +.ne 2 +.na +\fB\fB3\fR\fR +.ad +.sp .6 +.RS 4n +Mounting of device failed. Caller shall not place device in error state. +.RE + +.sp +.ne 2 +.na +\fB\fB4\fR\fR +.ad +.sp .6 +.RS 4n +Mounting of device succeeded. +.RE + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/etc/security/lib/*\fR\fR +.ad +.RS 23n +device clean programs +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) 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 +The Invocation is Uncommitted. The Output is Not-an-interface. +.SH SEE ALSO +.sp +.LP +.BR allocate (1), +.BR deallocate (1), +.BR list_devices (1), +.BR attributes (7) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man7/dhcp.7 b/usr/src/man/man7/dhcp.7 new file mode 100644 index 0000000000..67349a29d0 --- /dev/null +++ b/usr/src/man/man7/dhcp.7 @@ -0,0 +1,67 @@ +'\" te +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH DHCP 7 "Feb 13, 2020" +.SH NAME +dhcp \- Dynamic Host Configuration Protocol +.SH DESCRIPTION +Dynamic Host Configuration Protocol (\fBDHCP\fR) enables host systems in a +\fBTCP/IP\fR network to be configured automatically for the network as they +boot. \fBDHCP\fR uses a client/server mechanism: servers store configuration +information for clients, and provide that information upon a client's request. +The information can include the client's \fBIP\fR address and information about +network services available to the client. +.LP +This manual page provides a brief summary of the \fBDHCP\fR +implementation. +.SS "DHCP Client" +The DHCP client is implemented as background daemon, +\fBdhcpagent\fR(8). +.LP +For IPv4, this daemon is started automatically during bootup if there exists at +least one \fBdhcp.\fR\fIinterface\fR file in \fB/etc\fR. Only interfaces with a +corresponding \fB\fR\fB/etc/dhcp.\fR\fB\fIinterface\fR\fR file are +automatically configured during boot. +.LP +For IPv6, this daemon is started automatically when commanded by \fBin.ndpd\fR +(based on IPv6 Routing Advertisement messages). No +\fB/etc/dhcp\fR.\fIinterface\fR file is necessary, but such a file can be used +to specify an interface as "primary," provided that IPv4 DHCP is also in use. +.LP +Network parameters needed for system configuration during bootup are extracted +from the information received by the daemon through the use of the +\fBdhcpinfo\fR(1) command. The daemon's default behavior can be altered by +changing the tunables in the \fB/etc/default/dhcpagent\fR file. The daemon is +controlled by the \fBifconfig\fR(8) utility. Check the status of the daemon +using the \fBnetstat\fR(8) and \fBifconfig\fR(8) commands. +.SH SEE ALSO +.BR dhcpinfo (1), +.BR syslog (3C), +.BR dhcp_inittab (5), +.BR ndpd.conf (5), +.BR dhcpagent (8), +.BR ifconfig (8), +.BR in.ndpd (8), +.BR netstat (8) +.LP +Alexander, S., and R. Droms. \fIRFC 2132, DHCP Options and BOOTP Vendor +Extensions\fR. Silicon Graphics, Inc. Bucknell University. March 1997. +.LP +Droms, R. \fIRFC 1534, Interoperation Between DHCP and BOOTP\fR. Bucknell +University. October 1993. +.LP +Droms, R. \fIRFC 2131, Dynamic Host Configuration Protocol\fR. Bucknell +University. March 1997. +.LP +Wimer, W. \fIRFC 1542, Clarifications and Extensions for the Bootstrap +Protocol\fR. Carnegie Mellon University. October 1993. +.LP +Lemon, T. and B. Sommerfeld. \fIRFC 4361, Node-specific Client Identifiers for +Dynamic Host Configuration Protocol Version Four (DHCPv4)\fR. Nominum and Sun +Microsystems. February 2006. +.LP +Droms, R. \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6 +(DHCPv6)\fR. Cisco Systems. July 2003. diff --git a/usr/src/man/man7/environ.7 b/usr/src/man/man7/environ.7 new file mode 100644 index 0000000000..f3ada02e56 --- /dev/null +++ b/usr/src/man/man7/environ.7 @@ -0,0 +1,562 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" 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 ENVIRON 7 "Jun 26, 2014" +.SH NAME +environ \- user environment +.SH DESCRIPTION +.LP +When a process begins execution, one of the \fBexec\fR family of functions +makes available an array of strings called the environment; see \fBexec\fR(2). +By convention, these strings have the form \fIvariable=value\fR, for example, +\fBPATH=/sbin:/usr/sbin\fR. These environmental variables provide a way to make +information about a program's environment available to programs. +.LP +A name may be placed in the environment by the \fBexport\fR command and +\fIname\fR=\fIvalue\fR arguments in \fBsh\fR(1), or by one of the \fBexec\fR +functions. It is unwise to conflict with certain shell variables such as +\fBMAIL\fR, \fBPS1\fR, \fBPS2\fR, and \fBIFS\fR that are frequently exported by +\fB\&.profile\fR files; see \fBprofile\fR(5). +.LP +The following environmental variables can be used by applications and are +expected to be set in the target run-time environment. +.sp +.ne 2 +.na +\fB\fBHOME\fR\fR +.ad +.sp .6 +.RS 4n +The name of the user's login directory, set by \fBlogin\fR(1) from the password +file; see \fBpasswd\fR(5). +.RE + +.sp +.ne 2 +.na +\fB\fBLANG\fR\fR +.ad +.sp .6 +.RS 4n +The string used to specify internationalization information that allows users +to work with different national conventions. The \fBsetlocale\fR(3C) and +\fBnewlocale\fR(3C) functions +check the \fBLANG\fR environment variable when they are called with \fB""\fR as +the \fBlocale\fR argument. \fBLANG\fR is used as the default locale if the +corresponding environment variable for a particular category is unset or null. +If, however, \fBLC_ALL\fR is set to a valid, non-empty value, its contents are +used to override both the \fBLANG\fR and the other \fBLC_*\fR variables. For +example, when invoked as \fBsetlocale(LC_CTYPE, "")\fR, \fBsetlocale()\fR will +query the \fBLC_CTYPE\fR environment variable first to see if it is set and +non-null. If \fBLC_CTYPE\fR is not set or null, then \fBsetlocale()\fR will +check the \fBLANG\fR environment variable to see if it is set and non-null. If +both \fBLANG\fR and \fBLC_CTYPE\fR are unset or \fINULL\fR, the default "C" +locale will be used to set the \fBLC_CTYPE\fR category. +.sp +Most commands will invoke \fBsetlocale(LC_ALL, "")\fR prior to any other +processing. This allows the command to be used with different national +conventions by setting the appropriate environment variables. In addition, some +commands will use +.BR uselocale (3C) +to set a thread-specific locale. +.sp +The following environment variables correspond to each category of +\fBsetlocale\fR(3C): +.sp +.ne 2 +.na +\fB\fBLC_ALL\fR\fR +.ad +.sp .6 +.RS 4n +If set to a valid, non-empty string value, override the values of \fBLANG\fR +and all the other \fBLC_*\fRvariables. +.RE + +.sp +.ne 2 +.na +\fB\fBLC_COLLATE\fR\fR +.ad +.sp .6 +.RS 4n +This category specifies the character collation sequence being used. The +information corresponding to this category is stored in a database created by +the \fBlocaledef\fR(1) command. This environment variable affects +\fBstrcoll\fR(3C) and \fBstrxfrm\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBLC_CTYPE\fR\fR +.ad +.sp .6 +.RS 4n +This category specifies character classification, character conversion, and +widths of multibyte characters. When \fBLC_CTYPE\fR is set to a valid value, +the calling utility can display and handle text and file names containing valid +characters for that locale; Extended Unix Code (EUC) characters where any +individual character can be 1, 2, or 3 bytes wide; and EUC characters of 1, 2, +or 3 column widths. The default "C" locale corresponds to the 7-bit \fBASCII\fR +character set; only characters from ISO 8859-1 are valid. The information +corresponding to this category is stored in a database created by the +\fBlocaledef()\fR command. This environment variable is used by +\fBctype\fR(3C), \fBmblen\fR(3C), and many commands, such as \fBcat\fR(1), +\fBed\fR(1), \fBls\fR(1), and \fBvi\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fBLC_MESSAGES\fR\fR +.ad +.sp .6 +.RS 4n +This category specifies the language of the message database being used. For +example, an application may have one message database with French messages, and +another database with German messages. Message databases are created by the +\fBmkmsgs\fR(1) command. This environment variable is used by \fBexstr\fR(1), +\fBgettxt\fR(1), \fBsrchtxt\fR(1), \fBgettxt\fR(3C), and \fBgettext\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBLC_MONETARY\fR\fR +.ad +.sp .6 +.RS 4n +This category specifies the monetary symbols and delimiters used for a +particular locale. The information corresponding to this category is stored in +a database created by the \fBlocaledef\fR(1) command. This environment variable +is used by \fBlocaleconv\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBLC_NUMERIC\fR\fR +.ad +.sp .6 +.RS 4n +This category specifies the decimal and thousands delimiters. The information +corresponding to this category is stored in a database created by the +\fBlocaledef()\fR command. The default \fBC\fR locale corresponds to \fB"."\fR +as the decimal delimiter and no thousands delimiter. This environment variable +is used by \fBlocaleconv\fR(3C), \fBprintf\fR(3C), and \fBstrtod\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBLC_TIME\fR\fR +.ad +.sp .6 +.RS 4n +This category specifies date and time formats. The information corresponding to +this category is stored in a database specified in \fBlocaledef()\fR. The +default \fBC\fR locale corresponds to U.S. date and time formats. This +environment variable is used by many commands and functions; for example: +\fBat\fR(1), \fBcalendar\fR(1), \fBdate\fR(1), \fBstrftime\fR(3C), and +\fBgetdate\fR(3C). +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fBMSGVERB\fR\fR +.ad +.sp .6 +.RS 4n +Controls which standard format message components \fBfmtmsg\fR selects when +messages are displayed to \fBstderr\fR; see \fBfmtmsg\fR(1) and +\fBfmtmsg\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBNETPATH\fR\fR +.ad +.sp .6 +.RS 4n +A colon-separated list of network identifiers. A network identifier is a +character string used by the Network Selection component of the system to +provide application-specific default network search paths. A network identifier +must consist of non-null characters and must have a length of at least 1. No +maximum length is specified. Network identifiers are normally chosen by the +system administrator. A network identifier is also the first field in any +\fB/etc/netconfig\fR file entry. \fBNETPATH\fR thus provides a link into the +\fB/etc/netconfig\fR file and the information about a network contained in that +network's entry. \fB/etc/netconfig\fR is maintained by the system +administrator. The library routines described in \fBgetnetpath\fR(3NSL) access +the \fBNETPATH\fR environment variable. +.RE + +.sp +.ne 2 +.na +\fB\fBNLSPATH\fR\fR +.ad +.sp .6 +.RS 4n +Contains a sequence of templates which \fBcatopen\fR(3C) and \fBgettext\fR(3C) +use when attempting to locate message catalogs. Each template consists of an +optional prefix, one or more substitution fields, a filename and an optional +suffix. For example: +.sp +.in +2 +.nf +NLSPATH="/system/nlslib/%N.cat" +.fi +.in -2 +.sp + +defines that \fBcatopen()\fR should look for all message catalogs in the +directory \fB/system/nlslib\fR, where the catalog name should be constructed +from the \fIname\fR parameter passed to \fBcatopen\fR(\|), \fB%N\fR, with the +suffix \fB\&.cat\fR. +.sp +Substitution fields consist of a \fB%\fR symbol, followed by a single-letter +keyword. The following keywords are currently defined: +.sp +.ne 2 +.na +\fB%N\fR +.ad +.sp .6 +.RS 4n +The value of the \fIname\fR parameter passed to \fBcatopen()\fR. +.RE + +.sp +.ne 2 +.na +\fB%L\fR +.ad +.sp .6 +.RS 4n +The value of \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.na +\fB%l\fR +.ad +.sp .6 +.RS 4n +The language element from \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.na +\fB%t\fR +.ad +.sp .6 +.RS 4n +The territory element from \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.na +\fB%c\fR +.ad +.sp .6 +.RS 4n +The codeset element from \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.na +\fB%%\fR +.ad +.sp .6 +.RS 4n +A single \fB%\fR character. +.RE + +An empty string is substituted if the specified value is not currently defined. +The separators "\fB_\fR" and "\fB\&.\fR" are not included in \fB%t\fR and +\fB%c\fR substitutions. +.sp +Templates defined in \fBNLSPATH\fR are separated by colons (\fB:\fR). A leading +colon or two adjacent colons (\fB::\fR) is equivalent to specifying \fB%N\fR. +For example: +.sp +.in +2 +.nf +NLSPATH=":%N.cat:/nlslib/%L/%N.cat" +.fi +.in -2 +.sp + +indicates to \fBcatopen()\fR that it should look for the requested message +catalog in \fIname\fR, \fIname\fR\fB\&.cat\fR and +\fB/nlslib/$LANG/\fR\fIname\fR.cat. For \fBgettext()\fR, \fB%N\fR automatically +maps to "messages". +.sp +If \fBNLSPATH\fR is unset or \fINULL\fR, \fBcatopen()\fR and \fBgettext()\fR +call \fBsetlocale\fR(3C), which checks \fBLANG\fR and the \fBLC_*\fR +variables to locate the message catalogs. +.sp +\fBNLSPATH\fR will normally be set up on a system wide basis (in +\fB/etc/profile\fR) and thus makes the location and naming conventions +associated with message catalogs transparent to both programs and users. +.RE + +.sp +.ne 2 +.na +\fB\fBPATH\fR\fR +.ad +.sp .6 +.RS 4n +The sequence of directory prefixes that \fBsh\fR(1), \fBtime\fR(1), +\fBnice\fR(1), \fBnohup\fR(1), and other utilities apply in searching for a +file known by an incomplete path name. The prefixes are separated by colons +(\fB:\fR). \fBlogin\fR(1) sets \fBPATH=/usr/bin\fR. For more detail, see +\fBsh\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fBSEV_LEVEL\fR\fR +.ad +.sp .6 +.RS 4n +Define severity levels and associate and print strings with them in standard +format error messages; see \fBaddseverity\fR(3C), \fBfmtmsg\fR(1), and +\fBfmtmsg\fR(3C). +.RE + +.sp +.ne 2 +.na +\fB\fBTERM\fR\fR +.ad +.sp .6 +.RS 4n +The kind of terminal for which output is to be prepared. This information is +used by commands, such as \fBvi\fR(1), which may exploit special capabilities +of that terminal. +.RE + +.sp +.ne 2 +.na +\fB\fBTZ\fR\fR +.ad +.sp .6 +.RS 4n +Timezone information. The contents of this environment variable are used by the +functions \fBctime\fR(3C), \fBlocaltime\fR(3C), \fBstrftime\fR(3C), and +\fBmktime\fR(3C) to override the default timezone. The value of \fBTZ\fR has +one of the two formats (spaces inserted for clarity): +.sp +.in +2 +.nf +:characters +.fi +.in -2 + +or +.sp +.in +2 +.nf +std offset dst offset, rule +.fi +.in -2 + +If \fBTZ\fR is of the first format (that is, if the first character is a colon +(:)), or if \fBTZ\fR is not of the second format, then \fBTZ\fR designates a +path to a timezone database file relative to \fB/usr/share/lib/zoneinfo/\fR, +ignoring a leading colon if one exists. +.sp +Otherwise, \fBTZ\fR is of the second form, which when expanded is as follows: +.sp +.in +2 +.nf +\fIstdoffset\fR[\fIdst\fR[\fIoffset\fR][,\fIstart\fR[/\fItime\fR],\fIend\fR[/\fItime\fR]]] +.fi +.in -2 + +.sp +.ne 2 +.na +\fB\fIstd\fR and \fIdst\fR\fR +.ad +.sp .6 +.RS 4n +Indicate no less than three, nor more than {\fBTZNAME_MAX\fR}, bytes that are +the designation for the standard (\fIstd\fR) or the alternative (\fIdst\fR, +such as Daylight Savings Time) timezone. Only \fIstd\fR is required; if +\fIdst\fR is missing, then the alternative time does not apply in this +timezone. Each of these fields can occur in either of two formats, quoted or +unquoted: +.RS +4 +.TP +.ie t \(bu +.el o +In the quoted form, the first character is the less-than ('<') character and +the last character is the greater-than ('>') character. All characters between +these quoting characters are alphanumeric characters from the portable +character set in the current locale, the plus-sign ('+') character, or the +minus-sign ('-') character. The \fIstd\fR and \fIdst\fR fields in this case do +not include the quoting characters. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +In the unquoted form, all characters in these fields are alphabetic characters +from the portable character set in the current locale. +.RE +The interpretation of these fields is unspecified if either field is less than +three bytes (except for the case when \fIdst\fR is missing), more than +{\fBTZNAME_MAX\fR} bytes, or if they contain characters other than those +specified. +.RE + +.sp +.ne 2 +.na +\fB\fIoffset\fR\fR +.ad +.sp .6 +.RS 4n +Indicate the value one must add to the local time to arrive at Coordinated +Universal Time. The offset has the form: +.sp +.in +2 +.nf +\fIhh\fR[:\fImm\fR[:\fIss\fR]] +.fi +.in -2 +.sp + +The minutes (\fImm\fR) and seconds (\fIss\fR) are optional. The hour (\fIhh\fR) +is required and can be a single digit. The \fIoffset\fR following \fIstd\fR is +required. If no \fIoffset\fR follows \fIdst\fR, daylight savings time is +assumed to be one hour ahead of standard time. One or more digits can be used. +The value is always interpreted as a decimal number. The hour must be between 0 +and 24, and the minutes (and seconds), if present, must be between 0 and 59. +Out of range values can cause unpredictable behavior. If preceded by a "-", the +timezone is east of the Prime Meridian. Otherwise, it is west of the Prime +Meridian (which can be indicated by an optional preceding "\fI+\fR" sign). +.RE + +.sp +.ne 2 +.na +\fB\fIstart\fR/\fItime\fR,\|\fIend\fR/\fItime\fR\fR +.ad +.sp .6 +.RS 4n +Indicate when to change to and back from daylight savings time, where +\fIstart/time\fR describes when the change from standard time to daylight +savings time occurs, and \fIend/time\fR describes when the change back occurs. +Each \fItime\fR field describes when, in current local time, the change is +made. +.sp +The formats of \fIstart\fR and \fIend\fR are one of the following: +.sp +.ne 2 +.na +\fB\fBJ\fR\fIn\fR\fR +.ad +.sp .6 +.RS 4n +The Julian day \fIn\fR (1 \(<= \fIn\fR \(<= 365). Leap days are not counted. +That is, in all years, February 28 is day 59 and March 1 is day 60. It is +impossible to refer to the occasional February 29. +.RE + +.sp +.ne 2 +.na +\fB\fIn\fR\fR +.ad +.sp .6 +.RS 4n +The zero-based Julian day (0 \(<= \fIn\fR \(<= 365). Leap days are counted, and +it is possible to refer to February 29. +.RE + +.sp +.ne 2 +.na +\fB\fBM\fR\fIm.n.d\fR\fR +.ad +.sp .6 +.RS 4n +The \fId\fR^th day, (0 \(<= \fId\fR \(<= 6) of week \fIn\fR of month \fIm\fR of +the year (1 \(<= \fIn\fR \(<= 5, 1 \(<= \fIm\fR \(<= 12), where week 5 means +"the last \fId\fR-day in month \fIm\fR" which may occur in either the fourth or +the fifth week). Week 1 is the first week in which the \fId\fR^th day occurs. +Day zero is Sunday. +.RE + +Implementation specific defaults are used for \fIstart\fR and \fIend\fR if +these optional fields are not specified. +.sp +The \fItime\fR has the same format as \fIoffset\fR except that no leading sign +("-" or "+" ) is allowed. If \fItime\fR is not specified, the default value is +02:00:00. +.RE + +.RE + +.SH SEE ALSO +.LP +.BR cat (1), +.BR date (1), +.BR ed (1), +.BR fmtmsg (1), +.BR localedef (1), +.BR login (1), +.BR ls (1), +.BR mkmsgs (1), +.BR nice (1), +.BR nohup (1), +.BR sh (1), +.BR sort (1), +.BR time (1), +.BR vi (1), +.BR exec (2), +.BR addseverity (3C), +.BR catopen (3C), +.BR ctime (3C), +.BR ctype (3C), +.BR fmtmsg (3C), +.BR getdate (3C), +.BR gettext (3C), +.BR gettxt (3C), +.BR localeconv (3C), +.BR mblen (3C), +.BR mktime (3C), +.BR newlocale (3C), +.BR printf (3C), +.BR setlocale (3C), +.BR strcoll (3C), +.BR strftime (3C), +.BR strtod (3C), +.BR strxfrm (3C), +.BR uselocale (3C), +.BR getnetpath (3NSL), +.BR TIMEZONE (5), +.BR netconfig (5), +.BR passwd (5), +.BR profile (5) diff --git a/usr/src/man/man7/epoll.7 b/usr/src/man/man7/epoll.7 new file mode 100644 index 0000000000..05df7322dd --- /dev/null +++ b/usr/src/man/man7/epoll.7 @@ -0,0 +1,108 @@ +'\" 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 7 "May 16, 2020" +.SH NAME +epoll \- Linux-compatible I/O event notification facility +.SH SYNOPSIS +.nf +#include <sys/epoll.h> +.fi + +.SH DESCRIPTION +\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 argument 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) operates 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 +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 +.BR epoll_create (3C), +.BR epoll_create1 (3C), +.BR epoll_ctl (3C), +.BR epoll_pwait (3C), +.BR epoll_wait (3C), +.BR port_associate (3C), +.BR port_create (3C), +.BR port_dissociate (3C), +.BR port_get (3C), +.BR pselect (3C) diff --git a/usr/src/man/man7/eqn.7 b/usr/src/man/man7/eqn.7 new file mode 100644 index 0000000000..f2728a6b39 --- /dev/null +++ b/usr/src/man/man7/eqn.7 @@ -0,0 +1,507 @@ +.\" $Id: eqn.7,v 1.39 2020/01/10 11:55:04 schwarze Exp $ +.\" +.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 10 2020 $ +.Dt EQN 7 +.Os +.Sh NAME +.Nm eqn +.Nd eqn language reference for mandoc +.Sh DESCRIPTION +The +.Nm eqn +language is an equation-formatting language. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +.Ux +manual pages. +It describes the +.Em structure +of an equation, not its mathematical meaning. +This manual describes the +.Nm +language accepted by the +.Xr mandoc 1 +utility, which corresponds to the Second Edition +.Nm +specification (see +.Sx SEE ALSO +for references). +.Pp +An equation starts with an input line containing exactly the characters +.Sq \&.EQ , +may contain multiple input lines, and ends with an input line +containing exactly the characters +.Sq \&.EN . +Equivalently, an equation can be given in the middle of a single +text input line by surrounding it with the equation delimiters +defined with the +.Cm delim +statement. +.Pp +The equation grammar is as follows, where quoted strings are +case-sensitive literals in the input: +.Bd -literal -offset indent +eqn : box | eqn box +box : text + | \(dq{\(dq eqn \(dq}\(dq + | \(dqdefine\(dq text text + | \(dqndefine\(dq text text + | \(dqtdefine\(dq text text + | \(dqgfont\(dq text + | \(dqgsize\(dq text + | \(dqset\(dq text text + | \(dqundef\(dq text + | \(dqsqrt\(dq box + | box pos box + | box mark + | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq + | pile \(dq{\(dq list \(dq}\(dq + | font box + | \(dqsize\(dq text box + | \(dqleft\(dq text eqn [\(dqright\(dq text] +col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq +text : [^space\e\(dq]+ | \e\(dq.*\e\(dq +pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq +pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq +mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq + | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq +font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq +list : eqn + | list \(dqabove\(dq eqn +space : [\e^~ \et] +.Ed +.Pp +White-space consists of the space, tab, circumflex, and tilde +characters. +It is required to delimit tokens consisting of alphabetic characters +and it is ignored at other places. +Braces and quotes also delimit tokens. +If within a quoted string, these space characters are retained. +Quoted strings are also not scanned for keywords, glyph names, +and expansion of definitions. +To print a literal quote character, it can be prepended with a +backslash or expressed with the \e(dq escape sequence. +.Pp +Subequations can be enclosed in braces to pass them as arguments +to operation keywords, overriding standard operation precedence. +Braces can be nested. +To set a brace verbatim, it needs to be enclosed in quotes. +.Pp +The following text terms are translated into a rendered glyph, if +available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, +lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, +upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, +THETA, UPSILON, XI, inter (intersection), union (union), prod (product), +int (integral), sum (summation), grad (gradient), del (vector +differential), times (multiply), cdot (center-dot), nothing (zero-width +space), approx (approximately equals), prime (prime), half (one-half), +partial (partial differential), inf (infinity), >> (much greater), << +(much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), != +(not equal), == (equivalence), <= (less-than-equal), and >= +(more-than-equal). +The character escape sequences documented in +.Xr mandoc_char 7 +can be used, too. +.Pp +The following control statements are available: +.Bl -tag -width Ds +.It Cm define +Replace all occurrences of a key with a value. +Its syntax is as follows: +.Pp +.D1 Cm define Ar key cvalc +.Pp +The first character of the value string, +.Ar c , +is used as the delimiter for the value +.Ar val . +This allows for arbitrary enclosure of terms (not just quotes), such as +.Pp +.D1 Cm define Ar foo \(aqbar baz\(aq +.D1 Cm define Ar foo cbar bazc +.Pp +It is an error to have an empty +.Ar key +or +.Ar val . +Note that a quoted +.Ar key +causes errors in some +.Nm +implementations and should not be considered portable. +It is not expanded for replacements. +Definitions may refer to other definitions; these are evaluated +recursively when text replacement occurs and not when the definition is +created. +.Pp +Definitions can create arbitrary strings, for example, the following is +a legal construction. +.Bd -literal -offset indent +define foo \(aqdefine\(aq +foo bar \(aqbaz\(aq +.Ed +.Pp +Self-referencing definitions will raise an error. +The +.Cm ndefine +statement is a synonym for +.Cm define , +while +.Cm tdefine +is discarded. +.It Cm delim +This statement takes a string argument consisting of two bytes, +to be used as the opening and closing delimiters for equations +in the middle of text input lines. +Conventionally, the dollar sign is used for both delimiters, +as follows: +.Bd -literal -offset indent +\&.EQ +delim $$ +\&.EN +An equation like $sin pi = 0$ can now be entered +in the middle of a text input line. +.Ed +.Pp +The special statement +.Cm delim off +temporarily disables previously declared delimiters and +.Cm delim on +reenables them. +.It Cm gfont +Set the default font of subsequent output. +Its syntax is as follows: +.Pp +.D1 Cm gfont Ar font +.Pp +In mandoc, this value is discarded. +.It Cm gsize +Set the default size of subsequent output. +Its syntax is as follows: +.Pp +.D1 Cm gsize Oo +|\- Oc Ns Ar size +.Pp +The +.Ar size +value should be an integer. +If prepended by a sign, +the font size is changed relative to the current size. +.It Cm set +Set an equation mode. +In mandoc, both arguments are thrown away. +Its syntax is as follows: +.Pp +.D1 Cm set Ar key val +.Pp +The +.Ar key +and +.Ar val +are not expanded for replacements. +This statement is a GNU extension. +.It Cm undef +Unset a previously-defined key. +Its syntax is as follows: +.Pp +.D1 Cm define Ar key +.Pp +Once invoked, the definition for +.Ar key +is discarded. +The +.Ar key +is not expanded for replacements. +This statement is a GNU extension. +.El +.Pp +Operation keywords have the following semantics: +.Bl -tag -width Ds +.It Cm above +See +.Cm pile . +.It Cm bar +Draw a line over the preceding box. +.It Cm bold +Set the following box using bold font. +.It Cm ccol +Like +.Cm cpile , +but for use in +.Cm matrix . +.It Cm cpile +Like +.Cm pile , +but with slightly increased vertical spacing. +.It Cm dot +Set a single dot over the preceding box. +.It Cm dotdot +Set two dots (dieresis) over the preceding box. +.It Cm dyad +Set a dyad symbol (left-right arrow) over the preceding box. +.It Cm fat +A synonym for +.Cm bold . +.It Cm font +Set the second argument using the font specified by the first argument; +currently not recognized by the +.Xr mandoc 1 +.Nm +parser. +.It Cm from +Set the following box below the preceding box, +using a slightly smaller font. +Used for sums, integrals, limits, and the like. +.It Cm hat +Set a hat (circumflex) over the preceding box. +.It Cm italic +Set the following box using italic font. +.It Cm lcol +Like +.Cm lpile , +but for use in +.Cm matrix . +.It Cm left +Set the first argument as a big left delimiter before the second argument. +As an optional third argument, +.Cm right +can follow. +In that case, the fourth argument is set as a big right delimiter after +the second argument. +.It Cm lpile +Like +.Cm cpile , +but subequations are left-justified. +.It Cm matrix +Followed by a list of columns enclosed in braces. +All columns need to have the same number of subequations. +The columns are set as a matrix. +The difference compared to multiple subsequent +.Cm pile +operators is that in a +.Cm matrix , +corresponding subequations in all columns line up horizontally, +while each +.Cm pile +does vertical spacing independently. +.It Cm over +Set a fraction. +The preceding box is the numerator, the following box is the denominator. +.It Cm pile +Followed by a list of subequations enclosed in braces, +the subequations being separated by +.Cm above +keywords. +Sets the subequations one above the other, each of them centered. +Typically used to represent vectors in coordinate representation. +.It Cm rcol +Like +.Cm rpile , +but for use in +.Cm matrix . +.It Cm right +See +.Cm left ; +.Cm right +cannot be used without +.Cm left . +To set a big right delimiter without a big left delimiter, the following +construction can be used: +.Pp +.D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter +.It Cm roman +Set the following box using the default font. +.It Cm rpile +Like +.Cm cpile , +but subequations are right-justified. +.It Cm size +Set the second argument with the font size specified by the first +argument; currently ignored by +.Xr mandoc 1 . +By prepending a plus or minus sign to the first argument, +the font size can be selected relative to the current size. +.It Cm sqrt +Set the square root of the following box. +.It Cm sub +Set the following box as a subscript to the preceding box. +.It Cm sup +Set the following box as a superscript to the preceding box. +As a special case, if a +.Cm sup +clause immediately follows a +.Cm sub +clause as in +.Pp +.D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox +.Pp +both are set with respect to the same +.Ar mainbox , +that is, +.Ar supbox +is set above +.Ar subbox . +.It Cm tilde +Set a tilde over the preceding box. +.It Cm to +Set the following box above the preceding box, +using a slightly smaller font. +Used for sums and integrals and the like. +As a special case, if a +.Cm to +clause immediately follows a +.Cm from +clause as in +.Pp +.D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox +.Pp +both are set below and above the same +.Ar mainbox . +.It Cm under +Underline the preceding box. +.It Cm vec +Set a vector symbol (right arrow) over the preceding box. +.El +.Pp +The binary operations +.Cm from , +.Cm to , +.Cm sub , +and +.Cm sup +group to the right, that is, +.Pp +.D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox +.Pp +is the same as +.Pp +.D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox +.Pp +and different from +.Pp +.D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox . +.Pp +By contrast, +.Cm over +groups to the left. +.Pp +In the following list, earlier operations bind more tightly than +later operations: +.Pp +.Bl -enum -compact +.It +.Cm dyad , +.Cm vec , +.Cm under , +.Cm bar , +.Cm tilde , +.Cm hat , +.Cm dot , +.Cm dotdot +.It +.Cm fat , +.Cm roman , +.Cm italic , +.Cm bold , +.Cm size +.It +.Cm sub , +.Cm sup +.It +.Cm sqrt +.It +.Cm over +.It +.Cm from , +.Cm to +.El +.Sh COMPATIBILITY +This section documents the compatibility of mandoc +.Nm +and the troff +.Nm +implementation (including GNU troff). +.Pp +.Bl -dash -compact +.It +The text string +.Sq \e\(dq +is interpreted as a literal quote in troff. +In mandoc, this is interpreted as a comment. +.It +In troff, The circumflex and tilde white-space symbols map to +fixed-width spaces. +In mandoc, these characters are synonyms for the space character. +.It +The troff implementation of +.Nm +allows for equation alignment with the +.Cm mark +and +.Cm lineup +tokens. +mandoc discards these tokens. +The +.Cm back Ar n , +.Cm fwd Ar n , +.Cm up Ar n , +and +.Cm down Ar n +commands are also ignored. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mandoc_roff 7 , +.Xr mdoc 7 +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T System for Typesetting Mathematics +.%J Communications of the ACM +.%V 18 +.%P pp. 151\(en157 +.%D March, 1975 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide +.%D 1976 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide (Second Edition) +.%D 1978 +.Re +.Sh HISTORY +The eqn utility, a preprocessor for troff, was originally written by +Brian W. Kernighan and Lorinda L. Cherry in 1975. +The GNU reimplementation of eqn, part of the GNU troff package, was +released in 1989 by James Clark. +The eqn component of +.Xr mandoc 1 +was added in 2011. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/usr/src/man/man7/eqnchar.7 b/usr/src/man/man7/eqnchar.7 new file mode 100644 index 0000000000..592115f5df --- /dev/null +++ b/usr/src/man/man7/eqnchar.7 @@ -0,0 +1,42 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH EQNCHAR 7 "Jul 12, 2002" +.SH NAME +eqnchar \- special character definitions for eqn +.SH SYNOPSIS +.LP +.nf +eqn /usr/share/lib/pub/eqnchar \fIfilename\fR | troff \fIoptions\fR +.fi + +.LP +.nf +neqn /usr/share/lib/pub/eqnchar \fIfilename\fR | troff \fIoptions\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBeqnchar\fR command contains \fBnroff\fR(1) and \fBtroff\fR(1) character +definitions for constructing characters that are not available on the Graphic +Systems typesetter. These definitions are primarily intended for use with +\fBeqn\fR(1) and \fBneqn\fR(1). It contains definitions for the characters +listed in the following table. +.sp +To view the special characters, see the online man page on docs.sun.com or a +print copy. +.SH FILES +.sp +.LP +\fB/usr/share/lib/pub/eqnchar\fR +.SH SEE ALSO +.sp +.LP +.BR eqn (1), +.BR nroff (1), +.BR troff (1), +.BR attributes (7) diff --git a/usr/src/man/man7/eventfd.7 b/usr/src/man/man7/eventfd.7 new file mode 100644 index 0000000000..18945d6df0 --- /dev/null +++ b/usr/src/man/man7/eventfd.7 @@ -0,0 +1,32 @@ +.\" +.\" 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. +.\" +.Dd Dec 3, 2014 +.Dt EVENTFD 7 +.Os +.Sh NAME +.Nm eventfd +.Nd Linux-compatible user event notification facility +.Sh SYNOPSIS +.In sys/eventfd.h +.Sh DESCRIPTION +.Nm +is a Linux-borne facility for sending and receiving user +events via a file descriptor. +While the facility itself is somewhat dubious (it can be mimicked in an entirely +portable way with a pipe), it is small and straightforward and this +implementation is entirely compatible with its Linux antecedent; see +.Xr eventfd 3C +for details. +.Sh SEE ALSO +.Xr eventfd 3C diff --git a/usr/src/man/man7/extendedFILE.7 b/usr/src/man/man7/extendedFILE.7 new file mode 100644 index 0000000000..7f63a34cf4 --- /dev/null +++ b/usr/src/man/man7/extendedFILE.7 @@ -0,0 +1,194 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH EXTENDEDFILE 7 "Apr 18, 2006" +.SH NAME +extendedFILE \- enable extended FILE facility usage +.SH SYNOPSIS +.LP +.nf +$ ulimit \fB-n\fR \fIN_file_descriptors\fR +$ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \fIapplication\fR [\fIarg\fR...] +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBextendedFILE.so.1\fR is not a library but an enabler of the extended +FILE facility. +.sp +.LP +The extended FILE facility allows 32-bit processes to use any valid file +descriptor with the standard I/O (see \fBstdio\fR(3C)) C library functions. +Historically, 32-bit applications have been limited to using the first 256 +numerical file descriptors for use with standard I/O streams. By using the +extended FILE facility this limitation is lifted. Any valid file descriptor can +be used with standard I/O. See the NOTES section of +\fBenable_extended_FILE_stdio\fR(3C). +.sp +.LP +The extended FILE facility is enabled from the shell level before an +application is launched. The file descriptor limit must also be raised. The +syntax for raising the file descriptor limit is +.sp +.in +2 +.nf +$ ulimit -n \fImax_file_descriptors\fR +$ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \fIapplication\fR [\fIarg\fR...] +.fi +.in -2 + +.sp +.LP +where \fImax_file_descriptors\fR is the maximum number of file descriptors +desired. See \fBlimit\fR(1). The maximum value is the same as the maximum value +for \fBopen\fR(2). +.SH ENVIRONMENT VARIABLES +.sp +.LP +The following environment variables control the behavior of the extended FILE +facility. +.sp +.ne 2 +.na +\fB\fB_STDIO_BADFD\fR\fR +.ad +.RS 23n +This variable takes an integer representing the lowest file descriptor, which +will be made unallocatable. This action provides a protection mechanism so that +applications that abuse interfaces do not experience silent data corruption. +The value must be between 3 and 255 inclusive. +.RE + +.sp +.ne 2 +.na +\fB\fB_STDIO_BADFD_SIGNAL\fR\fR +.ad +.RS 23n +This variable takes an integer or string representing any valid signal. See +\fBsignal.h\fR(3HEAD) for valid values or strings. This environment variable +causes the specified signal to be sent to the application if certain +exceptional cases are detected during the use of this facility. The default +signal is \fBSIGABRT\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRLimit the number of file descriptors and FILE standard I/O +structures. +.sp +.LP +The following example limits the number of file descriptors and FILE standard +I/O structures to 1000. + +.sp +.in +2 +.nf +$ ulimit -n 1000 +$ LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 application [arg...] +.fi +.in -2 + +.LP +\fBExample 2 \fREnable the extended FILE facility. +.sp +.LP +The following example enables the extended FILE facility. See +\fBenable_extended_FILE_stdio\fR(3C) for more examples. + +.sp +.in +2 +.nf +$ ulimit -n 1000 +$ _STDIO_BADFD=100 _STDIO_BADFD_SIGNAL=SIGABRT \e + LD_PRELOAD_32=/usr/lib/extendedFILE.so.1 \e + application [arg ...] +.fi +.in -2 + +.LP +\fBExample 3 \fRSet up the extended FILE environment and start the application. +.sp +.LP +The following shell script first sets up the proper extended FILE environment +and then starts the application: + +.sp +.in +2 +.nf +#!/bin/sh +if [ $# = 0 ]; then + echo "usage: $0 application [arguments...]" + exit 1 +fi +ulimit -n 1000 +# _STDIO_BADFD=196; export _STDIO_BADFD +# _STDIO_BADFD_SIGNAL=SIGABRT; export _STDIO_BADFD_SIGNAL +LD_PRELOAD_32=/usr/lib/extendedFILE.so.1; export LD_PRELOAD_32 +"$@" +.fi +.in -2 + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/lib/extendedFILE.so.1\fR\fR +.ad +.RS 30n +enabling library +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Stable +_ +MT-Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR limit (1), +.BR open (2), +.BR enable_extended_FILE_stdio (3C), +.BR fdopen (3C), +.BR fopen (3C), +.BR popen (3C), +.BR stdio (3C), +.BR signal.h (3HEAD), +.BR attributes (7) +.SH WARNINGS +.sp +.LP +The following displayed message +.sp +.in +2 +.nf +Application violated extended FILE safety mechanism. +Please read the man page for extendedFILE. +Aborting +.fi +.in -2 +.sp + +.sp +.LP +is an indication that your application is modifying the internal file +descriptor field of the \fBFILE\fR structure from standard I/O. Continued use +of this extended FILE facility could harm your data. Do not use the extended +FILE facility with your application. diff --git a/usr/src/man/man7/filesystem.7 b/usr/src/man/man7/filesystem.7 new file mode 100644 index 0000000000..958e62dd10 --- /dev/null +++ b/usr/src/man/man7/filesystem.7 @@ -0,0 +1,2982 @@ +.\" +.\" 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] +.\" +.\" +.\" Copyright 1989 AT&T +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2016 Nexenta Systems, Inc. +.\" Copyright 2017 Peter Tribble +.\" +.TH FILESYSTEM 7 "Apr 15, 2020" +.SH NAME +filesystem \- File system organization +.SH SYNOPSIS +.nf +/ +.fi + +.LP +.nf +/usr +.fi + +.SH DESCRIPTION +The file system tree is organized for administrative convenience. Distinct +areas within the file system tree are provided for files that are private to +one machine, files that can be shared by multiple machines of a common +platform, files that can be shared by all machines, and home directories. This +organization allows sharable files to be stored on one machine but accessed by +many machines using a remote file access mechanism such as \fBNFS\fR. Grouping +together similar files makes the file system tree easier to upgrade and manage. +.sp +.LP +The file system tree consists of a root file system and a collection of +mountable file systems. The \fBmount\fR(2) program attaches mountable file +systems to the file system tree at mount points (directory entries) in the root +file system or other previously mounted file systems. Two file systems, \fB/\fR +(the root) and \fB/usr\fR, must be mounted and \fB/var\fR must be accessible to +have a functional system. The root file system is mounted automatically by the +kernel at boot time; the \fB/usr\fR file system is mounted by the system +start-up script, which is run as part of the booting process. \fB/var\fR can be +mounted as its own file system or be part of \fB/usr\fR, as it is by default. +.sp +.LP +Certain locations, noted below, are approved installation locations for bundled +Foundation Solaris software. In some cases, the approved locations for bundled +software are also approved locations for add-on system software or for +applications. The following descriptions make clear where the two locations +differ. For example, \fB/etc\fR is the installation location for +platform-dependent configuration files that are bundled with Solaris software. +The analogous location for applications is \fB/etc/opt/\fR\fIpackagename\fR. +.sp +.LP +In the following descriptions, \fIsubsystem\fR is a category of application or +system software, such as a window system (\fBdt\fR) or a language +(\fBjava1.2\fR) +.sp +.LP +The following descriptions make use of the terms \fBplatform\fR, +\fBplatform-dependent\fR, \fBplatform-independent\fR, and +\fBplatform-specific\fR. Platform refers to a machines Instruction Set +Architecture or processor type, such as is returned by \fBuname\fR \fB-i\fR. +\fBPlatform-dependent\fR refers to a file that is installed on all platforms +and whose contents vary depending on the platform. Like a platform-dependent +file, a \fBplatform-independent\fR file is installed on all platforms. However, +the contents of the latter type remains the same on all platforms. An example +of a platform-dependent file is compiled, executable program. An example of a +platform-independent file is a standard configuration file, such as +\fB/etc/hosts\fR. Unlike a platform-dependent or a platform-independent file, +the \fBplatform-specific\fR file is installed only on a subset of supported +platforms. Most platform-specific files are gathered under \fB/platform\fR and +\fB/usr/platform\fR. +.SS "Root File System" +The root file system contains files that are unique to each machine. It +contains the following directories: +.sp +.ne 2 +.na +\fB\fB/\fR\fR +.ad +.sp .6 +.RS 4n +Root of the overall file system name space. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev\fR\fR +.ad +.sp .6 +.RS 4n +The device name file system. See \fBdev\fR(4FS). +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/cfg\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic links to physical \fBap_ids.\fR +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/cpu\fR\fR +.ad +.sp .6 +.RS 4n +Provides configuration and capability information about the processor type +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/cua\fR\fR +.ad +.sp .6 +.RS 4n +Device files for \fBuucp\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/dsk\fR\fR +.ad +.sp .6 +.RS 4n +Block disk devices. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/dtrace\fR\fR +.ad +.sp .6 +.RS 4n +Pseudo-devices used by the DTrace framework. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/dtrace/provider\fR\fR +.ad +.sp .6 +.RS 4n +Pseudo-device drivers representing instrumentation providers for the DTrace +framework. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/fbs\fR\fR +.ad +.sp .6 +.RS 4n +Frame buffer device files. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/fd\fR\fR +.ad +.sp .6 +.RS 4n +File descriptors. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/net\fR\fR +.ad +.sp .6 +.RS 4n +Network data-link interface devices. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/printers\fR\fR +.ad +.sp .6 +.RS 4n +USB printer device files. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/pts\fR\fR +.ad +.sp .6 +.RS 4n +Pseudo-terminal devices. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/rdsk\fR\fR +.ad +.sp .6 +.RS 4n +Raw disk devices. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/rmt\fR\fR +.ad +.sp .6 +.RS 4n +Raw tape devices. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/sad\fR\fR +.ad +.sp .6 +.RS 4n +Entry points for the \fBSTREAMS\fR Administrative driver. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/sound\fR\fR +.ad +.sp .6 +.RS 4n +Audio device and audio device control files. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/swap\fR\fR +.ad +.sp .6 +.RS 4n +Default swap device. +.RE + +.sp +.ne 2 +.na +\fB\fB/dev/term\fR\fR +.ad +.sp .6 +.RS 4n +Terminal devices. +.RE + +.sp +.ne 2 +.na +\fB\fB/devices\fR\fR +.ad +.sp .6 +.RS 4n +The devices file system. See \fBdevfs\fR(4FS). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent administrative and configuration files and databases that +are not shared among systems. \fB/etc\fR may be viewed as the directory that +defines the machine's identity. An approved installation location for bundled +Solaris software. The analogous location for add-on system software or for +applications is \fB/etc/opt/\fR\fIpackagename\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/X11\fR\fR +.ad +.sp .6 +.RS 4n +Xorg Xserver (X11) configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/acct\fR\fR +.ad +.sp .6 +.RS 4n +Process accounting system configuration information. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/cron.d\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for \fBcron\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/dat\fR\fR +.ad +.sp .6 +.RS 4n +Contains a list of interface adapters supported by uDAPL service providers. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/default\fR\fR +.ad +.sp .6 +.RS 4n +Defaults information for various programs. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/devices\fR\fR +.ad +.sp .6 +.RS 4n +Contains device-related data. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/dfs\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for shared file systems. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/dhcp\fR\fR +.ad +.sp .6 +.RS 4n +Dynamic Host Configuration Protocol (\fBDHCP\fR) configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/fm\fR\fR +.ad +.sp .6 +.RS 4n +Fault manager configuration files. For more information, see \fBfmd\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/fonts\fR\fR +.ad +.sp .6 +.RS 4n +Font configuration information. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/fs\fR\fR +.ad +.sp .6 +.RS 4n +Binaries organized by file system types for operations required before +\fB/usr\fR is mounted. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/ftpd\fR\fR +.ad +.sp .6 +.RS 4n +\fBftpd\fR configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/gss\fR\fR +.ad +.sp .6 +.RS 4n +Generic Security Service (\fBGSS\fR) Application Program Interface +configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/inet\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for Internet services. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/init.d\fR\fR +.ad +.sp .6 +.RS 4n +Shell scripts for transitioning between init states. The service management +facility, \fBsmf\fR(7) is the preferred mechanism for managing services. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/krb5\fR\fR +.ad +.sp .6 +.RS 4n +Kerberos configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/lib\fR\fR +.ad +.sp .6 +.RS 4n +Shared libraries needed during booting. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/llc2\fR\fR +.ad +.sp .6 +.RS 4n +Logical link control (\fBllc2\fR) driver configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/lp\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for the printer subsystem. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/mail\fR\fR +.ad +.sp .6 +.RS 4n +Mail subsystem configuration. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/nca\fR\fR +.ad +.sp .6 +.RS 4n +Solaris Network Cache and Accelerator (\fBNCA\fR) configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/net\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for transport independent network services. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/nfs\fR\fR +.ad +.sp .6 +.RS 4n +NFS server logging configuration file. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/opt\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for optional packages. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/ppp\fR\fR +.ad +.sp .6 +.RS 4n +Solaris \fBPPP\fR configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rc0.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 0. See \fBinit\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rc1.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 1. See \fBinit\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rc2.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 2. See \fBinit\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rc3.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 3. See \fBinit\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rcS.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for bringing the system up in single user mode. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rcm\fR\fR +.ad +.sp .6 +.RS 4n +Directory for reconfiguration manager (RCM) custom scripts. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/saf\fR\fR +.ad +.sp .6 +.RS 4n +Service Access Facility files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/sasl\fR\fR +.ad +.sp .6 +.RS 4n +Simple Authentication and Security Layer (SASL) server configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/security\fR\fR +.ad +.sp .6 +.RS 4n +Solaris-delivered security configuration files (Audit, RBAC, crypto, Trusted +Extensions). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/skel\fR\fR +.ad +.sp .6 +.RS 4n +Default profile scripts for new user accounts. See \fBuseradd\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/sound\fR\fR +.ad +.sp .6 +.RS 4n +Sound Events configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/ssh\fR\fR +.ad +.sp .6 +.RS 4n +Secure Shell configuration files. See \fBssh\fR(1) +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/svc\fR\fR +.ad +.sp .6 +.RS 4n +SMF service repository. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/sysevent\fR\fR +.ad +.sp .6 +.RS 4n +\fBsyseventd\fR configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/\fIsubsystem\fR\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent \fIsubsystem\fR configuration files that are not shared +among systems. An approved installation location for bundled Solaris software. +The analogous location for add-on system software or for applications is +\fB/etc/opt/\fR\fIpackagename\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/tm\fR\fR +.ad +.sp .6 +.RS 4n +Trademark files; contents displayed at boot time. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/usb\fR\fR +.ad +.sp .6 +.RS 4n +\fBUSB\fR configuration information. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/uucp\fR\fR +.ad +.sp .6 +.RS 4n +\fBUUCP\fR configuration information. See \fBuucp\fR(1C). +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/xml\fR\fR +.ad +.sp .6 +.RS 4n +Extensible Markup Language (XML) catalog. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/zfs\fR\fR +.ad +.sp .6 +.RS 4n +Contains the zfs state file, \fBzpool.cache\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/zones\fR\fR +.ad +.sp .6 +.RS 4n +Solaris Zones configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/export\fR\fR +.ad +.sp .6 +.RS 4n +Default root of the shared file system tree. +.RE + +.sp +.ne 2 +.na +\fB\fB/home\fR\fR +.ad +.sp .6 +.RS 4n +Default root of a subtree for user directories. Often managed by the +automounter, see \fBautomount\fR(8) for more details. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel\fR\fR +.ad +.sp .6 +.RS 4n +Subtree of platform-dependent loadable kernel modules required as part of the +boot process. It includes the generic part of the core kernel that is +platform-independent, \fB/kernel/genunix\fR. See \fBkernel\fR(8) An approved +installation location for bundled Solaris software and for add-on system +software. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/drv\fR\fR +.ad +.sp .6 +.RS 4n +32-bit x86 device drivers. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/drv/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +64-bit \fBSPARC\fR device drivers. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/drv/amd64\fR\fR +.ad +.sp .6 +.RS 4n +64-bit device drivers for 64-bit x86 platforms. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/dtrace\fR\fR +.ad +.sp .6 +.RS 4n +Kernel modules representing components in the DTrace framework. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/genunix\fR\fR +.ad +.sp .6 +.RS 4n +Platform-independent kernel. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/amd64/genunix\fR\fR +.ad +.sp .6 +.RS 4n +64-bit, platform-independent kernel. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/\fIsubsystem\fR/amd64\fR\fR +.ad +.sp .6 +.RS 4n +64-bit x86 platform-dependent modules required for boot. An approved +installation location for bundled Solaris software and for add-on system +software. +.RE + +.sp +.ne 2 +.na +\fB\fB/kernel/\fIsubsystem\fR/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +64-bit \fBSPARC\fR platform-dependent modules required for boot. An approved +installation location for bundled Solaris software and for add-on system +software. +.RE + +.sp +.ne 2 +.na +\fB\fB/lib/svc/manifest\fR\fR +.ad +.sp .6 +.RS 4n +SMF method scripts. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/packagename/lib/svc/manifest\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/mnt\fR\fR +.ad +.sp .6 +.RS 4n +Default temporary mount point for file systems. This is an empty directory on +which file systems can be temporarily mounted. +.RE + +.sp +.ne 2 +.na +\fB\fB/net\fR\fR +.ad +.sp .6 +.RS 4n +Temporary mount point for file systems that are mounted by the automounter. +.RE + +.sp +.ne 2 +.na +\fB\fB/opt\fR\fR +.ad +.sp .6 +.RS 4n +Root of a subtree for add-on application packages. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform\fR\fR +.ad +.sp .6 +.RS 4n +Subtree of platform-specific objects which need to reside on the root +filesystem. It contains a series of directories, one per supported platform. +The semantics of the series of directories is equivalent to \fB/\fR (root). +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR \fB-i\fR\fB\fR\fB`\fR\fB/kernel\fR\fR +.ad +.sp .6 +.RS 4n +Platform-specific modules required for boot. These modules have semantics +equivalent to \fB/kernel\fR. It includes the file \fBunix\fR, the core kernel. +See \fBkernel\fR(8). An approved installation location for bundled Solaris +software and for add-on system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR \fB-m\fR\fB\fR\fB`\fR\fB/kernel\fR\fR +.ad +.sp .6 +.RS 4n +Hardware class-specific modules required for boot. An approved installation +location for bundled Solaris software and for add-on system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/kernel/\fIsubsystem\fR/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit, platform-dependent modules required for boot. This is an approved +installation location for bundled Solaris software. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/kernel/\fIsubsystem\fR/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +\fBSPARC\fR 64-bit platform-specific modules required for boot. An approved +installation location for bundled Solaris software. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/kernel/sparcv9/unix\fR\fR +.ad +.sp .6 +.RS 4n +64-bit platform-dependent kernel. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/kernel/unix\fR\fR +.ad +.sp .6 +.RS 4n +32-bit platform-dependent kernel on i86 and a symlink to \fBsparcv9/unix\fR on +SPARC. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR \fB-i\fR\fB\fR\fB`\fR\fB/lib\fR\fR +.ad +.sp .6 +.RS 4n +Platform-specific shared objects required for boot. Semantics are equivalent to +\fB/lib\fR. An approved installation location for bundled Solaris software and +for add-on system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/platform/\fR\fB`\fR\fBuname\fR \fB-i\fR\fB\fR\fB`\fR\fB/sbin\fR\fR +.ad +.sp .6 +.RS 4n +Platform-specific administrative utilities required for boot. Semantics are +equivalent to \fB/sbin\fR. An approved installation location for bundled +Solaris software and for add-on system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/proc\fR\fR +.ad +.sp .6 +.RS 4n +Root of a subtree for the process file system. See \fBproc\fR(5). +.RE + +.sp +.ne 2 +.na +\fB\fB/sbin\fR\fR +.ad +.sp .6 +.RS 4n +Essential executables used in the booting process and in manual system +recovery. The full complement of utilities is available only after \fB/usr\fR +is mounted. \fB/sbin\fR is an approved installation location for bundled +Solaris software. +.RE + +.sp +.ne 2 +.na +\fB\fB/system\fR\fR +.ad +.sp .6 +.RS 4n +Mount point for the contract (CTFS) and object (OBJFS) file systems. See +\fBctfs\fR(4FS) and \fBobjfs\fR(4FS). +.RE + +.sp +.ne 2 +.na +\fB\fB/tmp\fR\fR +.ad +.sp .6 +.RS 4n +Temporary files. Usually mounted as a memory based file system. See +\fBtmpfs\fR(4FS). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr\fR\fR +.ad +.sp .6 +.RS 4n +Mount point for the \fB/usr\fR file system. See description of \fB/usr\fR file +system, below. +.RE + +.sp +.ne 2 +.na +\fB\fB/var\fR\fR +.ad +.sp .6 +.RS 4n +Root of a subtree for varying files. Varying files are files that are unique to +a machine but that can grow to an arbitrary (that is, variable) size. An +example is a log file. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/var/opt/\fR\fIpackagename\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/adm\fR\fR +.ad +.sp .6 +.RS 4n +System logging and accounting files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/audit\fR\fR +.ad +.sp .6 +.RS 4n +Default location for Audit log files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/cores\fR\fR +.ad +.sp .6 +.RS 4n +Directory provided for global core files storage. See \fBcoreadm\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/crash\fR\fR +.ad +.sp .6 +.RS 4n +Default depository for kernel crash dumps. See \fBdumpadm\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/cron\fR\fR +.ad +.sp .6 +.RS 4n +Log files for \fBcron\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/fm\fR\fR +.ad +.sp .6 +.RS 4n +Fault manager state files. For more information, see \fBfmd\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/ftp\fR\fR +.ad +.sp .6 +.RS 4n +\fBFTP\fR server directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/inet\fR\fR +.ad +.sp .6 +.RS 4n +IPv6 router state files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/krb5\fR\fR +.ad +.sp .6 +.RS 4n +Database and log files for Kerberos. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/ld\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for runtime linker. See \fBcrle\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/ldap\fR\fR +.ad +.sp .6 +.RS 4n +LDAP client configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/lib\fR\fR +.ad +.sp .6 +.RS 4n +Directory for variable state information. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/log\fR\fR +.ad +.sp .6 +.RS 4n +System log files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/lp\fR\fR +.ad +.sp .6 +.RS 4n +Line printer subsystem logging information. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/mail\fR\fR +.ad +.sp .6 +.RS 4n +Directory where users' mail is kept. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/news\fR\fR +.ad +.sp .6 +.RS 4n +Community service messages. This is not the same as USENET-style news. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/nfs\fR\fR +.ad +.sp .6 +.RS 4n +NFS server log files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/ntp\fR\fR +.ad +.sp .6 +.RS 4n +Network Time Protocol (\fBNTP\fR) server state directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/opt\fR\fR +.ad +.sp .6 +.RS 4n +Root of a subtree for varying files associated with optional software packages. +An approved installation location for add-on system software and applications. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/pkg\fR\fR +.ad +.sp .6 +.RS 4n +Data associated with the Image Packaging System. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/preserve\fR\fR +.ad +.sp .6 +.RS 4n +Backup files for \fBvi\fR(1) and \fBex\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/run\fR\fR +.ad +.sp .6 +.RS 4n +Temporary files which are not needed across reboots. Only root may modify the +contents of this directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/sadm\fR\fR +.ad +.sp .6 +.RS 4n +Data associated with legacy SVR4 package management utilities. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/saf\fR\fR +.ad +.sp .6 +.RS 4n +Service access facility logging and accounting files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool\fR\fR +.ad +.sp .6 +.RS 4n +Contains directories for files used in printer spooling, mail delivery, +\fBcron\fR(8), \fBat\fR(1), and so forth. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/clientmqueue\fR\fR +.ad +.sp .6 +.RS 4n +\fBsendmail\fR(8) client files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/cron\fR\fR +.ad +.sp .6 +.RS 4n +\fBcron\fR(8) and \fBat\fR(1) spooling files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/locks\fR\fR +.ad +.sp .6 +.RS 4n +Spooling lock files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/lp\fR\fR +.ad +.sp .6 +.RS 4n +Line printer spool files. See \fBlp\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/mqueue\fR\fR +.ad +.sp .6 +.RS 4n +Mail queued for delivery. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/pkg\fR\fR +.ad +.sp .6 +.RS 4n +Spooled packages. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/print\fR\fR +.ad +.sp .6 +.RS 4n +LP print service client-side request staging area. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/uucp\fR\fR +.ad +.sp .6 +.RS 4n +Queued \fBuucp\fR(1C) jobs. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/spool/uucppublic\fR\fR +.ad +.sp .6 +.RS 4n +Files deposited by \fBuucp\fR(1C). +.RE + +.sp +.ne 2 +.na +\fB\fB/var/statmon\fR\fR +.ad +.sp .6 +.RS 4n +Network status monitor files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/svc/log\fR\fR +.ad +.sp .6 +.RS 4n +SMF log files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/svc/manifest\fR\fR +.ad +.sp .6 +.RS 4n +SMF service manifests. An approved installation location for bundled, add-on +system software and applications. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/svc/manifest/site\fR\fR +.ad +.sp .6 +.RS 4n +Site-local SMF service manifests. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/tmp\fR\fR +.ad +.sp .6 +.RS 4n +Files that vary in size or presence during normal system operations. This +directory is \fBnot\fR cleared during the boot operation. An approved +installation location for bundled Solaris software and for add-on system +software and applications. +.sp +It is possible to change the default behavior for \fB/var/tmp\fR to clear all +of the files except editor temporary files by setting the \fBclean_vartmp\fR +property value of the \fBrmtmpfiles\fR service. This is done with the following +commands: +.sp +.in +2 +.nf +# \fBsvccfg -s svc:/system/rmtmpfiles setprop \e\fR + \fBoptions/clean_vartmp = "true"\fR +# \fBsvcadm refresh svc:/system/rmtmpfiles:default\fR +.fi +.in -2 +.sp + +The \fBsolaris.smf.value.rmtmpfiles\fR authorization is required to modify this +property. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/uucp\fR\fR +.ad +.sp .6 +.RS 4n +\fBuucp\fR(1C) log and status files. +.RE + +.sp +.ne 2 +.na +\fB\fB/var/yp\fR\fR +.ad +.sp .6 +.RS 4n +Databases used by \fBNIS\fR and \fBypbind\fR(8). +.RE + +.SS "\fB/usr\fR File System" +Because it is desirable to keep the root file system small and not volatile, on +disk-based systems larger file systems are often mounted on \fB/home\fR, +\fB/opt\fR, \fB/usr\fR, and \fB/var\fR. +.sp +.LP +The file system mounted on \fB/usr\fR contains platform-dependent and +platform-independent sharable files. The subtree rooted at \fB/usr/share\fR +contains platform-independent sharable files; the rest of the \fB/usr\fR tree +contains platform-dependent files. By mounting a common remote file system, a +group of machines with a common platform may share a single \fB/usr\fR file +system. A single \fB/usr/share\fR file system can be shared by machines of any +platform. A machine acting as a file server can share many different \fB/usr\fR +file systems to support several different architectures and operating system +releases. Clients usually mount \fB/usr\fR read-only so that they do not +accidentally change any shared files. +.sp +.LP +The \fB/usr\fR file system contains the following subdirectories: +.sp +.ne 2 +.na +\fB\fB/usr/5bin\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/usr/bin\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/X11\fR\fR +.ad +.sp .6 +.RS 4n +Xorg Xserver (X11) executables and documentation. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/adm\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/var/adm\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/bin\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent, user-invoked executables. These are commands users expect +to be run as part of their normal \fB$PATH\fR. For executables that are +different on a 64-bit system than on a 32-bit system, a wrapper that selects +the appropriate executable is placed here. See \fBisaexec\fR(3C). An approved +installation location for bundled Solaris software. The analogous location for +add-on system software or for applications is \fB/opt/\fIpackagename\fR/bin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/bin/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit, platform-dependent, user-invoked executables. This directory should +not be part of a user's \fB$PATH\fR. A wrapper in \fB/usr/bin\fR should invoke +the executable in this directory. See \fBisaexec\fR(3C). An approved +installation location for bundled Solaris software. The analogous location for +add-on system software or for applications is +\fB/opt/\fIpackagename\fR/bin/amd64\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/bin/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +\fBSPARC\fR platform-dependent, user-invoked executables. This directory should +not be part of a user's \fB$PATH\fR. A wrapper in \fB/usr/bin\fR should invoke +the executable in this directory. See \fBisaexec\fR(3C). An approved +installation location for bundled Solaris software. The analogous location for +add-on system software or for applications is +\fB/opt/\fIpackagename\fR/bin/sparcv9\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/bin/\fIsubsystem\fR\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent user-invoked executables that are associated with +\fIsubsystem\fR. These are commands users expect to be run as part of their +normal \fB$PATH\fR. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/bin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/bin\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent user-invoked executables that are associated with +\fIsubsystem\fR. These are commands users expect to be run as part of their +normal \fB$PATH\fR. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/bin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/bin/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit, platform-dependent, user-invoked executables. This directory should +not be part of a user's \fB$PATH\fR. A wrapper in \fB/usr/bin\fR should invoke +the executable in this directory. See \fBisaexec\fR(3C). An approved +installation location for bundled Solaris software. The analogous location for +add-on system software or for applications is +\fB/opt/\fIpackagename\fR/bin/amd64\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/bin/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +\fBSPARC\fR 64-bit, platform-dependent, user-invoked executables. This +directory should not be part of a user's \fB$PATH\fR. A wrapper in +\fB/usr/bin\fR should invoke the executable in this directory. See +\fBisaexec\fR(3C). An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/bin/sparcv9\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/ccs\fR\fR +.ad +.sp .6 +.RS 4n +Former location of files for the C compilation system, now containing +compatibility symbolic links to their new locations in \fB/usr/bin\fR +and \fB/usr/lib\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/demo\fR\fR +.ad +.sp .6 +.RS 4n +Demo programs and data. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/dict\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/usr/share/lib/dict\fR directory, which contains the +dictionary file used by the \fBUNIX\fR spell program. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/include\fR\fR +.ad +.sp .6 +.RS 4n +Include headers (for C programs). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/java\fI*\fR\fR\fR +.ad +.sp .6 +.RS 4n +Directories containing Java programs and libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/jdk\fI*\fR\fR\fR +.ad +.sp .6 +.RS 4n +Java Platform virtual machine and core class libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/kernel\fR\fR +.ad +.sp .6 +.RS 4n +Subtree of platform-dependent loadable kernel modules, not needed in the root +filesystem. An approved installation location for bundled Solaris software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/kvm\fR\fR +.ad +.sp .6 +.RS 4n +A mount point, retained for backward compatibility, that formerly contained +platform-specific binaries and libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent libraries, various databases, commands and daemons not +invoked directly by a human user. An approved installation location for bundled +Solaris software. The analogous location for add-on system software or for +applications is \fB/opt/\fIpackagename\fR/lib\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/32\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to \fB/usr/lib\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/64\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the most portable 64-bit Solaris interfaces, on both SPARC and +x86 platforms. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/acct\fR\fR +.ad +.sp .6 +.RS 4n +Accounting scripts and binaries. See \fBacct\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/adb\fR\fR +.ad +.sp .6 +.RS 4n +\fBadb\fR accounting scripts. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/amd64\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent libraries, various databases, commands and daemons not +invoked directly by a human user on 64-bit x86. An approved installation +location for bundled Solaris software. The analogous location for add-on system +software or for applications is \fB/opt/\fIpackagename\fR/lib/amd64\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/autofs\fR\fR +.ad +.sp .6 +.RS 4n +Contains the \fBautomountd\fR executable. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/cfgadm\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBcfgadm\fR hardware-specific driver plugins. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/class\fR\fR +.ad +.sp .6 +.RS 4n +Scheduling-class-specific directories containing executables for +\fBpriocntl\fR(1) and \fBdispadmin\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/crypto\fR\fR +.ad +.sp .6 +.RS 4n +Contains the kernel-level cryptographic framework daemon (\fBkcfd\fR). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/devfsadm\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBdevfsadm\fR, the daemon version of \fBdevfsadm\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/dict\fR\fR +.ad +.sp .6 +.RS 4n +Database files for \fBspell\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/dtrace\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBdtrace\fR D source files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/fm\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBfmd\fR, the fault manager daemon and the fault manager library. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/font\fR\fR +.ad +.sp .6 +.RS 4n +\fBtroff\fR(1) font description files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/fs\fR\fR +.ad +.sp .6 +.RS 4n +File system type dependent modules; generally not intended to be invoked +directly by the user. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/gss\fR\fR +.ad +.sp .6 +.RS 4n +Secure services-related libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/iconv\fR\fR +.ad +.sp .6 +.RS 4n +Conversion tables for \fBiconv\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/inet\fR\fR +.ad +.sp .6 +.RS 4n +Contains many network-related daemons and libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/ipf\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBIPFILTER.LICENCE\fR and \fBipftest\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/ipqosconf\fR\fR +.ad +.sp .6 +.RS 4n +IPQoS configuration utility. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/krb5\fR\fR +.ad +.sp .6 +.RS 4n +Contains the Kerberos database propagation program and libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/ld\fR\fR +.ad +.sp .6 +.RS 4n +Contains the map files for the \fBld\fR link editor. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/ldap\fR\fR +.ad +.sp .6 +.RS 4n +Contains LDAP client configuration utilities. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/libp\fR\fR +.ad +.sp .6 +.RS 4n +Profiled libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/llc2\fR\fR +.ad +.sp .6 +.RS 4n +Contains logical link control (\fBllc2\fR) driver configuration files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/locale\fR\fR +.ad +.sp .6 +.RS 4n +Localization databases. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/lp\fR\fR +.ad +.sp .6 +.RS 4n +Line printer subsystem databases and back-end executables. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/netsvc\fR\fR +.ad +.sp .6 +.RS 4n +Internet network services. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/nfs\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary NFS-related programs and daemons. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/picl\fR\fR +.ad +.sp .6 +.RS 4n +Platform Information and Control Library. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/pool\fR\fR +.ad +.sp .6 +.RS 4n +Contains the automated resource pools partitioning daemon (\fBpoold\fR) and +associated libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/power\fR\fR +.ad +.sp .6 +.RS 4n +Power management daemon, \fBpowerd\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/print\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBlp\fR conversion scripts and the \fBin.lpd\fR daemon. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/rcap\fR\fR +.ad +.sp .6 +.RS 4n +Resource cap enforcement daemon, \fBrcapd\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/rcm\fR\fR +.ad +.sp .6 +.RS 4n +Contains the Reconfiguration and Coordination Manager daemon (\fBrcm_daemon\fR) +and RCM scripts. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/refer\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary programs for \fBrefer\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/rmmount\fR\fR +.ad +.sp .6 +.RS 4n +Removable media mounter shared objects. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/sa\fR\fR +.ad +.sp .6 +.RS 4n +Scripts and commands for the system activity report package. See \fBsar\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/saf\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary programs and daemons related to the service access facility. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/sasl\fR\fR +.ad +.sp .6 +.RS 4n +Simple Authentication and Security Layer (SASL) plug-in modules. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/secure\fR\fR +.ad +.sp .6 +.RS 4n +Default trusted libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/security\fR\fR +.ad +.sp .6 +.RS 4n +Solaris security plug-in modules. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/smedia\fR\fR +.ad +.sp .6 +.RS 4n +Removable media device server daemon, \fBrpc.smserverd\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +\fBSPARC\fR 64-bit, platform-dependent libraries, various databases, commands +and daemons not invoked directly by a human user. An approved installation +location for bundled Solaris software. The analogous location for add-on system +software or for applications is \fB/opt/\fIpackagename\fR/lib/sparcv9\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/spell\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary programs and databases for \fBspell\fR(1). This directory is only +present when the Binary Compatibility Package is installed. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/\fIsubsystem\fR\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent libraries, various databases, commands and daemons that are +associated with \fIsubsystem\fR and that are not invoked directly by a human +user. An approved installation location for bundled Solaris software. The +analogous location for add-on system software or for applications is +\fB/opt/\fIpackagename\fR/lib\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/\fIsubsystem\fR/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit, platform-dependent libraries, various databases, commands and +daemons that are associated with \fIsubsystem\fR and that are not invoked +directly by a human user. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/lib/amd64\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/\fIsubsystem\fR/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +\fBSPARC\fR 64-bit, platform-dependent libraries, various databases, commands +and daemons that are associated with \fIsubsystem\fR and that are not invoked +directly by a human user. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/lib/sparcv9\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/lib\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent libraries, various databases, commands and daemons not +invoked directly by a human user. An approved installation location for bundled +Solaris software. The analogous location for add-on system software or for +applications is \fB/opt/\fIpackagename\fR/lib\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/lib/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit, platform-dependent libraries, various databases, commands and +daemons that are associated with \fIsubsystem\fR and that are not invoked +directly by a human user. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/lib/amd64\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/lib/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +\fBSPARC\fR 64-bit, platform-dependent libraries, various databases, commands +and daemons that are associated with \fIsubsystem\fR and that are not invoked +directly by a human user. An approved installation location for bundled Solaris +software. The analogous location for add-on system software or for applications +is \fB/opt/\fIpackagename\fR/lib/sparcv9\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/sysevent\fR\fR +.ad +.sp .6 +.RS 4n +Contains the system event notification daemon (\fBsyseventd\fR) and the +\fBsyseventd\fR loadable module (SLM) repository. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/uucp\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary programs and daemons for \fBuucp\fR(1C). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/zones\fR\fR +.ad +.sp .6 +.RS 4n +Zone administration daemon (\fBzoneadmd\fR). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/local\fR\fR +.ad +.sp .6 +.RS 4n +Not part of the SVR4-based Solaris distribution. The \fB/usr\fR directory is +exclusively for software bundled with the Solaris operating system. If needed +for storing machine-local add-on software, create the directory +\fB/opt/local\fR and make \fB/usr/local\fR a symbolic link to \fB/opt/local\fR. +The \fB/opt\fR directory or filesystem is for storing add-on software to the +system. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/mail\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/var/mail\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/man\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/usr/share/man\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/net/servers\fR\fR +.ad +.sp .6 +.RS 4n +Entry points for foreign name service requests relayed using the network +listener. See \fBlisten\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/news\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/var/news\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/old\fR\fR +.ad +.sp .6 +.RS 4n +Programs that are being phased out. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/perl5\fR\fR +.ad +.sp .6 +.RS 4n +Perl 5 programs and documentation +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/platform\fR\fR +.ad +.sp .6 +.RS 4n +Subtree of platform-specific objects which does not need to reside on the root +filesystem. It contains a series of directories, one per supported platform. +The semantics of the series of directories is equivalent to \fB/platform\fR, +except for subdirectories which do not provide utility under one or the other +(for example, \fB/platform/include\fR is not needed). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/platform/\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/include\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to \fB/../\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/include\fR. Platform-specific system (\fBsys\fR, +\fBvm\fR) header files with semantics equivalent to \fB/usr/include\fR. An +approved installation location for bundled Solaris software and for add-on +system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/platform/\fR\fB`\fR\fBuname\fR \fB-i\fR\fB\fR\fB`\fR\fB/lib\fR\fR +.ad +.sp .6 +.RS 4n +Platform-specific shared objects with semantics equivalent to \fB/usr/lib\fR. +An approved installation location for bundled Solaris software and for add-on +system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/platform/\fR\fB`\fR\fBuname\fR +\fB-i\fR\fB\fR\fB`\fR\fB/lib/\fIsubsystem\fR/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit, platform-specific daemon and shared objects. An approved +installation location for bundled Solaris software and for add-on system +software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/platform/\fR\fB`\fR\fBuname\fR \fB-i\fR\fB\fR\fB`\fR\fB/sbin\fR\fR +.ad +.sp .6 +.RS 4n +Platform-specific system administration utilities with semantics equivalent to +\fB/usr/sbin\fR. An approved installation location for bundled Solaris software +and for add-on system software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/preserve\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/var/preserve\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/proc\fR\fR +.ad +.sp .6 +.RS 4n +Former location of the \fBproc\fR(1) tools, now containing compatibility +symbolic links to their new locations in \fB/usr/bin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/pub\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to \fB/share/lib/pub\fR, which contains files for online man page +and character processing. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/sadm\fR\fR +.ad +.sp .6 +.RS 4n +System administration files and directories. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/sadm/install\fR\fR +.ad +.sp .6 +.RS 4n +Executables and scripts for package management. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/sbin\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent executables for system administration, expected to be run +only by system administrators. An approved installation location for bundled +Solaris software. The analogous location for add-on system software or for +applications is \fB/opt/\fIpackagename\fR/sbin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/sbin/sparcv7\fR and \fBsparcv9\fR\fR +.ad +.sp .6 +.RS 4n +32-bit and 64-bit SPARC versions of commands. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/sbin/amd64\fR\fR +.ad +.sp .6 +.RS 4n +64-bit x86 versions of commands. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/sbin/\fIsubsystem\fR\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent executables for system administration, expected to be run +only by system administrators, and associated with \fIsubsystem\fR. An approved +installation location for bundled Solaris software. The analogous location for +add-on system software or for applications is +\fB/opt/\fIpackagename\fR/sbin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/\fIsubsystem\fR/sbin\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent executables for system administration, expected to be run +only by system administrators, and associated with \fIsubsystem\fR. An approved +installation location for bundled Solaris software. The analogous location for +add-on system software or for applications is +\fB/opt/\fIpackagename\fR/sbin\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share\fR\fR +.ad +.sp .6 +.RS 4n +Platform-independent sharable files. An approved installation location for +bundled Solaris software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/aclocal\fR\fR +.ad +.sp .6 +.RS 4n +Open source \fBm4\fR files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/applications\fR\fR +.ad +.sp .6 +.RS 4n +Desktop application files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/audio\fR\fR +.ad +.sp .6 +.RS 4n +Sample audio files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/icons\fR\fR +.ad +.sp .6 +.RS 4n +Desktop icon files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/intltool\fR\fR +.ad +.sp .6 +.RS 4n +XML translation tools. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/ipfilter\fR\fR +.ad +.sp .6 +.RS 4n +Open source IP Filter sample files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib\fR\fR +.ad +.sp .6 +.RS 4n +Platform-independent sharable databases. An approved installation location for +bundled Solaris software. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/dict\fR\fR +.ad +.sp .6 +.RS 4n +Contains word list for \fBspell\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/keytables\fR\fR +.ad +.sp .6 +.RS 4n +Keyboard layout description tables. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/mailx\fR\fR +.ad +.sp .6 +.RS 4n +Help files for \fBmailx\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/nterm\fR\fR +.ad +.sp .6 +.RS 4n +\fBnroff\fR(1) terminal tables. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/pub\fR\fR +.ad +.sp .6 +.RS 4n +Character set data files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tabset\fR\fR +.ad +.sp .6 +.RS 4n +Tab setting escape sequences. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/terminfo\fR\fR +.ad +.sp .6 +.RS 4n +Terminal description files for \fBterminfo\fR(5). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac\fR\fR +.ad +.sp .6 +.RS 4n +Macro packages and related files for text processing tools, for example, +\fBnroff\fR(1) and \fBtroff\fR(1). +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/zoneinfo\fR\fR +.ad +.sp .6 +.RS 4n +Time zone information. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/man\fR\fR +.ad +.sp .6 +.RS 4n +Platform-independent sharable manual pages. An approved installation location +for bundled Solaris software. The analogous location for add-on system software +or for applications is \fB/opt/\fIpackagename\fR/man\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/pixmaps\fR\fR +.ad +.sp .6 +.RS 4n +Desktop icon files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/sounds\fR\fR +.ad +.sp .6 +.RS 4n +Sound files. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/src\fR\fR +.ad +.sp .6 +.RS 4n +Source code for kernel, utilities, and libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/themes\fR\fR +.ad +.sp .6 +.RS 4n +Desktop themes. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/snadm\fR\fR +.ad +.sp .6 +.RS 4n +Files related to system and network administration. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/spool\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/var/spool\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/src\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/usr/share/src\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/tmp\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/var/tmp\fR directory. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/ucb\fR\fR +.ad +.sp .6 +.RS 4n +Berkeley compatibility package binaries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/ucbinclude\fR\fR +.ad +.sp .6 +.RS 4n +Berkeley compatibility package headers. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/ucblib\fR\fR +.ad +.sp .6 +.RS 4n +Berkeley compatibility package libraries. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/xpg4\fR\fR +.ad +.sp .6 +.RS 4n +Directory for POSIX-compliant utilities. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/xpg6\fR\fR +.ad +.sp .6 +.RS 4n +Directory for newer versions of POSIX-compliant utilities. +.RE + +.SH SEE ALSO +.BR at (1), +.BR ex (1), +.BR iconv (1), +.BR isainfo (1), +.BR lp (1), +.BR mail (1), +.BR mailx (1), +.BR nroff (1), +.BR priocntl (1), +.BR refer (1), +.BR sar (1), +.BR sh (1), +.BR spell (1), +.BR svcs (1), +.BR troff (1), +.BR uname (1), +.BR vi (1), +.BR uucp (1C), +.BR mount (2), +.BR ctfs (4FS), +.BR ctfs (4FS), +.BR dev (4FS), +.BR devfs (4FS), +.BR objfs (4FS), +.BR tmpfs (4FS), +.BR Intro (5), +.BR proc (5), +.BR terminfo (5), +.BR smf (7), +.BR acct (8), +.BR cron (8), +.BR dispadmin (8), +.BR dladm (8), +.BR fmd (8), +.BR fsck (8), +.BR init (8), +.BR kernel (8), +.BR mknod (8), +.BR mount (8), +.BR svcadm (8), +.BR svccfg (8), +.BR useradd (8), +.BR ypbind (8) diff --git a/usr/src/man/man7/fnmatch.7 b/usr/src/man/man7/fnmatch.7 new file mode 100644 index 0000000000..51b73312d1 --- /dev/null +++ b/usr/src/man/man7/fnmatch.7 @@ -0,0 +1,341 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved. +.\" +.TH FNMATCH 7 "Jun 14, 2015" +.SH NAME +fnmatch \- file name pattern matching +.SH DESCRIPTION +.LP +The pattern matching notation described below is used to specify patterns for +matching strings in the shell. Historically, pattern matching notation is +related to, but slightly different from, the regular expression notation. For +this reason, the description of the rules for this pattern matching notation is +based on the description of regular expression notation described on the +\fBregex\fR(7) manual page. +.SS "Patterns Matching a Single Character" +.LP +The following patterns match a single character: \fIordinary characters\fR, +\fIspecial pattern characters\fR and \fIpattern bracket expressions\fR. The pattern +bracket expression will also match a single collating element. +.sp +.LP +An ordinary character is a pattern that matches itself. It can be any character +in the supported character set except for \fINUL\fR, those special shell +characters that require quoting, and the following three special pattern +characters. Matching is based on the bit pattern used for encoding the +character, not on the graphic representation of the character. If any character +(ordinary, shell special, or pattern special) is quoted, that pattern will +match the character itself. The shell special characters always require +quoting. +.sp +.LP +When unquoted and outside a bracket expression, the following three characters +will have special meaning in the specification of patterns: +.sp +.ne 2 +.na +\fB\fB?\fR \fR +.ad +.RS 6n +A question-mark is a pattern that will match any character. +.RE + +.sp +.ne 2 +.na +\fB\fB*\fR \fR +.ad +.RS 6n +An asterisk is a pattern that will match multiple characters, as described in +\fBPatterns Matching Multiple Characters\fR, below. +.RE + +.sp +.ne 2 +.na +\fB\fB[\fR \fR +.ad +.RS 6n +The open bracket will introduce a pattern bracket expression. +.RE + +.sp +.LP +The description of basic regular expression bracket expressions on the +\fBregex\fR(7) manual page also applies to the pattern bracket expression, +except that the exclamation-mark character \fB(\fR \fB!\fR \fB)\fR replaces the +circumflex character (\fB^\fR) in its role in a \fInon-matching list\fR in the +regular expression notation. A bracket expression starting with an unquoted +circumflex character produces unspecified results. +.sp +.LP +The restriction on a circumflex in a bracket expression is to allow +implementations that support pattern matching using the circumflex as the +negation character in addition to the exclamation-mark. A portable application +must use something like \fB[\e^!\fR] to match either character. +.sp +.LP +When pattern matching is used where shell quote removal is not performed (such +as in the argument to the \fBfind\fR \fB-name\fR primary when \fBfind\fR is +being called using one of the \fBexec\fR functions, or in the \fIpattern\fR +argument to the \fBfnmatch\fR(3C) function, special characters can be escaped +to remove their special meaning by preceding them with a backslash character. +This escaping backslash will be discarded. The sequence \fB\e\e\fR represents +one literal backslash. All of the requirements and effects of quoting on +ordinary, shell special and special pattern characters will apply to escaping +in this context. +.sp +.LP +Both quoting and escaping are described here because pattern matching must work +in three separate circumstances: +.RS +4 +.TP +.ie t \(bu +.el o +Calling directly upon the shell, such as in pathname expansion or in a +\fBcase\fR statement. All of the following will match the string or file +\fBabc\fR: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBabc\fR \fB"abc"\fR \fBa"b"c\fR \fBa\ebc\fR \fBa[b]c\fR +\fBa["b"]c\fR \fBa[\eb]c\fR \fBa["\eb"]c\fR \fBa?c\fR \fBa*c\fR +.TE + +The following will not: +.sp + +.sp +.TS +l l l . +\fB"a?c"\fR \fBa\e*c\fR \fBa\e[b]c\fR +.TE + +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Calling a utility or function without going through a shell, as described for +\fBfind\fR(1) and the function \fBfnmatch\fR(3C) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Calling utilities such as \fBfind\fR, \fBcpio\fR, \fBtar\fR or \fBpax\fR +through the shell command line. In this case, shell quote removal is performed +before the utility sees the argument. For example, in: +.sp +find /bin -name e\ec[\eh]o -print +.sp +after quote removal, the backslashes are presented to \fBfind\fR and it treats +them as escape characters. Both precede ordinary characters, so the \fBc\fR and +\fBh\fR represent themselves and \fBecho\fR would be found on many historical +systems (that have it in \fB/bin\fR). To find a file name that contained shell +special characters or pattern characters, both quoting and escaping are +required, such as: +.sp +\fBpax -r .\|.\|. "*a\e\|(\|\e?"\fR +.sp +to extract a filename ending with \fBa(?\fR. +.RE +.sp +.LP +Conforming applications are required to quote or escape the shell special +characters (sometimes called metacharacters). If used without this protection, +syntax errors can result or implementation extensions can be triggered. For +example, the KornShell supports a series of extensions based on parentheses in +patterns; see \fBksh\fR(1) +.SS "Patterns Matching Multiple Characters" +.LP +The following rules are used to construct \fIpatterns matching multiple +characters\fR from \fIpatterns matching a single character\fR: +.RS +4 +.TP +.ie t \(bu +.el o +The asterisk (*) is a pattern that will match any string, including the null +string. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The concatenation of \fIpatterns matching a single character\fR is a valid +pattern that will match the concatenation of the single characters or collating +elements matched by each of the concatenated patterns. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The concatenation of one or more \fIpatterns matching a single character\fR +with one or more asterisks is a valid pattern. In such patterns, each asterisk +will match a string of zero or more characters, matching the greatest possible +number of characters that still allows the remainder of the pattern to match +the string. +.RE +.sp +.LP +Since each asterisk matches zero or more occurrences, the patterns \fBa*b\fR +and \fBa**b\fR have identical functionality. +.sp +.LP +Examples: +.sp +.ne 2 +.na +\fB\fBa[bc]\fR \fR +.ad +.RS 10n +matches the strings \fBab\fR and \fBac\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBa*d\fR \fR +.ad +.RS 10n +matches the strings \fBad\fR, \fBabd\fR and \fBabcd\fR, but not the string +\fBabc\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBa*d*\fR \fR +.ad +.RS 10n +matches the strings \fBad\fR, \fBabcd\fR, \fBabcdef\fR, \fBaaaad\fR and +\fBadddd\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB*a*d\fR \fR +.ad +.RS 10n +matches the strings \fBad\fR, \fBabcd\fR, \fBefabcd\fR, \fBaaaad\fR and +\fBadddd\fR. +.RE + +.SS "Patterns Used for Filename Expansion" +.LP +The rules described so far in \fBPatterns\fR \fBMatching\fR \fBMultiple\fR +\fBCharacters\fR and \fBPatterns\fR \fBMatching\fR \fBa\fR \fBSingle\fR +\fBCharacter\fR are qualified by the following rules that apply when pattern +matching notation is used for filename expansion. +.RS +4 +.TP +1. +The slash character in a pathname must be explicitly matched by using one +or more slashes in the pattern; it cannot be matched by the asterisk or +question-mark special characters or by a bracket expression. Slashes in the +pattern are identified before bracket expressions; thus, a slash cannot be +included in a pattern bracket expression used for filename expansion. For +example, the pattern \fBa[b/c]d\fR will not match such pathnames as \fBabd\fR +or \fBa/d\fR. It will only match a pathname of literally \fBa[b/c]d\fR. +.RE +.RS +4 +.TP +2. +If a filename begins with a period (.), the period must be explicitly +matched by using a period as the first character of the pattern or immediately +following a slash character. The leading period will not be matched by: +.sp +\(bu the asterisk or question-mark special characters +.sp +\(bu a bracket expression containing a non-matching list, such as: +.sp +\fB[!a]\fR +.sp +a range expression, such as: +.sp +\fB[%\(mi0]\fR +.sp +or a character class expression, such as: +.sp +\fB[[:punct:]]\fR +.sp +It is unspecified whether an explicit period in a bracket expression matching +list, such as: +.sp +\fB[.abc]\fR +.sp +can match a leading period in a filename. +.RE +.RS +4 +.TP +3. +Specified patterns are matched against existing filenames and pathnames, as +appropriate. Each component that contains a pattern character requires read +permission in the directory containing that component. Any component, except +the last, that does not contain a pattern character requires search permission. +For example, given the pattern: +.sp +\fB/foo/bar/x*/bam\fR +.sp +search permission is needed for directories \fB/\fR and \fBfoo\fR, search and +read permissions are needed for directory \fBbar\fR, and search permission is +needed for each \fBx*\fR directory. +.sp +If the pattern matches any existing filenames or pathnames, the pattern will be +replaced with those filenames and pathnames, sorted according to the collating +sequence in effect in the current locale. If the pattern contains an invalid +bracket expression or does not match any existing filenames or pathnames, the +pattern string is left unchanged. +.RE +.SH SEE ALSO +.LP +.BR find (1), +.BR ksh (1), +.BR fnmatch (3C), +.BR regex (7) diff --git a/usr/src/man/man7/formats.7 b/usr/src/man/man7/formats.7 new file mode 100644 index 0000000000..1d9c7bf0b0 --- /dev/null +++ b/usr/src/man/man7/formats.7 @@ -0,0 +1,481 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved. +.\" +.TH FORMATS 7 "Mar 28, 1995" +.SH NAME +formats \- file format notation +.SH DESCRIPTION +.sp +.LP +Utility descriptions use a syntax to describe the data organization within +files\(emstdin, stdout, stderr, input files, and output files\(emwhen that +organization is not otherwise obvious. The syntax is similar to that used by +the \fBprintf\fR(3C) function. When used for stdin or input file +descriptions, this syntax describes the format that could have been used to +write the text to be read, not a format that could be used by the +\fBscanf\fR(3C) function to read the input file. +.SS "Format" +.sp +.LP +The description of an individual record is as follows: +.sp +.in +2 +.nf +"<\fBformat\fR>", [<\fIarg1\fR>, <\fIarg2\fR>, .\|.\|., <\fIargn\fR>] +.fi +.in -2 + +.sp +.LP +The \fBformat\fR is a character string that contains three types of objects +defined below: +.sp +.ne 2 +.na +\fB\fI\fR\fIcharacters\fR\fI\fR \fR +.ad +.RS 30n +Characters that are not \fIescape sequences\fR or \fIconversion +specifications\fR, as described below, are copied to the output. +.RE + +.sp +.ne 2 +.na +\fB\fI\fR\fIescape sequences\fR\fI\fR \fR +.ad +.RS 30n +Represent non-graphic characters. +.RE + +.sp +.ne 2 +.na +\fB\fI\fR\fIconversion specifications\fR\fI\fR \fR +.ad +.RS 30n +Specifies the output format of each argument. (See below.) +.RE + +.sp +.LP +The following characters have the following special meaning in the format +string: +.sp +.ne 2 +.na +\fB`` \&''\fR +.ad +.RS 11n +(An empty character position.) One or more blank characters. +.RE + +.sp +.ne 2 +.na +\fB/\e \fR +.ad +.RS 11n +Exactly one space character. +.RE + +.sp +.LP +The notation for spaces allows some flexibility for application output. Note +that an empty character position in \fBformat\fR represents one or more blank +characters on the output (not \fIwhite space\fR, which can include newline +characters). Therefore, another utility that reads that output as its input +must be prepared to parse the data using \fBscanf\fR(3C), \fBawk\fR(1), and so +forth. The character is used when exactly one space character is output. +.SS "Escape Sequences" +.sp +.LP +The following table lists escape sequences and associated actions on display +devices capable of the action. +.sp + +.sp +.TS +c c c +l l l . +\fBSequence\fR \fBCharacter\fR \fBTerminal Action\fR +_ +\fB\e\e\fR backslash None. +\fB\ea\fR alert T{ +Attempts to alert the user through audible or visible notification. +T} +\fB\eb\fR backspace T{ +Moves the printing position to one column before the current position, unless the current position is the start of a line. +T} +\fB\ef\fR form-feed T{ +Moves the printing position to the initial printing position of the next logical page. +T} +\fB\en\fR newline T{ +Moves the printing position to the start of the next line. +T} +\fB\er\fR carriage-return T{ +Moves the printing position to the start of the current line. +T} +\fB\et\fR tab T{ +Moves the printing position to the next tab position on the current line. If there are no more tab positions left on the line, the behavior is undefined. +T} +\fB\ev\fR vertical-tab T{ +Moves the printing position to the start of the next vertical tab position. If there are no more vertical tab positions left on the page, the behavior is undefined. +T} +.TE + +.SS "Conversion Specifications" +.sp +.LP +Each conversion specification is introduced by the percent-sign character (%). +After the character %, the following appear in sequence: +.sp +.ne 2 +.na +\fB\fI\fR\fIflags\fR\fI\fR \fR +.ad +.RS 26n +Zero or more \fIflags\fR, in any order, that modify the meaning of the +conversion specification. +.RE + +.sp +.ne 2 +.na +\fB\fI\fR\fIfield width\fR\fI\fR \fR +.ad +.RS 26n +An optional string of decimal digits to specify a minimum \fIfield width\fR. +For an output field, if the converted value has fewer bytes than the field +width, it is padded on the left (or right, if the left-adjustment flag (\(mi), +described below, has been given to the field width). +.RE + +.sp +.ne 2 +.na +\fB\fI\fR\fIprecision\fR\fI\fR \fR +.ad +.RS 26n +Gives the minimum number of digits to appear for the d, o, i, u, x or X +conversions (the field is padded with leading zeros), the number of digits to +appear after the radix character for the e and f conversions, the maximum +number of significant digits for the g conversion; or the maximum number of +bytes to be written from a string in s conversion. The precision takes the form +of a period (.) followed by a decimal digit string; a null digit string is +treated as zero. +.RE + +.sp +.ne 2 +.na +\fB\fI\fR\fIconversion characters\fR\fI\fR \fR +.ad +.RS 26n +A conversion character (see below) that indicates the type of conversion to be +applied. +.RE + +.SS "\fIflags\fR" +.sp +.LP +The \fIflags\fR and their meanings are: +.sp +.ne 2 +.na +\fB\fI\(mi\fR \fR +.ad +.RS 12n +The result of the conversion is left-justified within the field. +.RE + +.sp +.ne 2 +.na +\fB\fI+\fR \fR +.ad +.RS 12n +The result of a signed conversion always begins with a sign (+ or \(mi). +.RE + +.sp +.ne 2 +.na +\fB\fI<space>\fR \fR +.ad +.RS 12n +If the first character of a signed conversion is not a sign, a space character +is prefixed to the result. This means that if the space character and + flags +both appear, the space character flag is ignored. +.RE + +.sp +.ne 2 +.na +\fB\fI#\fR \fR +.ad +.RS 12n +The value is to be converted to an alternative form. For c, d, i, u, and s +conversions, the behaviour is undefined. For o conversion, it increases the +precision to force the first digit of the result to be a zero. For x or X +conversion, a non-zero result has 0x or 0X prefixed to it, respectively. For e, +E, f, g, and G conversions, the result always contains a radix character, even +if no digits follow the radix character. For g and G conversions, trailing +zeros are not removed from the result as they usually are. +.RE + +.sp +.ne 2 +.na +\fB\fI0\fR \fR +.ad +.RS 12n +For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros (following +any indication of sign or base) are used to pad to the field width; no space +padding is performed. If the 0 and \(mi flags both appear, the 0 flag is +ignored. For d, i, o, u, x and X conversions, if a precision is specified, the +0 flag is ignored. For other conversions, the behaviour is undefined. +.RE + +.SS "Conversion Characters" +.sp +.LP +Each conversion character results in fetching zero or more arguments. The +results are undefined if there are insufficient arguments for the format. If +the format is exhausted while arguments remain, the excess arguments are +ignored. +.sp +.LP +The \fIconversion characters\fR and their meanings are: +.sp +.ne 2 +.na +\fB\fId,i,o,u,x,X\fR \fR +.ad +.RS 16n +The integer argument is written as signed decimal (d or i), unsigned octal (o), +unsigned decimal (u), or unsigned hexadecimal notation (x and X). The d and i +specifiers convert to signed decimal in the style \fB[\fR\(mi\fB]\fR\fIdddd\fR. +The x conversion uses the numbers and letters 0123456789abcdef and the X +conversion uses the numbers and letters 0123456789ABCDEF. The \fIprecision\fR +component of the argument specifies the minimum number of digits to appear. If +the value being converted can be represented in fewer digits than the specified +minimum, it is expanded with leading zeros. The default precision is 1. The +result of converting a zero value with a precision of 0 is no characters. If +both the field width and precision are omitted, the implementation may precede, +follow or precede and follow numeric arguments of types d, i and u with blank +characters; arguments of type o (octal) may be preceded with leading zeros. +.sp +The treatment of integers and spaces is different from the \fBprintf\fR(3C) +function in that they can be surrounded with blank characters. This was done so +that, given a format such as: +.sp +.in +2 +.nf +"%d\en",<\fIfoo\fR> +.fi +.in -2 + +the implementation could use a \fBprintf()\fR call such as: +.sp +.in +2 +.nf +printf("%6d\en", \fIfoo\fR); +.fi +.in -2 + +and still conform. This notation is thus somewhat like \fBscanf()\fR in +addition to \fBprintf(\|).\fR +.RE + +.sp +.ne 2 +.na +\fB\fIf\fR \fR +.ad +.RS 16n +The floating point number argument is written in decimal notation in the style +\fB[\fR\(mi\fB]\fR\fIddd\fR.\fIddd\fR, where the number of digits after the +radix character (shown here as a decimal point) is equal to the \fIprecision\fR +specification. The \fBLC_NUMERIC\fR locale category determines the radix +character to use in this format. If the \fIprecision\fR is omitted from the +argument, six digits are written after the radix character; if the +\fIprecision\fR is explicitly 0, no radix character appears. +.RE + +.sp +.ne 2 +.na +\fB\fIe,E\fR \fR +.ad +.RS 16n +The floating point number argument is written in the style +\fB[\fR\(mi\fB]\fR\fId\fR.\fIddd\fRe\(+-\fBdd\fR (the symbol \(+- indicates +either a plus or minus sign), where there is one digit before the radix +character (shown here as a decimal point) and the number of digits after it is +equal to the precision. The \fBLC_NUMERIC\fR locale category determines the +radix character to use in this format. When the precision is missing, six +digits are written after the radix character; if the precision is 0, no radix +character appears. The E conversion character produces a number with E instead +of e introducing the exponent. The exponent always contains at least two +digits. However, if the value to be written requires an exponent greater than +two digits, additional exponent digits are written as necessary. +.RE + +.sp +.ne 2 +.na +\fB\fIg,G\fR \fR +.ad +.RS 16n +The floating point number argument is written in style f or e (or in style E in +the case of a G conversion character), with the precision specifying the number +of significant digits. The style used depends on the value converted: style g +is used only if the exponent resulting from the conversion is less than \(mi4 +or greater than or equal to the precision. Trailing zeros are removed from the +result. A radix character appears only if it is followed by a digit. +.RE + +.sp +.ne 2 +.na +\fB\fIc\fR \fR +.ad +.RS 16n +The integer argument is converted to an \fBunsigned char\fR and the resulting +byte is written. +.RE + +.sp +.ne 2 +.na +\fB\fIs\fR \fR +.ad +.RS 16n +The argument is taken to be a string and bytes from the string are written +until the end of the string or the number of bytes indicated by the +\fIprecision\fR specification of the argument is reached. If the precision is +omitted from the argument, it is taken to be infinite, so all bytes up to the +end of the string are written. +.RE + +.sp +.ne 2 +.na +\fB\fI%\fR \fR +.ad +.RS 16n +Write a % character; no argument is converted. +.RE + +.sp +.LP +In no case does a non-existent or insufficient \fIfield width\fR cause +truncation of a field; if the result of a conversion is wider than the field +width, the field is simply expanded to contain the conversion result. The term +\fIfield width\fR should not be confused with the term \fIprecision\fR used in +the description of %s. +.sp +.LP +One difference from the C function \fBprintf()\fR is that the l and h +conversion characters are not used. There is no differentiation between decimal +values for type \fBint\fR, type \fBlong\fR, or type \fBshort\fR. The +specifications %d or %i should be interpreted as an arbitrary length sequence +of digits. Also, no distinction is made between single precision and double +precision numbers (\fBfloat\fR or \fBdouble\fR in C). These are simply +referred to as floating point numbers. +.sp +.LP +Many of the output descriptions use the term \fBline\fR, such as: +.sp +.in +2 +.nf +"%s", <\fIinput line\fR> +.fi +.in -2 + +.sp +.LP +Since the definition of \fBline\fR includes the trailing newline character +already, there is no need to include a \fB\en\fR in the format; a double +newline character would otherwise result. +.SH EXAMPLES +.LP +\fBExample 1 \fRTo represent the output of a program that prints a date and +time in the form Sunday, July 3, 10:02, where \fI<weekday>\fR and \fI<month>\fR +are strings: +.sp +.in +2 +.nf +"%s,/\e%s/\e%d,/\e%d:%.2d\en",<\fIweekday\fR>,<\fImonth\fR>,<\fIday\fR>,<\fIhour\fR>,<\fImin\fR> +.fi +.in -2 + +.LP +\fBExample 2 \fRTo show pi written to 5 decimal places: +.sp +.in +2 +.nf +"pi/\e=/\e%.5f\en",<\fIvalue of pi\fR> +.fi +.in -2 + +.LP +\fBExample 3 \fRTo show an input file format consisting of five colon-separated +fields: +.sp +.in +2 +.nf +"%s:%s:%s:%s:%s\en",<\fIarg1\fR>,<\fIarg2\fR>,<\fIarg3\fR>,<\fIarg4\fR>,<\fIarg5\fR> +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +.BR awk (1), +.BR printf (1), +.BR printf (3C), +.BR scanf (3C) diff --git a/usr/src/man/man7/fsattr.7 b/usr/src/man/man7/fsattr.7 new file mode 100644 index 0000000000..4691e5eab6 --- /dev/null +++ b/usr/src/man/man7/fsattr.7 @@ -0,0 +1,812 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH FSATTR 7 "Oct 10, 2007" +.SH NAME +fsattr \- extended file attributes +.SH DESCRIPTION +.sp +.LP +Attributes are logically supported as files within the file system. The file +system is therefore augmented with an orthogonal name space of file attributes. +Any file (including attribute files) can have an arbitrarily deep attribute +tree associated with it. Attribute values are accessed by file descriptors +obtained through a special attribute interface. This logical view of +"attributes as files" allows the leveraging of existing file system interface +functionality to support the construction, deletion, and manipulation of +attributes. +.sp +.LP +The special files "." and ".\|." retain their accustomed semantics within the +attribute hierarchy. The "." attribute file refers to the current directory +and the ".\|." attribute file refers to the parent directory. The unnamed +directory at the head of each attribute tree is considered the "child" of the +file it is associated with and the ".\|." file refers to the associated file. +For any non-directory file with attributes, the ".\|." entry in the unnamed +directory refers to a file that is not a directory. +.sp +.LP +Conceptually, the attribute model is fully general. Extended attributes can be +any type of file (doors, links, directories, and so forth) and can even have +their own attributes (fully recursive). As a result, the attributes associated +with a file could be an arbitrarily deep directory hierarchy where each +attribute could have an equally complex attribute tree associated with it. Not +all implementations are able to, or want to, support the full model. +Implementation are therefore permitted to reject operations that are not +supported. For example, the implementation for the UFS file system allows only +regular files as attributes (for example, no sub-directories) and rejects +attempts to place attributes on attributes. +.sp +.LP +The following list details the operations that are rejected in the current +implementation: +.sp +.ne 2 +.na +\fB\fBlink\fR\fR +.ad +.RS 25n +Any attempt to create links between attribute and non-attribute space is +rejected to prevent security-related or otherwise sensitive attributes from +being exposed, and therefore manipulable, as regular files. +.RE + +.sp +.ne 2 +.na +\fB\fBrename\fR\fR +.ad +.RS 25n +Any attempt to rename between attribute and non-attribute space is rejected to +prevent an already linked file from being renamed and thereby circumventing the +\fBlink\fR restriction above. +.RE + +.sp +.ne 2 +.na +\fB\fBmkdir\fR, \fBsymlink\fR, \fBmknod\fR\fR +.ad +.RS 25n +Any attempt to create a "non-regular" file in attribute space is rejected to +reduce the functionality, and therefore exposure and risk, of the initial +implementation. +.RE + +.sp +.LP +The entire available name space has been allocated to "general use" to bring +the implementation in line with the NFSv4 draft standard [NFSv4]. That standard +defines "named attributes" (equivalent to Solaris Extended Attributes) with no +naming restrictions. All Sun applications making use of opaque extended +attributes will use the prefix "SUNW". +.SS "Shell-level API" +.sp +.LP +The command interface for extended attributes is the set of applications +provided by Solaris for the manipulation of attributes from the command line. +This interface consists of a set of existing utilities that have been extended +to be "attribute-aware", plus the \fBrunat\fR utility designed to "expose" the +extended attribute space so that extended attributes can be manipulated as +regular files. +.sp +.LP +The \fB-@\fR option enable utilities to manipulate extended attributes. As a +rule, this option enables the utility to enter into attribute space when the +utility is performing a recursive traversal of file system space. This is a +fully recursive concept. If the underlying file system supports recursive +attributes and directory structures, the \fB-@\fR option opens these spaces to +the file tree-walking algorithms. +.sp +.LP +The following utilities accommodate extended attributes (see the individual +manual pages for details): +.sp +.ne 2 +.na +\fB\fBcp\fR\fR +.ad +.RS 8n +By default, \fBcp\fR ignores attributes and copies only file data. This is +intended to maintain the semantics implied by \fBcp\fR currently, where +attributes (such as owner and mode) are not copied unless the \fB-p\fR option +is specified. With the \fB-@\fR (or \fB-p\fR) option, \fBcp\fR attempts to copy +all attributes along with the file data. +.RE + +.sp +.ne 2 +.na +\fB\fBcpio\fR\fR +.ad +.RS 8n +The \fB-@\fR option informs \fBcpio\fR to archive attributes, but by default +\fBcpio\fR ignores extended attributes. See \fBExtended Archive Formats\fR +below for a description of the new archive records. +.RE + +.sp +.ne 2 +.na +\fB\fBdu\fR\fR +.ad +.RS 8n +File sizes computed include the space allocated for any extended attributes +present. +.RE + +.sp +.ne 2 +.na +\fB\fBfind\fR\fR +.ad +.RS 8n +By default, \fBfind\fR ignores attributes. The \fB-xattr\fR expression +provides support for searches involving attribute space. It returns true if +extended attributes are present on the current file. +.RE + +.sp +.ne 2 +.na +\fB\fBfsck\fR\fR +.ad +.RS 8n +The \fBfsck\fR utility manages extended attribute data on the disk. A file +system with extended attributes can be mounted on versions of Solaris that are +not attribute-aware (versions prior to Solaris 9), but the attributes will not +be accessible and \fBfsck\fR will strip them from the files and place them in +\fBlost+found\fR. Once the attributes have been stripped the file system is +completely stable on Solaris versions that are not attribute-aware, but would +now be considered corrupted on attribute-aware versions of Solaris. The +attribute-aware \fBfsck\fR utility should be run to stabilize the file system +before using it in an attribute-aware environment. +.RE + +.sp +.ne 2 +.na +\fB\fBfsdb\fR\fR +.ad +.RS 8n +This \fBfsdb\fR utility is able to find the inode for the "hidden" extended +attribute directory. +.RE + +.sp +.ne 2 +.na +\fB\fBls\fR\fR +.ad +.RS 8n +The \fBls\fR \fB-@\fR command displays an "@" following the mode information +when extended attributes are present. More precisely, the output line for a +given file contains an "@" character following the mode characters if the +\fBpathconf\fR(2) variable \fBXATTR_EXISTS\fR is set to true. See the +\fBpathconf()\fR section below. The \fB-@\fR option uses the same general +output format as the \fB-l\fR option. +.RE + +.sp +.ne 2 +.na +\fB\fBmv\fR\fR +.ad +.RS 8n +When a file is moved, all attributes are carried along with the file rename. +When a file is moved across a file system boundary, the copy command invoked is +similar to the \fBcp\fR \fB-p\fR variant described above and extended +attributes are "moved". If the extended file attributes cannot be replicated, +the move operation fails and the source file is not removed. +.RE + +.sp +.ne 2 +.na +\fB\fBpax\fR\fR +.ad +.RS 8n +The \fB-@\fR option informs \fBpax\fR to archive attributes, but by default +\fBpax\fR ignores extended attributes. The \fBpax\fR(1) utility is a generic +replacement for both \fBtar\fR(1) and \fBcpio\fR(1) and is able to produce +either output format in its archive. See \fBExtended Archive Formats\fR below +for a description of the new archive records. +.RE + +.sp +.ne 2 +.na +\fB\fBtar\fR\fR +.ad +.RS 8n +In the default case, \fBtar\fR does not attempt to place attributes in the +archive. If the \fB-@\fR option is specified, however, \fBtar\fR traverses +into the attribute space of all files being placed in the archive and attempts +to add the attributes to the archive. A new record type has been introduced for +extended attribute entries in \fBtar\fR archive files (the same is true for +\fBpax\fR and \fBcpio\fR archives) similar to the way ACLs records were +defined. See \fBExtended Archive Formats\fR below for a description of the new +archive records. +.RE + +.sp +.LP +There is a class of utilities (\fBchmod\fR, \fBchown\fR, \fBchgrp\fR) that one +might expect to be modified in a manner similar to those listed above. For +example, one might expect that performing \fBchmod\fR on a file would not only +affect the file itself but would also affect at least the extended attribute +directory if not any existing extended attribute files. This is not the case. +The model chosen for extended attributes implies that the attribute directory +and the attributes themselves are all file objects in their own right, and can +therefore have independent file status attributes associated with them (a +given implementation cannot support this, for example, for intrinsic +attributes). The relationship is left undefined and a fine-grained control +mechanism (\fBrunat\fR(1)) is provided to allow manipulation of extended +attribute status attributes as necessary. +.sp +.LP +The \fBrunat\fR utility has the following syntax: +.sp +.in +2 +.nf +runat \fIfilename\fR [\fIcommand\fR] +.fi +.in -2 +.sp + +.sp +.LP +The \fBrunat\fR utility executes the supplied command in the context of the +"attribute space" associated with the indicated file. If no command argument +is supplied, a shell is invoked. See \fBrunat\fR(1) for details. +.SS "Application-level API" +.sp +.LP +The primary interface required to access extended attributes at the +programmatic level is the \fBopenat\fR(2) function. Once a file descriptor has +been obtained for an attribute file by an \fBopenat()\fR call, all normal file +system semantics apply. There is no attempt to place special semantics on +\fBread\fR(2), \fBwrite\fR(2), \fBftruncate\fR(3C), or other functions when +applied to attribute file descriptors relative to "normal" file descriptors. +.sp +.LP +The set of existing attributes can be browsed by calling \fBopenat()\fR with +"." as the file name and the \fBO_XATTR\fR flag set, resulting in a file +descriptor for the attribute directory. The list of attributes is obtained by +calls to \fBgetdents\fR(2) on the returned file descriptor. If the target file +did not previously have any attributes associated with it, an empty top-level +attribute directory is created for the file and subsequent \fBgetdents()\fR +calls will return only "." and ".\|.". While the owner of the parent file owns +the extended attribute directory, it is not charged against its quota if the +directory is empty. Attribute files themselves, however, are charged against +the user quota as any other regular file. +.sp +.LP +Additional system calls have been provided as convenience functions. These +include the \fBfchownat\fR(2), \fBfstatat\fR(2), \fBfutimesat\fR(2), +\fBrenameat\fR(2), \fBunlinkat\fR(2). These new functions, along with +\fBopenat()\fR, provide a mechanism to access files relative to an arbitrary +point in the file system, rather than only the current working directory. This +mechanism is particularly useful in situations when a file descriptor is +available with no path. The \fBopenat()\fR function, in particular, can be used +in many contexts where \fBchdir()\fR or \fBfchdir()\fR is currently required. +See \fBchdir\fR(2). +.SS "Open a file relative to a file descriptor" +.sp +.in +2 +.nf +int openat (int \fIfd\fR, const char *\fIpath\fR, int \fIoflag\fR [, mode_t \fImode\fR]) +.fi +.in -2 + +.sp +.LP +The \fBopenat\fR(2) function behaves exactly as \fBopen\fR(2) except when given +a relative path. Where \fBopen()\fR resolves a relative path from the current +working directory, \fBopenat()\fR resolves the path based on the vnode +indicated by the supplied file descriptor. When \fIoflag\fR is \fBO_XATTR\fR, +\fBopenat()\fR interprets the \fIpath\fR argument as an extended attribute +reference. The following code fragment uses \fBopenat()\fR to examine the +attributes of some already opened file: +.sp +.in +2 +.nf +dfd = openat(fd, ".", O_RDONLY|O_XATTR); +(void)getdents(dfd, buf, nbytes); +.fi +.in -2 + +.sp +.LP +If \fBopenat()\fR is passed the special value \fBAT_FDCWD\fR as its first +(\fIfd\fR) argument, its behavior is identical to \fBopen()\fR and the relative +path arguments are interpreted relative to the current working directory. If +the \fBO_XATTR\fR flag is provided to \fBopenat()\fR or to \fBopen()\fR, the +supplied path is interpreted as a reference to an extended attribute on the +current working directory. +.SS "Unlink a file relative to a directory file descriptor" +.sp +.in +2 +.nf +int unlinkat (int \fIdirfd\fR, const char *path\fIflag\fR, int flag\fIflag\fR) +.fi +.in -2 + +.sp +.LP +The \fBunlinkat\fR(2) function deletes an entry from a directory. The +\fIpath\fR argument indicates the name of the entry to remove. If \fIpath\fR an +absolute path, the \fIdirfd\fR argument is ignored. If it is a relative path, +it is interpreted relative to the directory indicated by the \fIdirfd\fR +argument. If \fIdirfd\fR does not refer to a valid directory, the function +returns \fBENOTDIR\fR. If the special value \fBAT_FDCWD\fR is specified for +\fIdirfd\fR, a relative path argument is resolved relative to the current +working directory. If the \fIflag\fR argument is 0, all other semantics of +this function are equivalent to \fBunlink\fR(2). If \fIflag\fR is set to +\fBAT_REMOVEDIR\fR, all other semantics of this function are equivalent to +\fBrmdir\fR(2). +.SS "Rename a file relative to directories" +.sp +.in +2 +.nf +int renameat (int \fIfromfd\fR, const char *\fIold\fR, int \fItofd\fR, const char *\fInew\fR) +.fi +.in -2 + +.sp +.LP +The \fBrenameat\fR(2) function renames an entry in a directory, possibly moving +the entry into a different directory. The \fIold\fR argument indicates the +name of the entry to rename. If this argument is a relative path, it is +interpreted relative to the directory indicated by the \fIfd\fR argument. If it +is an absolute path, the \fIfromfd\fR argument is ignored. The \fInew\fR +argument indicates the new name for the entry. If this argument is a relative +path, it is interpreted relative to the directory indicated by the \fItofd\fR +argument. If it is an absolute path, the \fItofd\fR argument is ignored. +.sp +.LP +In the relative path cases, if the directory file descriptor arguments do not +refer to a valid directory, the function returns \fBENOTDIR\fR. All other +semantics of this function are equivalent to \fBrename\fR(2). +.sp +.LP +If a special value \fBAT_FDCWD\fR is specified for either the \fIfromfd\fR or +\fItofd\fR arguments, their associated path arguments (\fIold\fR and \fInew\fR) +are interpreted relative to the current working directory if they are not +specified as absolute paths. Any attempt to use \fBrenameat()\fR to move a file +that is not an extended attribute into an extended attribute directory (so that +it becomes an extended attribute) will fail. The same is true for an attempt to +move a file that is an extended attribute into a directory that is not an +extended attribute directory. +.SS "Obtain information about a file" +.sp +.in +2 +.nf +int fstatat (int \fIfd\fR, const char *\fIpath\fR, struct stat* \fIbuf\fR, int \fIflag\fR) +.fi +.in -2 + +.sp +.LP +The \fBfstatat\fR(2) function obtains information about a file. If the +\fIpath\fR argument is relative, it is resolved relative to the \fIfd\fR +argument file descriptor, otherwise the \fIfd\fR argument is ignored. If the +\fIfd\fR argument is a special value \fBAT_FDCWD\fR the path is resolved +relative to the current working directory. If the \fIpath\fR argument is a +null pointer, the function returns information about the file referenced by the +\fIfd\fR argument. In all other relative path cases, if the \fIfd\fR argument +does not refer to a valid directory, the function returns \fBENOTDIR\fR. If +\fBAT_SYMLINK_NOFOLLOW\fR is set in the \fIflag\fR argument, the function will +not automatically traverse a symbolic link at the position of the path. If +\fB_AT_TRIGGER\fR is set in the \fIflag\fR argument and the vnode is a trigger +mount point, the mount is performed and the function returns the attributes of +the root of the mounted filesystem. The \fBfstatat()\fR function is a +multipurpose function that can be used in place of \fBstat()\fR, \fBlstat()\fR, +or \fBfstat()\fR. See \fBstat\fR(2) +.sp +.LP +The function call \fBstat(\fR\fIpath\fR\fB,\fR \fIbuf\fR\fB)\fR is identical to +\fBfstatat(AT_FDCWD\fR, \fIpath\fR\fB,\fR \fIbuf\fR\fB, 0)\fR. +.sp +.LP +The function call \fBlstat(\fR\fIpath\fR\fB,\fR \fIbuf\fR\fB)\fR is identical +to \fBfstatat(AT_FDCWD\fR, \fIpath\fR\fB,\fR \fIbuf\fR, +\fBAT_SYMLINK_NOFOLLOW)\fR +.sp +.LP +The function call \fBfstat(\fR\fIfildes\fR\fB,\fR \fIbuf\fR\fB)\fR is identical +to \fBfstatat(\fR\fIfildes\fR, \fBNULL\fR, \fIbuf\fR, \fB0)\fR. +.SS "Set owner and group ID" +.sp +.in +2 +.nf +int fchownat (int \fIfd\fR, const char *\fIpath\fR, uid_t \fIowner\fR, gid_t \fIgroup\fR, \e + int \fIflag\fR) +.fi +.in -2 + +.sp +.LP +The \fBfchownat\fR(2) function sets the owner ID and group ID for a file. If +the \fIpath\fR argument is relative, it is resolved relative to the \fIfd\fR +argument file descriptor, otherwise the \fIfd\fR argument is ignored. If the +\fIfd\fR argument is a special value \fBAT_FDCWD\fR the path is resolved +relative to the current working directory. If the path argument is a null +pointer, the function sets the owner and group ID of the file referenced by the +\fIfd\fR argument. In all other relative path cases, if the \fIfd\fR argument +does not refer to a valid directory, the function returns \fBENOTDIR\fR. If the +\fIflag\fR argument is set to \fBAT_SYMLINK_NOFOLLOW\fR, the function will not +automatically traverse a symbolic link at the position of the path. The +\fBfchownat()\fR function is a multi-purpose function that can be used in place +of \fBchown()\fR, \fBlchown()\fR, or \fBfchown()\fR. See \fBchown\fR(2). +.sp +.LP +The function call \fBchown(\fR\fIpath\fR\fB,\fR \fIowner\fR\fB,\fR +\fIgroup\fR\fB)\fR is equivalent to \fBfchownat(AT_FDCWD\fR, \fIpath\fR\fB,\fR +\fIowner\fR\fB,\fR \fIgroup\fR\fB, 0)\fR. +.sp +.LP +The function call \fBlchown(\fR\fIpath\fR\fB,\fR \fIowner\fR\fB,\fR +\fIgroup\fR\fB)\fR is equivalent to \fBfchownat(AT_FDCWD\fR, \fIpath\fR\fB,\fR +\fIowner\fR\fB,\fR \fIgroup\fR\fB, AT_SYMLINK_NOFOLLOW)\fR. +.SS "Set file access and modification times" +.sp +.in +2 +.nf +int futimesat (int \fIfd\fR, const char *\fIpath\fR, const struct timeval \e + \fItimes\fR[2]) +.fi +.in -2 + +.sp +.LP +The \fBfutimesat\fR(2) function sets the access and modification times for a +file. If the \fIpath\fR argument is relative, it is resolved relative to the +\fIfd\fR argument file descriptor; otherwise the \fIfd\fR argument is ignored. +If the \fIfd\fR argument is the special value \fBAT_FDCWD\fR, the path is +resolved relative to the current working directory. If the \fIpath\fR argument +is a null pointer, the function sets the access and modification times of the +file referenced by the \fIfd\fR argument. In all other relative path cases, if +the \fIfd\fR argument does not refer to a valid directory, the function returns +\fBENOTDIR\fR. The \fBfutimesat()\fR function can be used in place of +\fButimes\fR(2). +.sp +.LP +The function call \fButimes(\fR\fIpath\fR\fB,\fR \fItimes\fR\fB)\fR is +equivalent to \fBfutimesat(AT_FDCWD\fR, \fIpath\fR\fB,\fR \fItimes\fR\fB)\fR. +.SS "New pathconf() functionality" +.sp +.in +2 +.nf +long int pathconf(const char *\fIpath\fR, int \fIname\fR) +.fi +.in -2 + +.sp +.LP +Two variables have been added to \fBpathconf\fR(2) to provide enhanced support +for extended attribute manipulation. The \fBXATTR_ENABLED\fR variable allows an +application to determine if attribute support is currently enabled for the file +in question. The \fBXATTR_EXISTS\fR variable allows an application to determine +whether there are any extended attributes associated with the supplied path. +.SS "Open/Create an attribute file" +.sp +.in +2 +.nf +int attropen (const char *\fIpath\fR, const char *\fIattrpath\fR, int \fIoflag\fR \e + [, mode_t \fImode\fR]) +.fi +.in -2 + +.sp +.LP +The \fBattropen\fR(3C) function returns a file descriptor for the named +attribute, \fIattrpath\fR, of the file indicated by \fIpath\fR. The \fIoflag\fR +and \fImode\fR arguments are identical to the \fBopen\fR(2) arguments and are +applied to the open operation on the attribute file (for example, using the +\fBO_CREAT\fR flag creates a new attribute). Once opened, all normal file +system operations can be used on the attribute file descriptor. The +\fBattropen()\fR function is a convenience function and is equivalent to the +following sequence of operations: +.sp +.in +2 +.nf +fd = open (path, O_RDONLY); +attrfd = openat(fd, attrpath, oflag|O_XATTR, mode); +close(fd); +.fi +.in -2 + +.sp +.LP +The set of existing attributes can be browsed by calling \fBattropen()\fR with +"." as the attribute name. The list of attributes is obtained by calling +\fBgetdents\fR(2) (or \fBfdopendir\fR(3C) followed by \fBreaddir\fR(3C), see +below) on the returned file descriptor. +.SS "Convert an open file descriptor for a directory into a directory descriptor" +.sp +.in +2 +.nf +DIR * fdopendir (const int \fIfd\fR) +.fi +.in -2 + +.sp +.LP +The \fBfdopendir\fR(3C) function promotes a file descriptor for a directory to +a directory pointer suitable for use with the \fBreaddir\fR(3C) function. The +originating file descriptor should not be used again following the call to +\fBfdopendir()\fR. The directory pointer should be closed with a call to +\fBclosedir\fR(3C). If the provided file descriptor does not reference a +directory, the function returns \fBENOTDIR\fR. This function is useful in +circumstances where the only available handle on a directory is a file +descriptor. See \fBattropen\fR(3C) and \fBopenat\fR(2). +.SS "Using the API" +.sp +.LP +The following examples demonstrate how the API might be used to perform basic +operations on extended attributes: +.LP +\fBExample 1 \fRList extended attributes on a file. +.sp +.in +2 +.nf +attrdirfd = attropen("test", ".", O_RDONLY); +dirp = fdopendir(attrdirfd); +while (dp = readdir(dirp)) { +\&... +.fi +.in -2 + +.LP +\fBExample 2 \fROpen an extended attribute. +.sp +.in +2 +.nf +attrfd = attropen("test", dp->d_name, O_RDONLY); +.fi +.in -2 + +.sp +.LP +or + +.sp +.in +2 +.nf +attrfd = openat(attrdirfd, dp->d_name, O_RDONLY); +.fi +.in -2 + +.LP +\fBExample 3 \fRRead from an extended attribute. +.sp +.in +2 +.nf +while (read(attrfd, buf, 512) > 0) { +\&... +.fi +.in -2 + +.LP +\fBExample 4 \fRCreate an extended attribute. +.sp +.in +2 +.nf +newfd = attropen("test", "attr", O_CREAT|O_RDWR); +.fi +.in -2 + +.sp +.LP +or + +.sp +.in +2 +.nf +newfd = openat(attrdirfd, "attr", O_CREAT|O_RDWR); +.fi +.in -2 + +.LP +\fBExample 5 \fRWrite to an extended attribute. +.sp +.in +2 +.nf +count = write(newfd, buf, length); +.fi +.in -2 + +.LP +\fBExample 6 \fRDelete an extended attribute. +.sp +.in +2 +.nf +error = unlinkat(attrdirfd, "attr"); +.fi +.in -2 + +.sp +.LP +Applications intending to access the interfaces defined here as well as the +POSIX and X/Open specification-conforming interfaces should define the macro +\fB_ATFILE_SOURCE\fR to be 1 and set whichever feature test macros are +appropriate to obtain the desired environment. See \fBstandards\fR(7). +.SS "Extended Archive Formats" +.sp +.LP +As noted above in the description of command utilities modified to provide +support for extended attributes, the archive formats for \fBtar\fR(1) and +\fBcpio\fR(1) have been extended to provide support for archiving extended +attributes. This section describes the specifics of the archive format +extensions. +.SS "Extended tar format" +.sp +.LP +The \fBtar\fR archive is made up of a series of 512 byte blocks. Each archived +file is represented by a header block and zero or more data blocks containing +the file contents. The header block is structured as shown in the following +table. +.sp + +.sp +.TS +c c c +l l l . +Field Name Length (in Octets) Description +Name 100 File name string +Mode 8 12 file mode bits +Uid 8 User ID of file owner +Gid 8 Group ID of file owner +Size 12 Size of file +Mtime 12 File modification time +Chksum 8 File contents checksum +Typeflag 1 File type flag +Linkname 100 Link target name if file linked +Magic 6 "ustar" +Version 2 "00" +Uname 32 User name of file owner +Gname 32 Group name of file owner +Devmajor 8 Major device ID if special file +Devminor 8 Minor device ID if special file +Prefix 155 Path prefix string for file +.TE + +.sp +.LP +The extended attribute project extends the above header format by defining a +new header type (for the \fBTypeflag\fR field). The type 'E' is defined to be +used for all extended attribute files. Attribute files are stored in the +\fBtar\fR archive as a sequence of two \fB<header ,data>\fR pairs. The first +file contains the data necessary to locate and name the extended attribute in +the file system. The second file contains the actual attribute file data. Both +files use an 'E' type header. The prefix and name fields in extended attribute +headers are ignored, though they should be set to meaningful values for the +benefit of archivers that do not process these headers. Solaris archivers set +the prefix field to "\fB/dev/null\fR" to prevent archivers that do not +understand the type 'E' header from trying to restore extended attribute files +in inappropriate places. +.SS "Extended cpio format" +.sp +.LP +The \fBcpio\fR archive format is octet-oriented rather than block-oriented. +Each file entry in the archive includes a header that describes the file, +followed by the file name, followed by the contents of the file. These data +are arranged as described in the following table. +.sp + +.sp +.TS +c c c +l l l . +\fBField Name\fR Length (in Octets) Description +\fBc_magic\fR 6 70707 +\fBc_dev\fR 6 First half of unique file ID +\fBc_ino\fR 6 Second half of unique file ID +\fBc_mode\fR 6 File mode bits +\fBc_uid\fR 6 User ID of file owner +\fBc_gid\fR 6 Group ID of file owner +\fBc_nlink\fR 6 Number of links referencing file +\fBc_rdev\fR 6 Information for special files +\fBc_mtime\fR 11 Modification time of file +\fBc_namesize\fR 6 Length of file pathname +\fBc_filesize\fR 11 Length of file content +\fBc_name\fR \fBc_namesize\fR File pathname +\fBc_filedata\fR \fBc_filesize\fR File content +.TE + +.sp +.LP +The basic archive file structure is not changed for extended attributes. The +file type bits stored in the \fBc_mode\fR field for an attribute file are set +to \fB0xB000\fR. As with the \fBtar\fR archive format, extended attributes are +stored in \fBcpio\fR archives as two consecutive file entries. The first file +describes the location/name for the extended attribute. The second file +contains the actual attribute file content. The \fBc_name\fR field in extended +attribute headers is ignored, though it should be set to a meaningful value for +the benefit of archivers that do not process these headers. Solaris archivers +start the pathname with "\fB/dev/null/\fR"to prevent archivers that do not +understand the type 'E' header from trying to restore extended attribute files +in inappropriate places. +.SS "Attribute identification data format" +.sp +.LP +Both the \fBtar\fR and \fBcpio\fR archive formats can contain the special files +described above, always paired with the extended attribute data record, for +identifying the precise location of the extended attribute. These special data +files are necessary because there is no simple naming mechanism for extended +attribute files. Extended attributes are not visible in the file system name +space. The extended attribute name space must be "tunneled into" using the +\fBopenat()\fR function. The attribute identification data must support not +only the flat naming structure for extended attributes, but also the +possibility of future extensions allowing for attribute directory hierarchies +and recursive attributes. The data file is therefore composed of a sequence of +records. It begins with a fixed length header describing the content. The +following table describes the format of this data file. +.sp + +.sp +.TS +c c c +l l l . +Field Name Length (in Octets) Description +\fBh_version\fR 7 Name file version +\fBh_size\fR 10 Length of data file +\fBh_component_len\fR 10 Total length of all path segments +\fBh_link_comp_len\fR 10 Total length of all link segments +\fBpath\fR \fBh_component_len\fR Complex path +\fBlink_path\fR \fBh_link_comp_len\fR Complex link path +.TE + +.sp +.LP +As demonstrated above, the header is followed by a record describing the "path" +to the attribute file. This path is composed of two or more path segments +separated by a null character. Each segment describes a path rooted at the +hidden extended attribute directory of the leaf file of the previous segment, +making it possible to name attributes on attributes. The first segment is +always the path to the parent file that roots the entire sequence in the normal +name space. The following table describes the format of each segment. +.sp + +.sp +.TS +c c c +l l l . +Field Name Length (in Octets) Description +_ +\fBh_namesz\fR 7 Length of segment path +\fBh_typeflag\fR 1 Actual file type of attribute file +\fBh_names\fR \fBh_namesz\fR Parent path + segment path +.TE + +.sp +.LP +If the attribute file is linked to another file, the path record is followed by +a second record describing the location of the referencing file. The structure +of this record is identical to the record described above. +.SH SEE ALSO +.sp +.LP +.BR cp (1), +.BR cpio (1), +.BR du (1), +.BR find (1), +.BR ls (1), +.BR mv (1), +.BR pax (1), +.BR runat (1), +.BR tar (1), +.BR chown (2), +.BR link (2), +.BR open (2), +.BR pathconf (2), +.BR rename (2), +.BR stat (2), +.BR unlink (2), +.BR utimes (2), +.BR attropen (3C), +.BR standards (7), +.BR fsck (8) diff --git a/usr/src/man/man7/gptzfsboot.7 b/usr/src/man/man7/gptzfsboot.7 new file mode 100644 index 0000000000..ff7a5f31e3 --- /dev/null +++ b/usr/src/man/man7/gptzfsboot.7 @@ -0,0 +1,191 @@ +.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS 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 AUTHORS 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. +.\" +.Dd July 17, 2019 +.Dt GPTZFSBOOT 7 +.Os +.Sh NAME +.Nm gptzfsboot +.Nd disk bootcode for BIOS-based computers +.Sh DESCRIPTION +.Nm +is used on BIOS-based computers to boot from a filesystem on disk device. +Depending on disk partitioning and boot file system, the +.Nm +is installed in a +.Cm zfs pool boot area +or +.Cm boot +partition of a disk with +.Xr installboot 8 . +.Ss IMPLEMENTATION NOTES +The GPT standard allows a variable number of partitions, but +.Nm +only boots from tables with 128 partitions or less. +.Ss BOOTING +.Nm +tries to find all ZFS pools that are composed of BIOS-visible +hard disks or partitions on them. +.Nm +looks for ZFS device labels on all visible disks and in discovered +supported partitions for all supported partition scheme types. +Disks are probed in BIOS defined order. +After a disk is probed and +.Nm +determines that the whole disk is not a ZFS pool member, the +individual partitions are probed in their partition table order. +Currently GPT and MBR partition schemes are supported. +.Pp +The default boot partition is recorded into +.Nm +binary by +.Xr installboot 8 +and the default boot file system is determined at run time. +.Nm +does support booting from the +.Cm ZFS , +.Cm UFS +and +.Cm PCFS +file systems. +.Pp +The filesystem specified by the +.Cm bootfs +property of the ZFS pool is used as a default boot filesystem. +If the +.Cm bootfs +property is not set, then the root filesystem of the pool is used as +the default. +.Xr loader 7 +is loaded from the boot filesystem. +If +.Pa /boot/config +is present in the boot filesystem, boot options are read from it. +.Pp +The ZFS GUIDs of the boot pool and boot file system are made available to +.Xr loader 7 . +.Ss USAGE +Normally +.Nm +will boot in fully automatic mode. +However, it is possible to interrupt the automatic boot process and +interact with +.Nm +through a prompt. +.Pp +The filesystem specification and the path to +.Xr loader 7 +is specified as +.Pp +.Sm off +.Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc +.Sm on +.Pp +Both the filesystem and the path can be specified. +If only a path is specified, then the default filesystem is used. +If only a pool and filesystem are specified, then +.Pa /boot/loader +is used as a path. +.Pp +Additionally, the +.Nm +does support two commands to get information about the system. +.Ic ?directoryname +can be used to list the content of named directory and +.Ic status +command can be used to query information about discovered devices. +The output format for ZFS pools is similar to that of +.Cm zpool status +.Pq see Xr zpool 8 . +.Pp +The configured or automatically determined ZFS boot filesystem is +stored in the +.Xr loader 7 +.Cm loaddev +variable, and also set as the initial value of the +.Cm currdev +variable. +.Sh OPTIONS +The following options are supported by +.Nm +and +.Xr loader 7 : +.Bl -tag -width indent +.It Fl D +Dual console. +Use both text and serial console with +.Nm +and +.Xr loader 7 . +.It Fl P +Probe for keyboard. +If there is no keyboard, switch on the dual console and serial console. +.It Fl S Ns Ar speed +Set serial port speed. +.It Fl h +Set serial console. +.It Fl q +Keep the +.Nm +console quiet. +.It Fl t +Keep the VGA text mode for +.Xr loader 7 . +.El +.Pp +The following options will be passed to the kernel: +.Bl -tag -width indent +.It Fl s +Single user +.It Fl v +Verbose boot +.El +.Sh FILES +.Bl -tag -width /boot/gptzfsboot -compact +.It Pa /boot/config +parameters for the boot block +.Pq optional +.It Pa /boot/gptzfsboot +boot code binary +.El +.Sh EXAMPLES +.Nm +is installed in combination with a +.Dq protective MBR +.Po +see +.Xr installboot 8 +.Pc . +To install +.Nm +on the +.Pa c0t0d0s0 +drive: +.Bd -literal -offset indent +installboot /boot/pmbr /boot/gptzfsboot /dev/rdsk/c0t0d0s0 +.Ed +.Sh SEE ALSO +.Xr loader 7 , +.Xr installboot 8 , +.Xr zpool 8 diff --git a/usr/src/man/man7/grub.7 b/usr/src/man/man7/grub.7 new file mode 100644 index 0000000000..4cc3baf2c0 --- /dev/null +++ b/usr/src/man/man7/grub.7 @@ -0,0 +1,87 @@ +'\" te +.\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH GRUB 7 "Apr 21, 2005" +.SH NAME +grub \- GRand Unified Bootloader software on Solaris +.SH DESCRIPTION +.sp +.LP +The current release of the Solaris operating system is shipped with the GRUB +(GRand Unified Bootloader) software. GRUB is developed and supported by the +Free Software Foundation. +.sp +.LP +The overview for the GRUB Manual, accessible at \fBwww.gnu.org\fR, describes +GRUB: +.sp +.LP +Briefly, a boot loader is the first software program that runs when a computer +starts. It is responsible for loading and transferring control to an operating +system kernel software (such as Linux or GNU Mach). The kernel, in turn, +initializes the rest of the operating system (for example, a GNU [Ed. note: or +Solaris] system). +.sp +.LP +GNU GRUB is a very powerful boot loader that can load a wide variety of free, +as well as proprietary, operating systems, by means of chain-loading. GRUB is +designed to address the complexity of booting a personal computer; both the +program and this manual are tightly bound to that computer platform, although +porting to other platforms may be addressed in the future. [Ed. note: Sun has +ported GRUB to the Solaris operating system.] +.sp +.LP +One of the important features in GRUB is flexibility; GRUB understands +filesystems and kernel executable formats, so you can load an arbitrary +operating system the way you like, without recording the physical position of +your kernel on the disk. Thus you can load the kernel just by specifying its +file name and the drive and partition where the kernel resides. +.sp +.LP +Among Solaris machines, GRUB is supported on x86 platforms. The GRUB software +that is shipped with Solaris adds two utilities not present in the open-source +distribution: +.sp +.ne 2 +.na +\fB\fBbootadm\fR(8)\fR +.ad +.RS 19n +Enables you to manage the boot archive and make changes to the GRUB menu. +.RE + +.sp +.ne 2 +.na +\fB\fBinstallgrub\fR(8)\fR +.ad +.RS 19n +Loads the boot program from disk. +.RE + +.sp +.LP +Both of these utilities are described in Solaris man pages. +.sp +.LP +Beyond these two Solaris-specific utilities, the GRUB software is described in +the GRUB manual, a PDF version of which is available from the Sun web site. +Available in the same location is the \fBgrub(8)\fR open-source man page. This +man page describes the GRUB shell. +.SH SEE ALSO +.sp +.LP +.BR boot (8), +.BR bootadm (8), +.BR installgrub (8) +.sp +.LP +\fISolaris Express Installation Guide: Basic Installations\fR +.sp +.LP +\fISystem Administration Guide: Basic Administration\fR +.sp +.LP +http://www.gnu.org/software/grub diff --git a/usr/src/man/man7/gss_auth_rules.7 b/usr/src/man/man7/gss_auth_rules.7 new file mode 100644 index 0000000000..72d1d54738 --- /dev/null +++ b/usr/src/man/man7/gss_auth_rules.7 @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH GSS_AUTH_RULES 7 "Apr 13, 2004" +.SH NAME +gss_auth_rules \- overview of GSS authorization +.SH DESCRIPTION +.sp +.LP +The establishment of the veracity of a user's credentials requires both +authentication (Is this an authentic user?) and authorization (Is this +authentic user, in fact, authorized?). +.sp +.LP +When a user makes use of Generic Security Services (GSS) versions of the +\fBftp\fR or \fBssh\fR clients to connect to a server, the user is not +necessarily authorized, even if his claimed GSS identity is authenticated, +Authentication merely establishes that the user is who he says he is to the GSS +mechanism's authentication system. Authorization is then required: it +determines whether the GSS identity is permitted to access the specified +Solaris user account. +.sp +.LP +The GSS authorization rules are as follows: +.RS +4 +.TP +.ie t \(bu +.el o +If the mechanism of the connection has a set of authorization rules, then use +those rules. For example, if the mechanism is Kerberos, then use the +\fBkrb5_auth_rules\fR(7), so that authorization is consistent between raw +Kerberos applications and GSS/Kerberos applications. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the mechanism of the connection does not have a set of authorization rules, +then authorization is successful if the remote user's \fBgssname\fR matches the +local user's \fBgssname\fR exactly, as compared by +\fBgss_compare_name\fR(3GSS). +.RE +.SH FILES +.sp +.ne 2 +.na +\fB\fB/etc/passwd\fR\fR +.ad +.RS 15n +System account file. This information may also be in a directory service. See +\fBpasswd\fR(5). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for a description 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 +.BR ftp (1), +.BR ssh (1), +.BR gss_compare_name (3GSS), +.BR passwd (5), +.BR attributes (7), +.BR krb5_auth_rules (7), +.BR gsscred (8) diff --git a/usr/src/man/man7/hal.7 b/usr/src/man/man7/hal.7 new file mode 100644 index 0000000000..df3f2a7351 --- /dev/null +++ b/usr/src/man/man7/hal.7 @@ -0,0 +1,39 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH HAL 7 "Nov 26, 2017" +.SH NAME +hal \- overview of hardware abstraction layer +.SH DESCRIPTION +.LP +The Hardware Abstraction Layer (HAL) provides a view of the various hardware +attached to a system. This view is updated dynamically as hardware +configuration changes by means of hotplug or other mechanisms. HAL represents a +piece of hardware as a device object. A device object is identified by a unique +identifier and carries a set of key/value pairs, referred to as device +properties. Some properties are derived from the actual hardware, some are +merged from device information files (\fB\&.fdi\fR files), and some are related +to the actual device configuration. +.sp +.LP +HAL provides an easy-to-use API through D-Bus. D-Bus is an IPC framework that, +among other features, provides a system-wide message-bus that allows +applications to talk to one another. Specifically, D-Bus provides asynchronous +notification such that HAL can notify other peers on the message-bus when +devices are added and removed, as well as when properties on a device are +changing. +.sp +.LP +In the Solaris operating system, HAL is supported by a daemon, \fBhald\fR(8), +and a set of utilities that enable the adding and removing of devices and the +modification of their properties. +.SH SEE ALSO +.LP +.BR fdi (5), +.BR hald (8) +.sp +.LP +See the HAL pages, including the HAL specification, under +http://freedesktop.org. diff --git a/usr/src/man/man7/ibmf.7 b/usr/src/man/man7/ibmf.7 deleted file mode 100644 index 36598fc066..0000000000 --- a/usr/src/man/man7/ibmf.7 +++ /dev/null @@ -1,47 +0,0 @@ -.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved -.\" Copyright 2020 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] -.\" -.Dd January 12, 2020 -.Dt IBMF 7 -.Os -.Sh NAME -.Nm ibmf -.Nd InfiniBand Management Transport Framework -.Sh DESCRIPTION -The InfiniBand (IB) Management Transport Framework provides the mechanisms for -IB management modules to communicate with other InfiniBand management modules -such as the Subnet Administration process. -It also provides helper functions -such as Subnet Administration Access (SAA) for commonly performed operations. -.Sh FILES -.Bl -tag -width Pa -.It Pa /kernel/misc/amd64/ibmf -Device driver (x86). -.It Pa /kernel/misc/sparcv9/ibmf -Device driver (SPARC) -.El -.Sh ARCHITECTURE -PCI-based systems -.Sh INTERFACE STABILITY -Private -.Sh SEE ALSO -.Xr ibtl 7D -.Pp -.%T InfiniBand Architecture Specification, Version 1\&.1 -.Pp -.%U www.infinibandta.org diff --git a/usr/src/man/man7/iconv.7 b/usr/src/man/man7/iconv.7 new file mode 100644 index 0000000000..2a292fc4fd --- /dev/null +++ b/usr/src/man/man7/iconv.7 @@ -0,0 +1,322 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" +.TH ICONV 7 "Dec 5, 2001" +.SH NAME +iconv \- code set conversion tables +.SH DESCRIPTION +.sp +.LP +The following code set conversions are supported: +.sp +.in +2 +.nf + Code Set Conversions Supported + +Code Symbol Target Code Symbol Target Output + +ISO 646 646 ISO 8859-1 8859 US ASCII +ISO 646de 646de ISO 8859-1 8859 German +ISO 646da 646da ISO 8859-1 8859 Danish +ISO 646en 646en ISO 8859-1 8859 English ASCII +ISO 646es 646es ISO 8859-1 8859 Spanish +ISO 646fr 646fr ISO 8859-1 8859 French +ISO 646it 646it ISO 8859-1 8859 Italian +ISO 646sv 646sv ISO 8859-1 8859 Swedish +ISO 8859-1 8859 ISO 646 646 7 bit ASCII +ISO 8859-1 8859 ISO 646de 646de German +ISO 8859-1 8859 ISO 646da 646da Danish +ISO 8859-1 8859 ISO 646en 646en English ASCII +ISO 8859-1 8859 ISO 646es 646es Spanish +ISO 8859-1 8859 ISO 646fr 646fr French +ISO 8859-1 8859 ISO 646it 646it Italian +ISO 8859-1 8859 ISO 646sv 646sv Swedish +ISO 8859-16 iso16 ISO 8859-2 iso2 ISO Latin 2 +ISO 8859-2 iso2 ISO 8859-16 iso16 ISO Latin 10 +ISO 8859-16 iso16 IBM 850 ibm850 IBM 850 code page +ISO 8859-16 iso16 IBM 870 ibm870 IBM 870 code page +ISO 8859-2 iso2 MS 1250 win2 Windows Latin 2 +ISO 8859-2 iso2 MS 852 dos2 MS-DOS Latin 2 +ISO 8859-2 iso2 Mazovia maz Mazovia +IBM 850 ibm850 ISO 8859-16 iso16 ISO Latin 10 +IBM 870 ibm870 ISO 8859-16 iso16 ISO Latin 10 +MS 1250 win2 DHN dhn Dom Handlowy Nauki +MS 852 dos2 ISO 8859-2 iso2 ISO Latin 2 +MS 852 dos2 MS 1250 win2 Windows Latin 2 +MS 852 dos2 Mazovia maz Mazovia +MS 852 dos2 DHN dhn Dom Handlowy Nauki +Mazovia maz ISO 8859-2 iso2 ISO Latin 2 +Mazovia maz MS 1250 win2 Windows Latin 2 +Mazovia maz MS 852 dos2 MS-DOS Latin 2 +Mazovia maz DHN dhn Dom Handlowy Nauki +DHN dhn ISO 8859-2 iso2 ISO Latin 2 +DHN dhn MS 1250 win2 Windows Latin 2 +DHN dhn MS 852 dos2 MS-DOS Latin 2 +DHN dhn Mazovia maz Mazovia +ISO 8859-5 iso5 KOI8-R koi8 KOI8-R +ISO 8859-5 iso5 PC Cyrillic alt Alternative PC Cyrillic +ISO 8859-5 iso5 MS 1251 win5 Windows Cyrillic +ISO 8859-5 iso5 Mac Cyrillic mac Macintosh Cyrillic +KOI8-R koi8 ISO 8859-5 iso5 ISO 8859-5 Cyrillic +KOI8-R koi8 PC Cyrillic alt Alternative PC Cyrillic +KOI8-R koi8 MS 1251 win5 Windows Cyrillic +KOI8-R koi8 Mac Cyrillic mac Macintosh Cyrillic +PC Cyrillic alt ISO 8859-5 iso5 ISO 8859-5 Cyrillic +PC Cyrillic alt KOI8-R koi8 KOI8-R +PC Cyrillic alt MS 1251 win5 Windows Cyrillic +PC Cyrillic alt Mac Cyrillic mac Macintosh Cyrillic +MS 1251 win5 ISO 8859-5 iso5 ISO 8859-5 Cyrillic +MS 1251 win5 KOI8-R koi8 KOI8-R +MS 1251 win5 PC Cyrillic alt Alternative PC Cyrillic +MS 1251 win5 Mac Cyrillic mac Macintosh Cyrillic +Mac Cyrillic mac ISO 8859-5 iso5 ISO 8859-5 Cyrillic +Mac Cyrillic mac KOI8-R koi8 KOI8-R +Mac Cyrillic mac PC Cyrillic alt Alternative PC Cyrillic +Mac Cyrillic mac MS 1251 win5 Windows Cyrillic +.fi +.in -2 +.sp + +.SH CONVERSIONS +.sp +.LP +The conversions are performed according to the tables contained in the manual +pages cross-referenced in the \fBIndex of Conversion Code Tables\fR below. +.sp + +.sp +.TS +box; +c | c | c +l | l | l . +\fBIndex of Conversion Code Tables\fR +_ +\fBCode\fR \fBTarget Code\fR \fBSee Manual Page\fR +_ +ISO 646 ISO 8859-1 iconv_646 (5) +_ +ISO 646de ISO 8859-1 +_ +ISO 646da ISO 8859-1 +_ +ISO 646en ISO 8859-1 +_ +ISO 646es ISO 8859-1 +_ +ISO 646fr ISO 8859-1 +_ +ISO 646it ISO 8859-1 +_ +ISO 646sv ISO 8859-1 +_ +ISO 8859-1 ISO 646 iconv_8859-1 (5) +_ +ISO 8859-1 ISO 646de +_ +ISO 8859-1 ISO 646da +_ +ISO 8859-1 ISO 646en +_ +ISO 8859-1 ISO 646es +_ +ISO 8859-1 ISO 646fr +_ +ISO 8859-1 ISO 646it +_ +ISO 8859-1 ISO 646sv +_ +ISO 8859-2 MS 1250 iconv_8859-2 (5) +_ +ISO 8859-2 MS 852 +_ +ISO 8859-2 Mazovia +_ +ISO 8859-2 DHN +_ +MS 1250 ISO 8859-2 iconv_1250 (5) +_ +MS 1250 MS 852 +_ +MS 1250 Mazovia +_ +MS 1250 DHN +_ +MS 852 ISO 8859-2 iconv_852 (5) +_ +MS 852 MS 1250 +_ +MS 852 Mazovia +_ +MS 852 DHN +_ +Mazovia ISO 8859-2 iconv_maz (5) +_ +Mazovia MS 1250 +_ +Mazovia MS 852 +_ +Mazovia DHN +.TE + +.sp + +.sp +.TS +box; +c | c | c +l | l | l . +\fBIndex of Conversion Code Tables\fR +_ +\fBCode\fR \fBTarget Code\fR \fBSee Manual Page\fR +_ +DHN ISO 8859-2 iconv_dhn (5) +_ +DHN MS 1250 +_ +DHN MS 852 +_ +DHN Mazovia +_ +ISO 8859-5 KOI8-R iconv_8859-5 (5) +_ +ISO 8859-5 PC Cyrillic +_ +ISO 8859-5 MS 1251 +_ +ISO 8859-5 Mac Cyrillic +_ +KOI8-R ISO 8859-5 iconv_koi8-r (5) +_ +KOI8-R PC Cyrillic +_ +KOI8-R MS 1251 +_ +KOI8-R Mac Cyrillic +_ +PC Cyrillic ISO 8859-5 iconv_pc_cyr (5) +_ +PC Cyrillic KOI8-R +_ +PC Cyrillic MS 1251 +_ +PC Cyrillic Mac Cyrillic +_ +MS 1251 ISO 8859-5 iconv_1251 (5) +_ +MS 1251 KOI8-R +_ +MS 1251 PC Cyrillic +_ +MS 1251 Mac Cyrillic +_ +Mac Cyrillic ISO 8859-5 iconv_mac_cyr (5) +_ +Mac Cyrillic KOI8-R +_ +Mac Cyrillic PC Cyrillic +_ +Mac Cyrillic MS 1251 +.TE + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/lib/iconv/*.so\fR\fR +.ad +.sp .6 +.RS 4n +conversion modules +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/iconv/*.t\fR\fR +.ad +.sp .6 +.RS 4n +Conversion tables. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/iconv/geniconvtbl/binarytables/*.bt\fR\fR +.ad +.sp .6 +.RS 4n +Conversion binary tables. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/iconv/iconv_data\fR\fR +.ad +.sp .6 +.RS 4n +List of conversions supported by conversion tables. +.RE + +.SH SEE ALSO +.sp +.LP +.BR iconv (1), +.BR iconv (3C), +.BR iconv_1250 (7), +.BR iconv_1251 (7), +.BR iconv_646 (7), +.BR iconv_852 (7), +.BR iconv_8859-1 (7), +.BR iconv_8859-2 (7), +.BR iconv_8859-5 (7), +.BR iconv_dhn (7), +.BR iconv_koi8-r (7), +.BR iconv_mac_cyr (7), +.BR iconv_maz (7), +.BR iconv_pc_cyr (7), +.BR iconv_unicode (7) diff --git a/usr/src/man/man7/iconv_unicode.7 b/usr/src/man/man7/iconv_unicode.7 new file mode 100644 index 0000000000..74a3aca765 --- /dev/null +++ b/usr/src/man/man7/iconv_unicode.7 @@ -0,0 +1,325 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ICONV_UNICODE 7 "Apr 18, 1997" +.SH NAME +iconv_unicode \- code set conversion tables for Unicode +.SH DESCRIPTION +.sp +.LP +The following code set conversions are supported: +.sp +.in +2 +.nf + CODE SET CONVERSIONS SUPPORTED + ------------------------------ + FROM Code Set TO Code Set + Code FROM Target Code TO + Filename Filename + Element Element + +ISO 8859-1 (Latin 1) 8859-1 UTF-8 UTF-8 +ISO 8859-2 (Latin 2) 8859-2 UTF-8 UTF-8 +ISO 8859-3 (Latin 3) 8859-3 UTF-8 UTF-8 +ISO 8859-4 (Latin 4) 8859-4 UTF-8 UTF-8 +ISO 8859-5 (Cyrillic) 8859-5 UTF-8 UTF-8 +ISO 8859-6 (Arabic) 8859-6 UTF-8 UTF-8 +ISO 8859-7 (Greek) 8859-7 UTF-8 UTF-8 +ISO 8859-8 (Hebrew) 8859-8 UTF-8 UTF-8 +ISO 8859-9 (Latin 5) 8859-9 UTF-8 UTF-8 +ISO 8859-10 (Latin 6) 8859-10 UTF-8 UTF-8 +Japanese EUC eucJP UTF-8 UTF-8 +Chinese/PRC EUC +(GB 2312-1980) gb2312 UTF-8 UTF-8 +ISO-2022 iso2022 UTF-8 UTF-8 +Korean EUC ko_KR-euc Korean UTF-8 ko_KR-UTF-8 +ISO-2022-KR ko_KR-iso2022-7 Korean UTF-8 ko_KR_UTF-8 +Korean Johap +(KS C 5601-1987) ko_KR-johap Korean UTF-8 ko_KR-UTF-8 +Korean Johap +(KS C 5601-1992) ko_KR-johap92 Korean UTF-8 ko_KR-UTF-8 +Korean UTF-8 ko_KR-UTF-8 Korean EUC ko_KR-euc +Korean UTF-8 ko_KR-UTF-8 Korean Johap ko_KR-johap + (KS C 5601-1987) +Korean UTF-8 ko_KR-UTF-8 Korean Johap ko_KR-johap92 + (KS C 5601-1992) +KOI8-R (Cyrillic) KOI8-R UCS-2 UCS-2 +KOI8-R (Cyrillic) KOI8-R UTF-8 UTF-8 +PC Kanji (SJIS) PCK UTF-8 UTF-8 +PC Kanji (SJIS) SJIS UTF-8 UTF-8 +UCS-2 UCS-2 KOI8-R (Cyrillic) KOI8-R +UCS-2 UCS-2 UCS-4 UCS-4 +.fi +.in -2 +.sp + +.sp +.in +2 +.nf + CODE SET CONVERSIONS SUPPORTED + ------------------------------ + FROM Code Set TO Code Set + Code FROM Target Code TO + Filename Filename + Element Element + +UCS-2 UCS-2 UTF-7 UTF-7 +UCS-2 UCS-2 UTF-8 UTF-8 +UCS-4 UCS-4 UCS-2 UCS-2 +UCS-4 UCS-4 UTF-16 UTF-16 +UCS-4 UCS-4 UTF-7 UTF-7 +UCS-4 UCS-4 UTF-8 UTF-8 +UTF-16 UTF-16 UCS-4 UCS-4 +UTF-16 UTF-16 UTF-8 UTF-8 +UTF-7 UTF-7 UCS-2 UCS-2 +UTF-7 UTF-7 UCS-4 UCS-4 +UTF-7 UTF-7 UTF-8 UTF-8 +UTF-8 UTF-8 ISO 8859-1 (Latin 1) 8859-1 +UTF-8 UTF-8 ISO 8859-2 (Latin 2) 8859-2 +UTF-8 UTF-8 ISO 8859-3 (Latin 3) 8859-3 +UTF-8 UTF-8 ISO 8859-4 (Latin 4) 8859-4 +UTF-8 UTF-8 ISO 8859-5 (Cyrillic) 8859-5 +UTF-8 UTF-8 ISO 8859-6 (Arabic) 8859-6 +UTF-8 UTF-8 ISO 8859-7 (Greek) 8859-7 +UTF-8 UTF-8 ISO 8859-8 (Hebrew) 8859-8 +UTF-8 UTF-8 ISO 8859-9 (Latin 5) 8859-9 +UTF-8 UTF-8 ISO 8859-10 (Latin 6) 8859-10 +UTF-8 UTF-8 Japanese EUC eucJP +UTF-8 UTF-8 Chinese/PRC EUC gb2312 + (GB 2312-1980) +UTF-8 UTF-8 ISO-2022 iso2022 +UTF-8 UTF-8 KOI8-R (Cyrillic) KOI8-R +UTF-8 UTF-8 PC Kanji (SJIS) PCK +UTF-8 UTF-8 PC Kanji (SJIS) SJIS +UTF-8 UTF-8 UCS-2 UCS-2 +UTF-8 UTF-8 UCS-4 UCS-4 +UTF-8 UTF-8 UTF-16 UTF-16 +UTF-8 UTF-8 UTF-7 UTF-7 +UTF-8 UTF-8 Chinese/PRC EUC zh_CN.euc + (GB 2312-1980) +.fi +.in -2 +.sp + +.sp +.in +2 +.nf + CODE SET CONVERSIONS SUPPORTED + ------------------------------ + FROM Code Set TO Code Set + Code FROM Target Code TO + Filename Filename + Element Element + +UTF-8 UTF-8 ISO 2022-CN zh_CN.iso2022-7 +UTF-8 UTF-8 Chinese/Taiwan Big5 zh_TW-big5 +UTF-8 UTF-8 Chinese/Taiwan EUC zh_TW-euc + (CNS 11643-1992) +UTF-8 UTF-8 ISO 2022-TW zh_TW-iso2022-7 +Chinese/PRC EUC zh_CN.euc UTF-8 UTF-8 +(GB 2312-1980) +ISO 2022-CN zh_CN.iso2022-7 UTF-8 UTF-8 +Chinese/Taiwan Big5 zh_TW-big5 UTF-8 UTF-8 +Chinese/Taiwan EUC zh_TW-euc UTF-8 UTF-8 +(CNS 11643-1992) +ISO 2022-TW zh_TW-iso2022-7 UTF-8 UTF-8 +.fi +.in -2 +.sp + +.SH EXAMPLES +.LP +\fBExample 1 \fRThe library module filename +.sp +.LP +In the conversion library, \fB/usr/lib/iconv\fR (see \fBiconv\fR(3C)), the +library module filename is composed of two symbolic elements separated by the +percent sign (\fB%\fR). The first symbol specifies the code set that is being +converted; the second symbol specifies the \fItarget code\fR, that is, the code +set to which the first one is being converted. + +.sp +.LP +In the conversion table above, the first symbol is termed the "FROM Filename +Element". The second symbol, representing the target code set, is the "TO +Filename Element". + +.sp +.LP +For example, the library module filename to convert from the \fIKorean\fR +\fIEUC\fR code set to the \fIKorean\fR \fIUTF-8\fR code set is + +.sp +.LP +\fBko_KR-euc%ko_KR-UTF-8\fR + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/lib/iconv/*.so\fR\fR +.ad +.RS 23n +conversion modules +.RE + +.SH SEE ALSO +.sp +.LP +.BR iconv (1), +.BR iconv (3C), +.BR iconv (7) +.sp +.LP +Chernov, A., \fIRegistration of a Cyrillic Character Set\fR, RFC 1489, RELCOM +Development Team, July 1993. +.sp +.LP +Chon, K., H. Je Park, and U. Choi, \fIKorean Character Encoding for Internet +Messages\fR, RFC 1557, Solvit Chosun Media, December 1993. +.sp +.LP +Goldsmith, D., and M. Davis, \fIUTF-7 - A Mail-Safe Transformation Format of +Unicode\fR, RFC 1642, Taligent, Inc., July 1994. +.sp +.LP +Lee, F., \fIHZ - A Data Format for Exchanging Files of\fR \fIArbitrarily Mixed +Chinese and ASCII characters\fR, RFC 1843, Stanford University, August 1995. +.sp +.LP +Murai, J., M. Crispin, and E. van der Poel, \fIJapanese Character Encoding for +Internet Messages\fR, RFC 1468, Keio University, Panda Programming, June 1993. +.sp +.LP +Nussbacher, H., and Y. Bourvine, \fIHebrew Character Encoding for Internet +Messages\fR, RFC 1555, Israeli Inter-University, Hebrew University, December +1993. +.sp +.LP +Ohta, M., \fICharacter Sets ISO-10646 and ISO-10646-J-1\fR, RFC 1815, Tokyo +Institute of Technology, July 1995. +.sp +.LP +Ohta, M., and K. Handa, \fIISO-2022-JP-2: Multilingual Extension of +ISO-2022-JP\fR, RFC 1554, Tokyo Institute of Technology, December 1993. +.sp +.LP +Reynolds, J., and J. Postel, \fIASSIGNED NUMBERS\fR, RFC 1700, University of +Southern California/Information Sciences Institute, October 1994. +.sp +.LP +Simonson, K., \fICharacter Mnemonics & Character Sets\fR, RFC 1345, Rationel +Almen Planlaegning, June 1992. +.sp +.LP +Spinellis, D., \fIGreek Character Encoding for Electronic Mail Messages\fR, RFC +1947, SENA S.A., May 1996. +.sp +.LP +The Unicode Consortium, \fIThe Unicode Standard\fR, Version 2.0, Addison Wesley +Developers Press, July 1996. +.sp +.LP +Wei, Y., Y. Zhang, J. Li, J. Ding, and Y. Jiang, \fIASCII Printable +Characters-Based Chinese Character Encoding\fR \fIfor Internet Messages\fR, RFC +1842, AsiaInfo Services Inc., Harvard University, Rice University, University +of Maryland, August 1995. +.sp +.LP +Yergeau, F., \fIUTF-8, a transformation format of Unicode and ISO 10646\fR, RFC +2044, Alis Technologies, October 1996. +.sp +.LP +Zhu, H., D. Hu, Z. Wang, T. Kao, W. Chang, and M. Crispin, \fIChinese Character +Encoding for Internet Messages\fR, RFC 1922, Tsinghua University, China +Information Technology Standardization Technical Committee (CITS), Institute +for Information Industry (III), University of Washington, March 1996. +.SH NOTES +.sp +.LP +ISO 8859 character sets using Latin alphabetic characters are distinguished as +follows: +.sp +.ne 2 +.na +\fB\fBISO\fR \fB8859-1\fR \fB(Latin\fR \fB1)\fR\fR +.ad +.RS 25n +For most West European languages, including: +.sp + +.sp +.TS +l l l +l l l . +Albanian Finnish Italian +Catalan French Norwegian +Danish German Portuguese +Dutch Galician Spanish +English Irish Swedish +Faeroese Icelandic +.TE + +.RE + +.sp +.ne 2 +.na +\fB\fBISO\fR \fB8859-2\fR \fB(Latin\fR \fB2)\fR\fR +.ad +.RS 25n +For most Latin-written Slavic and Central European languages: +.sp + +.sp +.TS +l l l +l l l . +Czech Polish Slovak +German Rumanian Slovene +Hungarian Croatian +.TE + +.RE + +.sp +.ne 2 +.na +\fB\fBISO\fR \fB8859-3\fR \fB(Latin\fR \fB3)\fR\fR +.ad +.RS 25n +Popularly used for Esperanto, Galician, Maltese, and Turkish. +.RE + +.sp +.ne 2 +.na +\fB\fBISO\fR \fB8859-4\fR \fB(Latin\fR \fB4)\fR\fR +.ad +.RS 25n +Introduces letters for Estonian, Latvian, and Lithuanian. It is an incomplete +predecessor of ISO 8859-10 (Latin 6). +.RE + +.sp +.ne 2 +.na +\fB\fBISO\fR \fB8859-9\fR \fB(Latin\fR \fB5)\fR\fR +.ad +.RS 25n +Replaces the rarely needed Icelandic letters in ISO 8859-1 (Latin 1) with the +Turkish ones. +.RE + +.sp +.ne 2 +.na +\fB\fBISO\fR \fB8859-10\fR \fB(Latin\fR \fB6)\fR\fR +.ad +.RS 25n +Adds the last Inuit (Greenlandic) and Sami (Lappish) letters that were not +included in ISO 8859-4 (Latin 4) to complete coverage of the Nordic area. +.RE + diff --git a/usr/src/man/man7/ieee802.11.7 b/usr/src/man/man7/ieee802.11.7 new file mode 100644 index 0000000000..a61dd8cf25 --- /dev/null +++ b/usr/src/man/man7/ieee802.11.7 @@ -0,0 +1,140 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH IEEE802.11 7 "Nov 28, 2006" +.SH NAME +ieee802.11 \- 802.11 kernel statistics +.SH DESCRIPTION +.sp +.LP +This page describes the kernel statistics that can be used to monitor +attributes specific to the 802.11 physical layer. These statistics can be +retrieved using \fBkstat\fR(8). Not all 802.11 devices will support all +statistics. +.sp +.ne 2 +.na +\fB\fBtx_frags\fR\fR +.ad +.RS 16n +Count of data and management fragments transmitted. +.RE + +.sp +.ne 2 +.na +\fB\fBrx_frags\fR\fR +.ad +.RS 16n +Count of data and management fragments received. +.RE + +.sp +.ne 2 +.na +\fB\fBrx_dups\fR\fR +.ad +.RS 16n +Count of duplicate frames received. Duplicates are determined by the sequence +control field. +.RE + +.sp +.ne 2 +.na +\fB\fBmcast_tx\fR\fR +.ad +.RS 16n +Count of broadcast and multicast frames transmitted. +.RE + +.sp +.ne 2 +.na +\fB\fBmcast_rx\fR\fR +.ad +.RS 16n +Count of broadcast and multicast frames received. +.RE + +.sp +.ne 2 +.na +\fB\fBtx_failed\fR\fR +.ad +.RS 16n +Count of frames that could not be transmitted due to the retransmission limit +being reached. +.RE + +.sp +.ne 2 +.na +\fB\fBtx_retrans\fR\fR +.ad +.RS 16n +Count of frames successfully retransmitted after one or more retransmissions. +.RE + +.sp +.ne 2 +.na +\fB\fBtx_reretrans\fR\fR +.ad +.RS 16n +Count of frames successfully retransmitted after more than one retransmission. +.RE + +.sp +.ne 2 +.na +\fB\fBrts_success\fR\fR +.ad +.RS 16n +Count of times a \fBCTS\fR was received in response to an \fBRTS\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBrts_failure\fR\fR +.ad +.RS 16n + Count of times a \fBCTS\fR was not received in response to an \fBRTS\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBack_failure\fR\fR +.ad +.RS 16n +Count of times an \fBACK\fR was expected but was not received. +.RE + +.sp +.ne 2 +.na +\fB\fBfcs_errors\fR\fR +.ad +.RS 16n +Count of frames received with \fBFCS\fR errors. +.RE + +.sp +.ne 2 +.na +\fB\fBwep_errors\fR\fR +.ad +.RS 16n +Count of frames received with the \fBWEP\fR bit set but that either should not +have been encrypted or that were discarded due to \fBWEP\fR not being +supported. +.RE + +.SH SEE ALSO +.sp +.LP +.BR kstat (8) diff --git a/usr/src/man/man7/ieee802.3.7 b/usr/src/man/man7/ieee802.3.7 new file mode 100644 index 0000000000..f69db544a1 --- /dev/null +++ b/usr/src/man/man7/ieee802.3.7 @@ -0,0 +1,555 @@ +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" Copyright 2016 Joyent, Inc. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER 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 +.\" COPYRIGHT HOLDER 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 +.\" +.Dd "Nov 23, 2016" +.Dt IEEE802.3 7 +.Os +.Sh NAME +.Nm ieee802.3 +.Nd IEEE 802.3 Ethernet parameters and statistics +.Sh DESCRIPTION +The IEEE 802.3 standard specifies the details for Ethernet +networking. +This page describes the various statistics and tunables that device drivers +supporting Ethernet commonly offer. +. +Note that not every device or driver supports every one of these +values, and many devices offer additional statistics and tunables that +are specific to that hardware. +See the device driver's documentation for those specific details. +. +.Lp +Values that are statistics are visible +.Xr kstat 8 , +whereas properties are visible using the +.Xr dladm 8 +.Sy show-linkprop +subcommand. +Tunables are properties that can be changed using the +.Xr dladm 8 +.Sy set-linkprop +subcommand. +A more useful summary of current operational state can be seen with the +.Xr dladm 8 +.Sy show-ether +subcommand. +. +.Ss Statistics +The following statistics are accessible with +.Xr kstat 8 . +Note that some statistics are available in both 32- and 64-bit counters, +in which case the name of the 64 bit statistic will be the same as the +32-bit, but with +.Dq Sy 64 +appended. +For example, +.Sy ipackets64 +is the 64-bit version of the +.Sy ipackets +statistic. +These are indicated with the special suffix +.Op Sy 64 +in the table below. +. +.Bl -tag -width tx_late_collisions +.It Sy adv_cap_1000fdx +Advertises 1000 Mbps full-duplex support. +.It Sy adv_cap_1000hdx +Advertises 1000 Mbps half-duplex support. +.It Sy adv_cap_100fdx +Advertises 100 Mbps full-duplex support. +.It Sy adv_cap_100gfdx +Advertises 100 Gbps support. +.It Sy adv_cap_100hdx +Advertises 100 Mbps half-duplex support. +.It Sy adv_cap_100T4 +Advertises 100BASE-T4 support. +.It Sy adv_cap_10fdx +Advertises 10 Mbps full-duplex support. +.It Sy adv_cap_10gfdx +Advertises 10 Gbps support. +.It Sy adv_cap_10hdx +Advertises 10 Mbps half-duplex support. +.It Sy adv_cap_2500fdx +Advertises 2.5 Gbps support. +.It Sy adv_cap_50gfdx +Advertises 50 Gbps support. +.It Sy adv_cap_40gfdx +Advertises 40 Gbps support. +.It Sy adv_cap_25gfdx +Advertises 25 Gbps support. +.It Sy adv_cap_5000fdx +Advertises 5 Gbps support. +.It Sy adv_cap_autoneg +Advertises auto-negotiation support. +.It Sy adv_cap_asmpause +Advertises asymmetric flow control support. +.It Sy adv_cap_pause +Advertises flow control support. +.It Sy adv_rem_fault +Remote fault status sent to peer. +.It Sy align_errors +Mis-aligned frames received. +.It Sy brdcstrcv +Broadcast frames received. +.It Sy brdcstxmt +Broadcast frames transmitted. +.It Sy cap_1000fdx +Device supports 1000 Mbps full-duplex. +.It Sy cap_1000hdx +Device supports 1000 Mbps half-duplex. +.It Sy cap_100fdx +Device supports 100 Mbps full-duplex. +.It Sy cap_100gfdx +Device supports 100 Gbps. +.It Sy cap_100hdx +Device supports 100 Mbps half-duplex. +.It Sy cap_100T4 +Device supports 100BASE-T4. +.It Sy cap_10fdx +Device supports 10 Mbps full-duplex. +.It Sy cap_10gfdx +Device supports 10 Gpbs. +.It Sy cap_10hdx +Device supports 10 Mbps half-duplex. +.It Sy cap_2500fdx +Device supports 2.5 Gbps. +.It Sy cap_50gfdx +Device supports 50 Gpbs. +.It Sy cap_40gfdx +Device supports 40 Gpbs. +.It Sy cap_25gfdx +Device supports 25 Gpbs. +.It Sy cap_5000fdx +Device supports 5 Gbps. +.It Sy cap_asmpause +Device supports asymmetric flow control. +.It Sy cap_autoneg +Device supports auto-negotiation. +.It Sy cap_pause +Device supports symmetric flow control. +.It Sy cap_rem_fault +Device supports remote fault notification. +.It Sy carrier_errors +Frames dropped due to loss of link. +.It Sy collisions +Collisions. +.It Sy defer_xmts +Transmits deferred due to link activity. +.It Sy ex_collisions +Frames dropped due to too many collisions. +.It Sy fcs_errors +Frames received with bad frame checksum. +.It Sy first_collisions +Frames with at least one collision. +.It Sy ierrors +Receive errors. +.It Sy ifspeed +Link speed in bits per second. +.It Sy ipackets Ns Op Sy 64 +Frames received successfully. +.It Sy jabber_errors +Jabber errors. +.It Sy link_asmpause +Asymmetric flow control; works together with +.Sy link_pause . +See the description for it below. +.It Sy link_autoneg +Link was auto-negotiated. +.It Sy link_duplex +Link duplex status, values as follows: +.Bl -column "0" infinity +.It 0 Ta Unknown. +.It 1 Ta Half-duplex. +.It 2 Ta Full-duplex. +.El +.It Sy link_pause +Link flow control available; works together with +.Sy link_asmpause . +The meanings of these bits are: +.Bl -column "pause" "asmpause" +.It Sy pause Ta Sy asmpause Ta Sy meaning +.It 0 Ta 0 Ta "No flow control." +.It 1 Ta 0 Ta Symmetric flow control. +.It 0 Ta 1 Ta Honor received pause frames. +.It 1 Ta 1 Ta Send pause frames when congested. +.El +.It Sy link_state +Link state; 0 for down, 1 for up. +.It Sy link_up +Link is up if 1. +.It Sy lp_cap_1000fdx +Peer supports 1000 Mbps full-duplex. +.It Sy lp_cap_1000hdx +Peer supports 1000 Mbps half-duplex. +.It Sy lp_cap_100fdx +Peer supports 100 Mbps full-duplex. +.It Sy lp_cap_100gfdx +Peer supports 100 Gbps full-duplex. +.It Sy lp_cap_100hdx +Peer supports 100 Mbps half-duplex. +.It Sy lp_cap_100T4 +Peer supports 100BASE-T4. +.It Sy lp_cap_10fdx +Peer supports 10 Mbps full-duplex. +.It Sy lp_cap_10gfdx +Peer supports 10 Gbps. +.It Sy lp_cap_10hdx +Peer supports 10 Mbps half-duplex. +.It Sy lp_cap_2500fdx +Peer supports 2.5 Gbps. +.It Sy lp_cap_5000fdx +Peer supports 5 Gbps. +.It Sy lp_cap_50gfdx +Peer supports 50 Gbps. +.It Sy lp_cap_40gfdx +Peer supports 40 Gbps. +.It Sy lp_cap_25gfdx +Peer supports 25 Gbps. +.It Sy lp_cap_asmpause +Peer supports asymmetric flow control. +.It Sy lp_cap_autoneg +Peer supports auto-negotiation. +.It Sy lp_cap_pause +Peer advertises flow control support. +.It Sy lp_rem_fault +Peer announces a remote fault. +.It Sy macrv_errors +Generic receive errors. +.It Sy macxmt_errors +Generic transmit errors. +.It Sy multi_collisions +Frames with more than one collision. +.It Sy multircv +Multicast frames received. +.It Sy multixmt +Multicast frames transmitted. +.It Sy norcvbuf +Receive frames dropped due to lack of resources. +.It Sy noxmtbuf +Transmit frames dropped due to lack of resources. +.It Sy obytes Ns Op Sy 64 +Bytes (octets) transmitted successfully. +.It Sy oerrors +Transmit errors. +.It Sy oflo +Overflow errors. +.It Sy opackets Ns Op Sy 64 +Frames successfully transmitted. +.It Sy promisc +Interface is in promiscuous mode. +.It Sy rbytes Ns Op Sy 64 +Bytes (octets) received successfully. +.It Sy runt_errors +Frames received that were too short. +.It Sy sqe_errors +Squelch errors. +.It Sy toolong_errors +Frames received that were too long. +.It Sy tx_late_collisions +Late collisions on transmit. +.It Sy uflo +Underflow errors. +.It Sy unknowns +Frames received with no local recipient. +.It Sy xcvr_addr +Transceiver address. +.It Sy xcvr_id +Transceiver vendor and device ID. +.It Sy xcvr_inuse +Identifies the type of transceiver in use. +Values are as follows: +.Bl -column "0" +.It 0 Ta Unknown or undefined. +.It 1 Ta None. +.It 2 Ta 10 Mbps +.It 3 Ta 100BASE-T4 +.It 4 Ta 100BASE-X +.It 5 Ta 100BASE-T2 +.It 6 Ta 1000BASE-X +.It 7 Ta 1000BASE-T +.El +.El +.Ss Properties +The following parameters are accessible with +.Xr dladm 8 . +Some of these are normally read-only. +Other properties that are not specific to IEEE 802.3 / Ethernet links are also +available via +.Xr dladm 8 , +and are documented in its man page rather than here. +. +.Bl -tag -width adv_1000hdx_cap +.It Sy speed +Link speed, in Mbps per second (dladm only). +.It Sy duplex +Link duplex, either "full" or "half". +.It Sy state +Link state, either "up" or "down". +.It Sy mtu +Maximum link frame size in bytes. +See +.Sx Jumbo Frames . +.It Sy flowctrl +Flow control setting, one of \(dqno\(dq, \(dqtx\(dq, \(dqrx\(dq, or \(dqbi\(dq. +See +.Sx Flow Control . +.It Sy adv_10gfdx_cap +Advertising 10 Gbps support. +.It Sy en_10gfdx_cap +Enable 10 Gbps support. +. +.It Sy adv_1000fdx_cap +Advertising 1000 Mbps full-duplex support. +.It Sy en_1000fdx_cap +Enable 1000 Mbps full-duplex. +. +.It Sy adv_1000hdx_cap +Advertising 1000 Mbps half-duplex support. +.It Sy en_1000hdx_cap +Enable 1000 Mbps half-duplex. +. +.It Sy adv_100fdx_cap +Advertising 100 Mbps full-duplex support. +.It Sy en_100fdx_cap +Enable 100 Mbps full-duplex. +. +.It Sy adv_100hdx_cap +Advertising 100 Mbps half-duplex support. +.It Sy en_100hdx_cap +Enable 100 Mbps half-duplex. +. +.It Sy adv_10fdx_cap +Advertising 10 Mbps full-duplex support. +.It Sy en_10fhdx_cap +Enable 100 Mbps full-duplex. +. +.It Sy adv_10hdx_cap +Advertising 10 Mbps half-duplex support. +.It Sy en_10fhdx_cap +Enable 10 Mbps half-duplex. +.El +.Ss Auto-negotiation +With modern devices, auto-negotiation is normally handled automatically. +With 10 Gbps and 1000 Gbps, it is mandatory (10GBASE-T also requires full-duplex +operation). +It is also +.Em strongly +recommended for use whenever possible; without auto-negotiation the link +will usually not operate unless both partners are configured to use the +same link mode. +.Lp +Auto-negotiation, when enabled, takes place by comparing the local capabilities +that have been advertised (which must also be supported by the local device), +with the capabilities that have been advertised by the link partner (peer). +. +The first of the following modes that is supported by both partners is +selected as the link negotiation result: +.Lp +.Bl -bullet -offset indent -compact +.It +10 Gbps (10gfdx) +.It +1000 Mbps full-duplex (1000fdx) +.It +1000 Mbps half-duplex (1000hdx) +.It +100 Mbps full-duplex (100fdx) +.It +100BASE-T4 (100T4) +.It +100 Mbps half-duplex (100hdx) +.It +10 Mbps full-duplex (10fdx) +.It +10 Mbps half-duplex (10hdx) +.El +.Lp +Advertisement of these modes can be enabled or disabled by setting the +appropriate +.Sy en_ +property in +.Xr dladm 8 . +.Lp +Auto-negotiation may also be disabled, by setting the +.Sy adv_autoneg_cap +property to 0. +In this case, the highest enabled link mode (using the above list) is +.Dq forced +for the link. +.Ss Flow Control +Link layer flow control is available on many modern devices, and is mandatory +for operation at 10 Gbps. +It requires that the link be auto-negotiated, and that the link be full-duplex, +in order to function. +.Lp +Flow control is applied when a receiver becomes congested. +In this case the receiver can send a special frame, called a pause frame, to +request its partner cease transmitting for a short period of time. +.Lp +Flow control can be said to be either symmetric, in which case both partners +can send and honor pause frames, or asymmetric, in which case one partner +may not transmit pause frames. +.Lp +The flow control mode used is driven by the +.Sy flowctrl +property. +It has the following meanings: +.Lp +.Bl -column -compact -offset indent Dv +.It \(dqno\(dq Ta Neither send, nor honor pause frames. +.It \(dqtx\(dq Ta Send pause frames, provided that the peer can support them, +but do not honor them. +.It \(dqrx\(dq Ta Receive and honor pause frames. +.It \(dqbi\(dq Ta Both send and receive (and honor) pause frames. +.El +.Lp +The statistics for flow control +.Po Sy adv_cap_pause , adv_cap_asmpause , lp_cap_pause , lp_cap_asmpause , +.Sy link_pause , +and +.Sy link_asmpause +.Pc +are based on the properties exchanged in the auto-negotiation and are +confusing as a result. +Administrators are advised to use the +.Sy flowctrl +property instead. +. +.Ss Jumbo Frames +The IEEE 802.3 standard specifies a standard frame size of 1518 bytes, +which includes a 4-byte frame checksum, a 14-byte header, and 1500 bytes +of payload. +Most devices support larger frame sizes than this, and when all possible parties +on the same local network can do so, it may be advantageous to choose a larger +frame size; 9000 bytes is the most common option, as it allows a transport layer +to convey 8 KB (8192) of data, while leaving room for various link, network, and +transport layer headers. +.Lp +Note that the use of frames carrying more than 1500 bytes of payload is +not standardized, even though it is common practice. +.Lp +The +.Sy mtu +property is used to configure the frame size. +Note that this is the size of the payload, and excludes the preamble, checksum, +and header. +It also excludes the tag for devices that support tagging (see +.Sx Virtual LANs +below). +.Lp +Care must be taken to ensure that all communication parties agree on the same +size, or communication may cease to function properly. +.Lp +Note that the +.Sy mtu +property refers to the link layer property. +It may be necessary to configure upper layer protocols such as IP to use a +different size when this changes. +See +.Xr ifconfig 8 . +. +.Ss Virtual LANs +Most devices support virtual LANs (and also priority control tagging) though +the use of a 4-byte tag inserted between the frame header and payload. +The details of configuration of this are covered in the +.Xr dladm 8 +manual. +. +.Ss Data Link Provider Interface (DLPI) Details +. +The correct method for applications to access Ethernet devices directly +is to use the DLPI. +See +.Xr dlpi 4P +and +.Xr libdlpi 3LIB +for further information. +.Lp +The following DLPI parameters are presented to applications. +.Bl -column -offset indent "Broadcast address" +.It Maximum SDU Ta 1500 (or larger, as determined by the Sy mtu No property.) +.It Minimum SDU Ta 0 +.It Address length Ta 6 +.It MAC type Ta Dv DL_ETHER +.It SAP length Ta \(mi2 +.It Service mode Ta Dv DL_CLDLS +.It Broadcast address Ta Li ff:ff:ff:ff:ff:ff No (6 bytes with all bits set) +.El +.Lp +Note that if the application binds to SAP of 0, then standard IEEE 802.3 +mode is assumed and the frame length is stored in place of the Ethernet type. +Frames that arrive with the type field set to 1500 or less, are delivered +to applications that bind to SAP 0. +.Lp +Ethernet drivers on the support both DLPI style 1 and style 2 operation. +Additionally, it is possible to configure provide +.Dq vanity +names to interfaces using the +.Xr dladm 8 +.Sy rename-link +subcommand. +Such vanity names are only accessible using DLPI style 1. +.Sh NOTES +There may be other mechanisms available to configure link layer properties. +Historically the +.Xr ndd 8 +command, and +.Xr driver.conf 5 +files could be used to do this. +These methods are deprecated in favor of +.Xr dladm 8 +properties. +. +.Sh INTERFACE STABILITY +When present, the statistics and properties presented here +are +.Sy Committed . +However, note that not every Ethernet device supports all of these, +and some devices may support additional statistics and properties. +.Lp +The DLPI and IEEE 802.3 itself are +.Sy Standard . +.Sh SEE ALSO +.Xr libdlpi 3LIB , +.Xr dlpi 4P , +.Xr driver.conf 5 , +.Xr dladm 8 , +.Xr ifconfig 8 , +.Xr kstat 8 , +.Xr ndd 8 , +.Xr netstat 8 +.Rs +.%T IEEE 802.3: Ethernet +.%Q IEEE Standards Association +.Re +.Rs +.%B Data Link Provider Interface (DLPI) +.%Q The Open Group +.%D 1997 +.Re +.Rs +.%B STREAMs Programming Guide +.%Q Sun Microsystems, Inc. +.%D January 2005 +.Re diff --git a/usr/src/man/man7/ipfilter.7 b/usr/src/man/man7/ipfilter.7 new file mode 100644 index 0000000000..ff960929d2 --- /dev/null +++ b/usr/src/man/man7/ipfilter.7 @@ -0,0 +1,341 @@ +'\" te +.\" 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. +.TH IPFILTER 7 "Oct 7, 2014" +.SH NAME +ipfilter \- IP packet filtering software +.SH DESCRIPTION +.LP +IP Filter is software that provides packet filtering capabilities on a Solaris +system. On a properly setup system, it can be used to build a firewall. +.sp +.LP +Solaris IP Filter is installed with the Solaris operating system. However, +packet filtering is not enabled by default. See \fBipf\fR(8) for a procedure +to enable and activate the IP Filter feature. +.SH HOST-BASED FIREWALL +.LP +To simplify IP Filter configuration management, a firewall framework is created +to allow users to configure IP Filter by expressing firewall policy at system +and service level. Given the user-defined firewall policy, the framework +generates a set of IP Filter rules to enforce the desired system behavior. +Users specify system and service firewall policies that allow or deny network +traffic from certain hosts, subnets, and interface(s). The policies are +translated into a set of active IPF rules to enforce the specified firewall +policies. +.LP +Note - +.sp +.RS 2 +Users can still specify their own ipf rule file if they choose not to take +advantage of the framework. See \fBipf\fR(8) and \fBipf\fR(5). +.RE +.SS "Model" +.LP +This section describes the host-based firewall framework. See svc.ipfd(8) for +details on how to configure firewall policies. +.sp +.LP +In a given zone, a three-layer approach with different precedence levels helps +the user achieve the desired behaviors. +.sp +.ne 2 +.na +\fBGlobal Default\fR +.ad +.sp .6 +.RS 4n +Global Default - Default system-wide firewall policy. This policy is +automatically inherited by all services unless services modify their firewall +policy. +.RE + +.sp +.ne 2 +.na +\fBNetwork Services\fR +.ad +.sp .6 +.RS 4n +Higher precedence than Global Default. A service's policy allows/disallows +traffic to its specific ports, regardless of Global Default policy. +.RE + +.sp +.ne 2 +.na +\fBGlobal Override\fR +.ad +.sp .6 +.RS 4n +Another system-wide policy that takes precedence over the needs of specific +services in Network Services layer. +.RE + +.sp +.in +2 +.nf +Global Override + | + | +Network Services + | + | +Global Default +.fi +.in -2 +.sp + +.sp +.LP +A firewall policy includes a firewall mode and an optional set of network +sources. Network sources are IP addresses, subnets, and local network +interfaces, from all of which a system can receive incoming traffic. The basic +set of firewall modes are: +.sp +.ne 2 +.na +\fBNone\fR +.ad +.sp .6 +.RS 4n +No firewall, allow all incoming traffic. +.RE + +.sp +.ne 2 +.na +\fBDeny\fR +.ad +.sp .6 +.RS 4n +Allow all incoming traffic but deny from specified source(s). +.RE + +.sp +.ne 2 +.na +\fBAllow\fR +.ad +.sp .6 +.RS 4n +Deny all incoming traffic but allow from specified source(s). +.RE + +.SS "Layers in Detail" +.LP +The first system-wide layer, Global Default, defines a firewall policy that +applies to \fBany\fR incoming traffic, for example, allowing or blocking all +traffic from an IP address. This makes it simple to have a policy that blocks +all incoming traffic or all incoming traffic from unwanted source(s). +.sp +.LP +The Network Services layer contains firewall policies for local programs that +provide service to remote clients, for example, \fBtelnetd\fR, \fBsshd\fR, and +\fBhttpd\fR. Each of these programs, a network service, has its own firewall +policy that controls access to its service. Initially, a service's policy is +set to inherit Global Default policy, a "Use Global Default" mode. This makes +it simple to set a single policy, at the Global Default layer, that can be +inherited by all services. +.sp +.LP +When a service's policy is different from Global Default policy, the service's +policy has higher precedence. If Global Default policy is set to block all +traffic from a subnet, the SSH service could be configured to allow access from +certain hosts in that subnet. The set of all policies for all network services +comprises the Network Service layer. +.sp +.LP +The second system-wide layer, Global Override, has a firewall policy that also +applies to any incoming network traffic. This policy has highest precedence and +overrides policies in the other layers, specifically overriding the needs of +network services. The example is when it is desirable to block known malicious +source(s) regardless of services' policies. +.SS "User Interaction" +.LP +This framework leverages IP Filter functionality and is active only when +\fBsvc:/network/ipfilter\fR is enabled and inactive when \fBnetwork/ipfilter\fR +is disabled. Similarly, a network service's firewall policy is only active when +that service is enabled and inactive when the service is disabled. A system +with an active firewall has IP Filter rules for each running/enabled network +service and system-wide policy(s) whose firewall mode is not \fBNone\fR. +.sp +.LP +A user configures a firewall by setting the system-wide policies and policy for +each network service. See svc.ipfd(8) on how to configure a firewall policy. +.sp +.LP +The firewall framework composes of policy configuration and a mechanism to +generate IP Filter rules from the policy and applying those rules to get the +desired IP Filter configuration. A quick summary of the design and user +interaction: +.RS +4 +.TP +.ie t \(bu +.el o +system-wide policy(s) are stored in \fBnetwork/ipfilter\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +network services' policies are stored in each SMF service +.RE +.RS +4 +.TP +.ie t \(bu +.el o +a user activates a firewall by enabling \fBnetwork/ipfilter\fR (see +\fBipf\fR(8)) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +a user activates/deactivate a service's firewall by enabling/disabling that +network service +.RE +.RS +4 +.TP +.ie t \(bu +.el o +changes to system-wide or per-service firewall policy results in an update to +the system's firewall rules + +.SS "In-Zone and Global Zone Controlled firewalls" +.LP +Each non-global zone in the system can potentially have two firewalls +configured: the in-zone firewall and the Global Zone controlled (GZ-controlled) +firewall. The in-zone firewall can be controlled and observed inside the zone +using the framework detailed above, or from the Global Zone. The GZ-controlled +firewall can only be controlled and observed from the Global Zone. The +GZ-controlled firewall is always "outermost" with respect to the zone. +.sp +.LP +For inbound traffic (from an external source to the zone), the traffic flow looks +like the following diagram. Traffic blocked by the GZ-controlled firewall will +not be processed by the in-zone firewall. +.sp +.in +2 +.nf + External Source + | + | +GZ-controlled Firewall + | + | + In-Zone Firewall + | + | + Zone +.fi +.in -2 +.sp +.LP +For outbound traffic (from the zone to an external destination), the traffic +flow looks like the following diagram. Traffic blocked by the in-zone firewall +will not be processed by the GZ-controlled firewall. +.sp +.in +2 +.nf + Zone + | + | + In-Zone Firewall + | + | +GZ-controlled Firewall + | + | + External Destination +.fi +.in -2 +.sp +.LP +Either of the in-Zone or GZ-controlled firewalls can be enabled, or both at the +same time. +.sp +.LP +The Global Zone does not have a GZ-controlled firewall, only an +in-zone firewall. For inbound traffic (from an external source to the global +zone), the traffic flow therefore looks like the following diagram. +.sp +.in +2 +.nf + External Source + | + | + In-Zone Firewall + | + | + Zone +.fi +.in -2 +.sp +.LP +For outbound traffic (from the global zone to an external destination), the +traffic flow looks like the following diagram. +.sp +.in +2 +.nf + Zone + | + | + In-Zone Firewall + | + | + External Destination +.fi +.in -2 + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +.TE + +.SH SEE ALSO +.LP +.BR svcs (1), +.BR ipf (5), +.BR ipnat (5), +.BR attributes (7), +.BR smf (7), +.BR ipf (8), +.BR ipnat (8), +.BR svc.ipfd (8), +.BR svcadm (8) +.sp +.LP +\fISystem Administration Guide: IP Services\fR +.SH NOTES +.LP +The \fBipfilter\fR service is managed by the service management facility, +\fBsmf\fR(7), under the service identifier: +.sp +.in +2 +.nf +svc:/network/ipfilter:default +.fi +.in -2 +.sp + +.sp +.LP +Administrative actions on this service, such as enabling, disabling, or +requesting restart, can be performed using \fBsvcadm\fR(8). The service's +status can be queried using the \fBsvcs\fR(1) command. +.sp +.LP +IP Filter startup configuration files are stored in \fB/etc/ipf\fR. diff --git a/usr/src/man/man7/isalist.7 b/usr/src/man/man7/isalist.7 new file mode 100644 index 0000000000..452deadf17 --- /dev/null +++ b/usr/src/man/man7/isalist.7 @@ -0,0 +1,227 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ISALIST 7 "Mar 20, 2008" +.SH NAME +isalist \- the native instruction sets known to Solaris software +.SH DESCRIPTION +.sp +.LP +The possible instruction set names returned by \fBisalist\fR(1) and the +\fBSI_ISALIST\fR command of \fBsysinfo\fR(2) are listed here. +.sp +.LP +The list is ordered within an instruction set family in the sense that later +names are generally faster then earlier names; note that this is in the reverse +order than listed by \fBisalist\fR(1) and \fBsysinfo\fR(2). In the following +list of values, numbered entries generally represent increasing performance; +lettered entries are either mutually exclusive or cannot be ordered. +.sp +.LP +This feature is obsolete and may be removed in a future version of Solaris. The +lists below do not reflect all the extensions that have been made by modern +processors. See \fBgetisax\fR(2) for a better way to handle instruction set +extensions. +.SS "SPARC Platforms" +.sp +.LP +Where appropriate, correspondence with a given value of the \fB-xarch\fR option +of Sun's C 4.0 compiler is indicated. Other compilers might have similar +options. +.sp +.ne 2 +.na +\fB1a. \fBsparc\fR\fR +.ad +.RS 27n +Indicates the SPARC V8 instruction set, as defined in \fI\fR The SPARC +Architecture Manual, Version 8, Prentice-Hall, Inc., 1992. Some instructions +(such as integer multiply and divide, FSMULD, and all floating point operations +on quad operands) can be emulated by the kernel on certain systems. +.RE + +.sp +.ne 2 +.na +\fB1b. \fBsparcv7\fR\fR +.ad +.RS 27n +Same as sparc. This corresponds to code produced with the -xarch=v7 option of +Sun's C 4.0 compiler. +.RE + +.sp +.ne 2 +.na +\fB2. \fBsparcv8-fsmuld\fR\fR +.ad +.RS 27n +Like sparc, except that integer multiply and divide must be executed in +hardware. This corresponds to code produced with the -xarch=v8a option of Sun's +C 4.0 compiler. +.RE + +.sp +.ne 2 +.na +\fB3. \fBsparcv8\fR\fR +.ad +.RS 27n +Like sparcv8-fsmuld, except that FSMULD must also be executed in hardware. This +corresponds to code produced with the -xarch=v8 option of Sun's C 4.0 compiler. +.RE + +.sp +.ne 2 +.na +\fB4. \fBsparcv8plus\fR\fR +.ad +.RS 27n +Indicates the SPARC V8 instruction set plus those instructions in the SPARC V9 +instruction set, as defined in \fI\fR The SPARC Architecture Manual, Version 9, +Prentice-Hall, 1994, that can be used according to \fI\fR The V8+ Technical +Specification. This corresponds to code produced with the -xarch=v8plus option +of Sun's C 4.0 compiler. +.RE + +.sp +.ne 2 +.na +\fB5a. \fBsparcv8plus+vis\fR\fR +.ad +.RS 27n +Like sparcv8plus, with the addition of those UltraSPARC I Visualization +Instructions that can be used according to \fI\fR The V8+ Technical +Specification. This corresponds to code produced with the -xarch=v8plusa option +of Sun's C 4.0 compiler. +.RE + +.sp +.ne 2 +.na +\fB5b. \fBsparcv8plus+fmuladd\fR\fR +.ad +.RS 27n +Like sparcv8plus, with the addition of the Fujitsu SPARC64 floating +multiply-add and multiply-subtract instructions. +.RE + +.sp +.ne 2 +.na +\fB6. \fBsparcv9\fR\fR +.ad +.RS 27n +Indicates the SPARC V9 instruction set, as defined in \fI\fR The SPARC +Architecture Manual, Version 9, Prentice-Hall, 1994. +.RE + +.sp +.ne 2 +.na +\fB7a. \fBsparcv9+vis\fR\fR +.ad +.RS 27n +Like sparcv9, with the addition of the UltraSPARC I Visualization Instructions. +.RE + +.sp +.ne 2 +.na +\fB7b. \fBsparcv9+vis2\fR\fR +.ad +.RS 27n +Like sparcv9, with the addition of the UltraSPARC III Visualization +Instructions. +.RE + +.sp +.ne 2 +.na +\fB7c. \fBsparcv9+fmuladd\fR\fR +.ad +.RS 27n +Like sparcv9, with the addition of the Fujitsu SPARC64 floating multiply-add +and multiply-subtract instructions. +.RE + +.SS "x86 Platforms" +.sp +.ne 2 +.na +\fB1. \fBi386\fR\fR +.ad +.RS 22n +The Intel 80386 instruction set, as described in \fI\fR The i386 Microprocessor +Programmer's Reference Manual. +.RE + +.sp +.ne 2 +.na +\fB2. \fBi486\fR\fR +.ad +.RS 22n +The Intel 80486 instruction set, as described in \fI\fR The i486 Microprocessor +Programmer's Reference Manual. (This is effectively i386, plus the CMPXCHG, +BSWAP, and XADD instructions.) +.RE + +.sp +.ne 2 +.na +\fB3. \fBpentium\fR\fR +.ad +.RS 22n +The Intel Pentium instruction set, as described in \fI\fR The Pentium Processor +User's Manual. (This is effectively i486, plus the CPU_ID instruction, and any +features that the CPU_ID instruction indicates are present.) +.RE + +.sp +.ne 2 +.na +\fB4. \fBpentium+mmx\fR\fR +.ad +.RS 22n +Like pentium, with the MMX instructions guaranteed present. +.RE + +.sp +.ne 2 +.na +\fB5. \fBpentium_pro\fR\fR +.ad +.RS 22n +The Intel PentiumPro instruction set, as described in \fI\fR The PentiumPro +Family Developer's Manual. (This is effectively pentium, with the CMOVcc, +FCMOVcc, FCOMI, and RDPMC instructions guaranteed present.) +.RE + +.sp +.ne 2 +.na +\fB6. \fBpentium_pro+mmx\fR\fR +.ad +.RS 22n +Like pentium_pro, with the MMX instructions guaranteed present. +.RE + +.sp +.ne 2 +.na +\fB7. \fBamd64\fR\fR +.ad +.RS 22n +The AMD Opteron instruction set, as described in the \fIAMD64 Architecture +Programmer's Manual\fR. +.RE + +.SH SEE ALSO +.sp +.LP +.BR isalist (1), +.BR getisax (2), +.BR sysinfo (2) diff --git a/usr/src/man/man7/isoboot.7 b/usr/src/man/man7/isoboot.7 new file mode 100644 index 0000000000..eac855dcbe --- /dev/null +++ b/usr/src/man/man7/isoboot.7 @@ -0,0 +1,66 @@ +.\" Copyright (c) 2018 iXsystems, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS 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 AUTHORS 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. +.\" +.Dd March 30, 2018 +.Dt ISOBOOT 7 +.Os +.Sh NAME +.Nm isoboot +.Nd Boot code for hybrid ISO/USB images on BIOS-based computers +.Sh DESCRIPTION +.Nm +is used on BIOS-based computers to boot from an ISO image that has +been written to a USB flash drive or other HDD-like device. +.Nm +is installed in a +.Cm x86 Boot +partition with +.Xr installboot 8 . +.Sh IMPLEMENTATION NOTES +The El Torito standard for bootable CDs provides a 32KB "System Area" +at the beginning of an image. +To create an image that is able to be booted by the BIOS as either a +CD-ROM ("ISO") and as a more HDD-like image (e.g. on a USB flash drive) +it is necessary to have both a standard El Torito boot catalog +containing a HDD-style partition table and boot code. +.Nm +is intended to be placed in a MBR x86 boot partition to allow the system to find +the standard +.Fx +.Xr loader 7 +in the ISO filesystem later in the image. +.Sh BOOTING +.Nm +looks for an ISO filesystem image on the device it was booted from and +seeks to read the primary illumos +.Xr loader 7 +from there. +.Sh SEE ALSO +.Xr installboot 8 +.Sh HISTORY +.Nm +appeared in FreeBSD 12.0. +.Sh AUTHORS +This manual page written by +.An Benno Rice Aq benno@FreeBSD.org . diff --git a/usr/src/man/man7/kerberos.7 b/usr/src/man/man7/kerberos.7 new file mode 100644 index 0000000000..f2873db09b --- /dev/null +++ b/usr/src/man/man7/kerberos.7 @@ -0,0 +1,162 @@ +'\" te +.\" Copyright 2014 Nexenta Systems, Inc. All rights reserved. +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH KERBEROS 7 "November 22, 2021" +.SH NAME +kerberos \- overview of Solaris Kerberos implementation +.SH DESCRIPTION +The Solaris Kerberos implementation, hereafter sometimes shortened to +"Kerberos," authenticates clients in a network environment, allowing for secure +transactions. (A client may be a user or a network service.) Kerberos validates +the identity of a client and the authenticity of transferred data. Kerberos is +a \fIsingle-sign-on\fR system, meaning that a user needs to provide a password +only at the beginning of a session. The Solaris Kerberos implementation is +based on the Kerberos(TM) system developed at \fBMIT\fR, and is compatible with +Kerberos V5 systems over heterogeneous networks. +.sp +.LP +Kerberos works by granting clients \fItickets\fR, which uniquely identify a +client, and which have a finite lifetime. A client possessing a ticket is +automatically validated for network services for which it is entitled; for +example, a user with a valid Kerberos ticket may rlogin into another machine +running Kerberos without having to identify itself. Because each client has a +unique ticket, its identity is guaranteed. +.sp +.LP +To obtain tickets, a client must first initialize the Kerberos session, either +by using the \fBkinit\fR(1) command or a \fBPAM\fR module. (See +\fBpam_krb5\fR(7)). \fBkinit\fR prompts for a password, and then communicates +with a \fIKey Distribution Center\fR (\fBKDC\fR). The \fBKDC\fR returns a +\fITicket-Granting Ticket\fR (\fBTGT\fR) and prompts for a confirmation +password. If the client confirms the password, it can use the Ticket-Granting +Ticket to obtain tickets for specific network services. Because tickets are +granted transparently, the user need not worry about their management. Current +tickets may be viewed by using the \fBklist\fR(1) command. +.sp +.LP +Tickets are valid according to the system \fIpolicy\fR set up at installation +time. For example, tickets have a default lifetime for which they are valid. A +policy may further dictate that privileged tickets, such as those belonging to +root, have very short lifetimes. Policies may allow some defaults to be +overruled; for example, a client may request a ticket with a lifetime greater +or less than the default. +.sp +.LP +Tickets can be renewed using \fBkinit\fR. Tickets are also \fIforwardable\fR, +allowing you to use a ticket granted on one machine on a different host. +Tickets can be destroyed by using \fBkdestroy\fR(1). It is a good idea to +include a call to \fBkdestroy\fR in your \fB\&.logout\fR file. +.sp +.LP +Under Kerberos, a client is referred to as a \fIprincipal\fR. A principal takes +the following form: +.sp +.in +2 +.nf +primary/instance@REALM +.fi +.in -2 +.sp + +.sp +.ne 2 +.na +\fBprimary\fR +.ad +.RS 12n +A user, a host, or a service. +.RE + +.sp +.ne 2 +.na +\fBinstance\fR +.ad +.RS 12n +A qualification of the primary. If the primary is a host \(em indicated by the +keyword \fBhost\fR\(em then the instance is the fully-qualified domain name of +that host. If the primary is a user or service, then the instance is optional. +Some instances, such as \fBadmin\fR or \fBroot\fR, are privileged. +.RE + +.sp +.ne 2 +.na +\fBrealm\fR +.ad +.RS 12n +The Kerberos equivalent of a domain; in fact, in most cases the realm is +directly mapped to a \fBDNS\fR domain name. Kerberos realms are given in +upper-case only. For examples of principal names, see the EXAMPLES. +.RE + +.sp +.LP +By taking advantage of the General Security Services \fBAPI\fR (\fBGSS-API\fR), +Kerberos offers, besides user authentication, two other types of security +service: \fIintegrity\fR, which authenticates the validity of transmitted data, +and \fIprivacy\fR, which encrypts transmitted data. Developers can take +advantage of the \fBGSS-API\fR through the use of the RPCSEC_GSS \fBAPI\fR +interface (see \fBrpcsec_gss\fR(3NSL)). +.SH EXAMPLES +\fBExample 1 \fRExamples of valid principal names +.sp +.LP +The following are examples of valid principal names: + +.sp +.in +2 +.nf + joe + joe/admin + joe@ENG.EXAMPLE.COM + joe/admin@ENG.EXAMPLE.COM + rlogin/bigmachine.eng.example.com@ENG.EXAMPLE.COM + host/bigmachine.eng.example.com@ENG.EXAMPLE.COM +.fi +.in -2 +.sp + +.sp +.LP +The first four cases are \fIuser principals\fR. In the first two cases, it is +assumed that the user \fBjoe\fR is in the same realm as the client, so no realm +is specified. Note that \fBjoe\fR and \fBjoe/admin\fR are different principals, +even if the same user uses them; \fBjoe/admin\fR has different privileges from +\fBjoe\fR. The fifth case is a \fIservice principal\fR, while the final case is +a \fIhost principal\fR. The word \fBhost\fR is required for host principals. +With host principals, the instance is the fully qualified hostname. Note that +the words \fBadmin\fR and \fBhost\fR are reserved keywords. + +.SH SEE ALSO +.BR kdestroy (1), +.BR kinit (1), +.BR klist (1), +.BR kpasswd (1), +.BR krb5.conf (5), +.BR krb5envvar (7) +.sp +.LP +\fISystem Administration Guide: Security Services\fR +.SH NOTES +In previous releases of the Solaris operating system, the Solaris Kerberos +implementation was referred to as the "Sun Enterprise Authentication Mechanism" +(SEAM). +.sp +.LP +If you enter your username and \fBkinit\fR responds with this message: +.sp +.in +2 +.nf +Principal unknown (kerberos) +.fi +.in -2 +.sp + +.sp +.LP +you have not been registered as a Kerberos user. See your system administrator +or the \fISystem Administration Guide: Security Services\fR. diff --git a/usr/src/man/man7/krb5_auth_rules.7 b/usr/src/man/man7/krb5_auth_rules.7 new file mode 100644 index 0000000000..cf0f3c87e6 --- /dev/null +++ b/usr/src/man/man7/krb5_auth_rules.7 @@ -0,0 +1,129 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH KRB5_AUTH_RULES 7 "November 22, 2021" +.SH NAME +krb5_auth_rules \- overview of Kerberos V5 authorization +.SH DESCRIPTION +When kerberized versions of the \fBftp\fR, \fBrdist\fR, \fBrcp\fR, +\fBrlogin\fR, \fBrsh\fR, \fBtelnet\fR, or \fBssh\fR clients are used to connect +to a server, the identity of the originating user must be authenticated to the +Kerberos V5 authentication system. Account access can then be authorized if +appropriate entries exist in the \fB~/.k5login\fR file, the \fBgsscred\fR +table, or if the default GSS/Kerberos authentication rules successfully map the +Kerberos principal name to Unix login name. +.sp +.LP +To avoid security problems, the \fB~/.k5login\fR file must be owned by the +remote user on the server the client is attempting to access. The file should +contain a private authorization list comprised of Kerberos principal names of +the form \fIprincipal/instance\fR@\fIrealm\fR. The \fI/instance\fR variable is +optional in Kerberos principal names. For example, different principal names +such as \fBjdb@ENG.EXAMPLE.COM\fR and \fBjdb/happy.eng.example.com@ENG.EXAMPLE.COM\fR +would each be legal, though not equivalent, Kerberos principals. The client is +granted access if the \fB~/.k5login\fR file is located in the login directory +of the remote user account and if the originating user can be authenticated to +one of the principals named in the file. See \fBkadm5.acl\fR(5) for more +information on Kerberos principal names. +.sp +.LP +When no \fB~/.k5login\fR file is found in the remote user's login account, the +Kerberos V5 principal name associated with the originating user is checked +against the \fBgsscred\fR table. If a \fBgsscred\fR table exists and the +principal name is matched in the table, access is granted if the Unix user ID +listed in the table corresponds to the user account the client is attempting to +access. If the Unix user ID does not match, access is denied. See +\fBgsscred\fR(8). +.sp +.LP +For example, an originating user listed in the \fBgsscred\fR table with the +principal name \fBjdb@ENG.EXAMPLE.COM\fR and the \fBuid\fR \fB23154\fR is granted +access to the \fBjdb-user\fR account if \fB23154\fR is also the \fBuid\fR of +\fBjdb-user\fR listed in the user account database. See \fBpasswd\fR(5). +.sp +.LP +Finally, if there is no \fB~/.k5login\fR file and the Kerberos V5 identity of +the originating user is not in the \fBgsscred\fR table, or if the \fBgsscred\fR +table does not exist, the client is granted access to the account under the +following conditions (default GSS/Kerberos auth rules): +.RS +4 +.TP +.ie t \(bu +.el o +The user part of the authenticated principal name is the same as the Unix +account name specified by the client. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The realm part of the client and server are the same, unless the +\fBkrb5.conf\fR(5) \fIauth_to_local_realm\fR parameter is used to create +equivalence. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The Unix account name exists on the server. +.RE +.sp +.LP +For example, if the originating user has the principal name +\fBjdb@ENG.EXAMPLE.COM\fR and if the server is in realm \fBSALES.EXAMPLE.COM\fR, the +client would be denied access even if \fBjdb\fR is a valid account name on the +server. This is because the realms \fBSALES.EXAMPLE.COM\fR and \fBENG.EXAMPLE.COM\fR +differ. +.sp +.LP +The \fBkrb5.conf\fR(5) \fIauth_to_local_realm\fR parameter also affects +authorization. Non-default realms can be equated with the default realm for +authenticated \fBname-to-local name\fR mapping. +.SH FILES +.ne 2 +.na +\fB\fB~/.k5login\fR\fR +.ad +.RS 15n +Per user-account authorization file. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/passwd\fR\fR +.ad +.RS 15n +System account file. This information may also be in a directory service. See +\fBpasswd\fR(5). +.RE + +.SH ATTRIBUTES +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +.TE + +.SH SEE ALSO +.BR ftp (1), +.BR rcp (1), +.BR rdist (1), +.BR rlogin (1), +.BR rsh (1), +.BR telnet (1), +.BR kadm5.acl (5), +.BR krb5.conf (5), +.BR passwd (5), +.BR attributes (7), +.BR gss_auth_rules (7), +.BR gsscred (8) diff --git a/usr/src/man/man7/krb5envvar.7 b/usr/src/man/man7/krb5envvar.7 new file mode 100644 index 0000000000..6d180f9600 --- /dev/null +++ b/usr/src/man/man7/krb5envvar.7 @@ -0,0 +1,235 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH KRB5ENVVAR 7 "Feb 13, 2008" +.SH NAME +krb5envvar \- Kerberos environment variables +.SH DESCRIPTION +.sp +.LP +The Kerberos mechanism provides a number of environment variables to configure +different behavior in order to meet applications' needs. Environment variables +used within the Kerberos mechanism are: +.sp +.ne 2 +.na +\fB\fBKRB5_KTNAME\fR\fR +.ad +.sp .6 +.RS 4n +Used by the mechanism to specify the location of the key table file. The +variable can be set to the following value: +.sp +.in +2 +.nf +[[\fI<kt type>\fR:]\fI<file name>\fR] +.fi +.in -2 + +where \fI<kt type>\fR can be \fBFILE\fR or \fBWRFILE\fR. \fBFILE\fR is for read +operations; \fBWRFILE\fR is for write operations. \fI<file name>\fR is the +location of the \fBkeytab\fR file. +.sp +r +.sp +If \fBKRB5_KTNAME\fR is not defined, the default value is: +.sp +.in +2 +.nf +FILE:/etc/krb5/krb5.keytab +.fi +.in -2 + +The \fBkeytab\fR file is used to store credentials persistently and is used +commonly for service daemons. +.sp +Specifying the \fBFILE\fR type assumes that the subsequent operations on the +associated file are readable by the invoking process. Care must be taken to +ensure that the file is readable only by the set of principals that need to +retrieve their unencrypted keys. +.sp +The \fBWRFILE\fR type is used by the \fBkadmin\fR(8) command. Specifying this +type allows the administrator to designate an alternate \fBkeytab\fR file to +write to without using extra command line arguments for file location. +.RE + +.sp +.ne 2 +.na +\fB\fBKRB5CCNAME\fR\fR +.ad +.sp .6 +.RS 4n +Used by the mechanism to specify the location of the credential cache. The +variable can be set to the following value: +.sp +.in +2 +.nf +[[\fI<cc type>\fR:]\fI<file name>\fR] +.fi +.in -2 + +where \fI<cc type>\fR can be \fBFILE\fR or \fBMEMORY\fR. \fI<file name>\fR is +the location of the principal's credential cache. +.sp +If \fBKRB5CCNAME\fR is not defined, the default value is: +.sp +.in +2 +.nf +FILE:/tmp/krb5cc_\fI<uid>\fR +.fi +.in -2 + +where \fI<uid>\fR is the user id of the process that created the cache file. +.sp +The credential cache file is used to store tickets that have been granted to +the principal. +.sp +Specifying the \fBFILE\fR types assumes that subsequent operations on the +associated file are readable and writable by the invoking process. Care must be +taken to ensure that the file is accessible only by the set of principals that +need to access their credentials. If the credential file is in a directory to +which other users have write access, you need to set that directory's sticky +bit (see \fBchmod\fR(1)). +.sp +The \fBMEMORY\fR credential cache type is used only in special cases, such as +when making a temporary cache for the life of the invoking process. +.RE + +.sp +.ne 2 +.na +\fB\fBKRB5RCNAME\fR\fR +.ad +.sp .6 +.RS 4n +Used by the mechanism to specify the type and location of the replay cache. The +variable can be set to the following value: +.sp +.in +2 +.nf +[[\fI<rc type>\fR:]\fI<file name>\fR] +.fi +.in -2 + +where \fI<rc type>\fR can be either \fBFILE\fR, \fBMEMORY\fR, or \fBNONE\fR. +\fI<file name>\fR is relevant only when specifying the replay cache file type. +.sp +If not defined, the default value is: +.sp +.in +2 +.nf +FILE:/var/krb5/rcache/root/rc_\fI<service>\fR +.fi +.in -2 + +\&...if the process is owned by root, or: +.sp +.in +2 +.nf +FILE:/var/krb5/rcache/rc_\fI<service>\fR +.fi +.in -2 + +\&...if the process is owned by a user other than root. \fI<service>\fR is the +service process name associated with the replay cache file. +.sp +The replay cache is used by Kerberos to detect the replay of authentication +data. This prevents people who capture authentication messages on the network +from authenticating to the server by resending these messages. +.sp +When specifying the \fBFILE\fR replay cache type, care must be taken to prevent +the replay cache file from being deleted by another user. Make sure that every +directory in the replay cache path is either writable only by the owner of the +replay cache or that the sticky bit ("\fBt\fR") is set on every directory in +the replay cache path to which others have write permission. +.sp +When specifying the \fBMEMORY\fR replay cache type you need to weigh the +trade-off of performance against the slight security risk created by using a +non-persistent cache. The risk occurs during system reboots when the following +condition obtains: +.RS +4 +.TP +.ie t \(bu +.el o +The duration from the last write to the replay cache before reboot to the point +when the Kerberized server applications are running is less than the Kerberos +clockskew (see \fBkrb5.conf\fR(5)). +.RE +When specifying the \fBNONE\fR replay cache time you need to understand that +this disables the replay cache, and all security risks that this presents. This +includes all the risks outlined in this section of the man page. +.sp +Under this condition, the server applications can accept a replay of Kerberos +authentication data (up to the difference between the time of the last write +and the clockskew). Typically, this is a small window of time. If the server +applications take longer than the clockskew to start accepting connections +there is no replay risk. +.sp +The risk described above is the same when using \fBFILE\fR replay cache types +when the replay cache resides on swap file systems, such as \fB/tmp\fR and +\fB/var/run\fR. +.sp +The performance improvement in \fBMEMORY\fR replay cache types over \fBFILE\fR +types is derived from the absence of disk I/O. This is true even if the +\fBFILE\fR replay cache is on a memory-backed file system, such as swap +(\fB/tmp\fR and \fB/var/run\fR). +.sp +Note that \fBMEMORY\fR-type caches are per-process caches, therefore use of +these types of caches must be carefully considered. One example of where +\fBMEMORY\fR-type caches can be problematic is when an application uses more +than one process for establishing security contexts. In such a case, memory +replay caches are not shared across the processes, thus allowing potential for +replay attacks. +.RE + +.sp +.ne 2 +.na +\fBKRB5_CONFIG\fR +.ad +.sp .6 +.RS 4n +Allows you to change the default location of the \fB/etc/krb5/krb5.conf\fR file +to enable the Kerberos library code to read configuration parameters from +another file specified by KRB5_CONFIG. For example (using kinit from +\fBksh\fR(1)): +.sp +.in +2 +.nf + KRB5_CONFIG=/var/tmp/krb5.conf kinit +.fi +.in -2 + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Uncommitted +.TE + +.SH SEE ALSO +.sp +.LP +.BR chmod (1), +.BR kinit (1), +.BR klist (1), +.BR ksh (1), +.BR krb5.conf (5), +.BR attributes (7), +.BR kerberos (7), +.BR kadmin (8), +.BR kadmind (8) diff --git a/usr/src/man/man7/largefile.7 b/usr/src/man/man7/largefile.7 new file mode 100644 index 0000000000..bcb70cd8e2 --- /dev/null +++ b/usr/src/man/man7/largefile.7 @@ -0,0 +1,231 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved +.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures +.\" Copyright 2015 Nexenta Systems, 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 LARGEFILE 7 "Sep 8, 2015" +.SH NAME +largefile \- large file status of utilities +.SH DESCRIPTION +.LP +A \fIlarge file\fR is a regular file whose size is greater than or equal to 2 +Gbyte ( 2^31 bytes). A \fIsmall file\fR is a regular file whose size is less +than 2 Gbyte. +.SS "Large file aware utilities" +.LP +A utility is called \fIlarge file aware\fR if it can process large files in the +same manner as it does small files. A utility that is large file aware is able +to handle large files as input and generate as output large files that are +being processed. The exception is where additional files are used as system +configuration files or support files that can augment the processing. For +example, the \fBfile\fR utility supports the \fB-m\fR option for an alternative +"magic" file and the \fB-f\fR option for a support file that can contain a list +of file names. It is unspecified whether a utility that is large file aware +will accept configuration or support files that are large files. If a large +file aware utility does not accept configuration or support files that are +large files, it will cause no data loss or corruption upon encountering such +files and will return an appropriate error. +.LP +The following \fB/usr/bin\fR utilities are large file aware: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBadb\fR \fBaliasadm\fR \fBawk\fR \fBbdiff\fR \fBcat\fR +\fBchgrp\fR \fBchmod\fR \fBchown\fR \fBcksum\fR \fBcmp\fR +\fBcompress\fR \fBcp\fR \fBcsh\fR \fBcsplit\fR \fBcut\fR +\fBdd\fR \fBdircmp\fR \fBdu\fR \fBegrep\fR \fBfgrep\fR +\fBfile\fR \fBfind\fR \fBftp\fR \fBgetconf\fR \fBgrep\fR +\fBgzip\fR \fBhead\fR \fBjoin\fR \fBjsh\fR \fBksh\fR +\fBksh93\fR \fBln\fR \fBls\fR \fBmailcompat\fR \fBmailstats\fR +\fBmdb\fR \fBmkdir\fR \fBmkfifo\fR \fBmore\fR \fBmv\fR +\fBnawk\fR \fBpage\fR \fBpaste\fR \fBpathchck\fR \fBpg\fR +\fBpraliases\fR \fBrcp\fR \fBremsh\fR \fBrksh\fR \fBrksh93\fR +\fBrm\fR \fBrmdir\fR \fBrsh\fR \fBsed\fR \fBsh\fR +\fBsort\fR \fBsplit\fR \fBsum\fR \fBtail\fR \fBtar\fR +\fBtee\fR \fBtest\fR \fBtouch\fR \fBtr\fR \fBuncompress\fR +\fBuudecode\fR \fBuuencode\fR \fBvacation\fR \fBwc\fR \fBzcat\fR +.TE + +.LP +The following \fB/usr/xpg4/bin\fR utilities are large file aware: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBawk\fR \fBcp\fR \fBchgrp\fR \fBchown\fR \fBdu\fR +\fBegrep\fR \fBfgrep\fR \fBfile\fR \fBgrep\fR \fBln\fR +\fBls\fR \fBmore\fR \fBmv\fR \fBrm\fR \fBsed\fR +\fBsh\fR sort tail tr +.TE + +.LP +The following \fB/usr/xpg6/bin\fR utilities are large file aware: +.sp + +.sp +.TS +l l l l l . +\fBgetconf\fR \fBls\fR \fBtr\fR +.TE + +.LP +The following \fB/usr/sbin\fR utilities are large file aware: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBeditmap\fR \fBinstall\fR \fBmakemap\fR \fBmkfile\fR \fBmknod\fR +\fBmvdir\fR \fBswap\fR +.TE + +.LP +The following \fB/usr/lib\fR utilities are large file aware: +.sp + +.sp +.TS +l l l l l . +\fBmail.local\fR \fBsendmail\fR \fBsmrsh\fR +.TE + +.LP +See the USAGE section of the \fBswap\fR(8) manual page for limitations of +\fBswap\fR on block devices greater than 2 Gbyte on a 32-bit operating system. +.sp +.LP +The following \fB/usr/ucb\fR utilities are large file aware: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBchown\fR \fBfrom\fR \fBln\fR \fBls\fR \fBsed\fR +\fBsum\fR \fBtouch\fR +.TE + +.LP +The \fB/usr/bin/cpio\fR and \fB/usr/bin/pax\fR utilities are large file aware, +but cannot archive a file whose size exceeds 8 Gbyte - 1 byte. +.LP +The \fB/usr/bin/truss\fR utilities has been modified to read a dump file and +display information relevant to large files, such as offsets. +.SS "nfs file systems" +.LP +The following utilities are large file aware for \fBnfs\fR file systems: +.sp + +.sp +.TS +l l +l l . +\fB/usr/lib/autofs/automountd\fR \fB/usr/sbin/mount\fR +\fB/usr/lib/nfs/rquotad\fR +.TE + +.SS "ufs file systems" +.LP +The following \fB/usr/bin\fR utility is large file aware for \fBufs\fR file +systems: +.LP +\fBdf\fR +.LP +The following \fB/usr/lib/nfs\fR utility is large file aware for \fBufs\fR file +systems: +.LP +\fBrquotad\fR +.LP +The following \fB/usr/xpg4/bin\fR utility is large file aware for \fBufs\fR +file systems: +.LP +\fBdf\fR +.LP +The following \fB/usr/sbin\fR utilities are large file aware for \fBufs\fR file +systems: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBclri\fR \fBdcopy\fR \fBedquota\fR \fBff\fR \fBfsck\fR +\fBfsdb\fR \fBfsirand\fR \fBfstyp\fR \fBlabelit\fR \fBlockfs\fR +\fBmkfs\fR \fBmount\fR \fBncheck\fR \fBnewfs\fR \fBquot\fR +\fBquota\fR \fBquotacheck\fR \fBquotaoff\fR \fBquotaon\fR \fBrepquota\fR +\fBtunefs\fR \fBufsdump\fR \fBufsrestore\fR \fBumount\fR +.TE + +.SS "Large file safe utilities" +.LP +A utility is called \fBlarge file safe\fR if it causes no data loss or +corruption when it encounters a large file. A utility that is large file safe +is unable to process properly a large file, but returns an appropriate error. +.LP +The following \fB/usr/bin\fR utilities are large file safe: +.sp + +.sp +.TS +l l l l l +l l l l l . +\fBaudioconvert\fR \fBaudioplay\fR \fBaudiorecord\fR \fBcomm\fR \fBdiff\fR +\fBdiff3\fR \fBdiffmk\fR \fBed\fR \fBlp\fR \fBmail\fR +\fBmailcompat\fR \fBmailstats\fR \fBmailx\fR \fBpack\fR \fBpcat\fR +\fBred\fR \fBrmail\fR \fBsdiff\fR \fBunpack\fR \fBvi\fR +\fBview\fR +.TE + +.LP +The following \fB/usr/xpg4/bin\fR utilities are large file safe: +.sp + +.sp +.TS +l l l l l . +\fBed\fR \fBvi\fR \fBview\fR +.TE + +.LP +The following \fB/usr/xpg6/bin\fR utility is large file safe: +.sp + +.sp +.TS +l l l l l . +\fBed\fR +.TE + +.LP +The following \fB/usr/sbin\fR utilities are large file safe: +.sp + +.sp +.TS +l l l l l . +lpfilter lpforms +.TE + +.LP +The following \fB/usr/ucb\fR utilities are large file safe: +.sp + +.sp +.TS +l l l l l . +\fBMail\fR \fBlpr\fR +.TE + +.SH SEE ALSO +.LP +.BR lf64 (7), +.BR lfcompile (7), +.BR lfcompile64 (7) diff --git a/usr/src/man/man7/lf64.7 b/usr/src/man/man7/lf64.7 new file mode 100644 index 0000000000..ef611874df --- /dev/null +++ b/usr/src/man/man7/lf64.7 @@ -0,0 +1,348 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.\" Copyright (c) 2015, Joyent, Inc. All rights reserved. +.TH LF64 7 "May 17, 2020" +.SH NAME +lf64 \- transitional interfaces for 64-bit file offsets +.SH DESCRIPTION +The data types, interfaces, and macros described on this page provide explicit +access to 64-bit file offsets. They are accessible through the transitional +compilation environment described on the \fBlfcompile64\fR(7) manual page. The +function prototype and semantics of a transitional interface are equivalent to +those of the standard version of the call, except that relevant data types are +64-bit entities. +.SS "Data Types" +The following tables list the standard data or struct types in the left-hand +column and their corresponding explicit 64-bit file offset types in the +right-hand column, grouped by header. The absence of an entry in the left-hand +column indicates that there is no existing explicit 32-bit type that +corresponds to the 64-bit type listed in the right\(emhand column. Note that +in a 64-bit application, the standard definition is equivalent to the 64-bit +file offset definition. +.SS "<\fBaio.h\fR>" + +.TS +l l +l l . +struct \fBaiocb\fR struct \fBaiocb64\fR + \fBoff_t\fR aio_offset; \fBoff64_t\fR aio_offset; +.TE + +.SS "<\fBsys/dirent.h\fR>" + +.TS +l l +l l . +struct \fBdirent\fR struct \fBdirent64\fR + \fBino_t\fR d_ino; \fBino64_t\fR d_ino; + \fBoff_t\fR d_off; \fBoff64_t\fR d_off; +.TE + +.SS "<\fBsys/fcntl.h\fR>" + +.TS +l l +l l . +struct \fBflock\fR struct \fBflock64\fR + \fBoff_t\fR l_start; \fBoff64_t\fR l_start; + \fBoff_t\fR l_len; \fBoff64_t\fR l_len; +\fBF_SETLK\fR \fBF_SETLK64\fR +\fBF_SETLKW\fR \fBF_SETLKW64\fR +\fBF_GETLK\fR \fBF_GETLK64\fR +\fBF_FREESP\fR \fBF_FREESP64\fR +\fBF_ALLOCSP\fR \fBF_ALLOCSP64\fR + \fBO_LARGEFILE\fR +.TE + +.SS "<\fBsys/stdio.h\fR>" + +.TS +l l . +\fBfpos_t\fR \fBfpos64_t\fR +.TE + +.SS "<\fBsys/resource.h\fR>" + +.TS +l l +l l . +\fBrlim_t\fR \fBrlim64_t\fR +struct \fBrlimit\fR struct \fBrlimit64\fR + \fBrlim_t\fR rlim_cur; \fBrlim64_t\fR rlim_cur; + \fBrlim_t\fR rlim_max; \fBrlim64_t\fR rlim_max; +\fBRLIM_INFINITY\fR \fBRLIM64_INFINITY\fR +\fBRLIM_SAVED_MAX\fR \fBRLIM64_SAVED_MAX\fR +\fBRLIM_SAVED_CUR\fR \fBRLIM64_SAVED_CUR\fR +.TE + +.SS "<\fBsys/stat.h\fR>" + +.TS +l l +l l . +struct \fBstat\fR struct \fBstat64\fR + \fBino_t\fR st_ino; \fBino64_t\fR st_ino; + \fBoff_t\fR st_size; \fBoff64_t\fR st_size; + \fBblkcnt_t\fR st_blocks; \fBblkcnt64_t\fR st_blocks; +.TE + +.SS "<\fBsys/statvfs.h\fR>" + +.TS +l l +l l . +struct \fBstatvfs\fR struct \fBstatvfs64\fR + \fBfsblkcnt_t\fR f_blocks; \fBfsblkcnt64_t\fR f_blocks; + \fBfsblkcnt_t\fR f_bfree; \fBfsblkcnt64_t\fR f_bfree; + \fBfsblkcnt_t\fR f_bavail; \fBfsblkcnt64_t\fR f_bavail; + \fBfsfilcnt_t\fR f_files; \fBfsfilcnt64_t\fR f_files; + \fBfsfilcnt_t\fR f_ffree; \fBfsfilcnt64_t\fR f_ffree; + \fBfsfilcnt_t\fR f_favail; \fBfsfilcnt64_t\fR f_favail; +.TE + +.SS "<\fBsys/types.h\fR>" + +.TS +l l +l l . +\fBoff_t\fR; \fBoff64_t\fR; +\fBino_t\fR; \fBino64_t\fR; +\fBblkcnt_t\fR; \fBblkcnt64_t\fR; +\fBfsblkcnt_t\fR; \fBfsblkcnt64_t\fR; +\fBfsfilcnt_t\fR; \fBfsfilcnt64_t\fR; +.TE + +.SS "<\fBunistd.h\fR>" + +.TS +l l +l l . + \fB_LFS64_LARGEFILE\fR + \fB_LFS64_STDIO\fR +.TE + +.SS "<\fBsys/unistd.h\fR>" + +.TS +l l +l l . + \fB_CS_LFS64_CFLAGS\fR + \fB_CS_LFS64_LDFLAGS\fR + \fB_CS_LFS64_LIBS\fR + \fB_CS_LFS64_LINTFLAGS\fR +.TE + +.SS "System Interfaces" +The following tables display the standard API and the corresponding +transitional interfaces for 64-bit file offsets. The interfaces are grouped by +header. The interface name and the affected data types are displayed in courier +font. +.SS "<\fBaio.h\fR>" + +.TS +l l +l l . +int \fBaio_cancel\fR(..., int \fBaio_cancel64\fR(..., + struct \fBaiocb\fR *); struct \fBaiocb64\fR *); +int \fBaio_error\fR( int \fBaio_error64\fR( + const struct \fBaiocb\fR *); const struct \fBaiocb64\fR *); +int \fBaio_fsync\fR(..., int \fBaio_fsync64\fR(..., + struct \fBaiocb\fR *); struct \fBaiocb64\fR *); +int \fBaio_read\fR(struct \fBaiocb\fR *); int \fBaio_read64\fR(struct \fBaiocb64\fR *); +int \fBaio_return\fR(struct \fBaiocb\fR *); int \fBaio_return64\fR(struct \fBaiocb64\fR *); +int \fBaio_suspend\fR( int \fBaio_suspend64\fR( + const struct \fBaiocb\fR *, ...); const struct \fBaiocb64\fR *, ...); +int \fBaio_waitn\fR(aiocb_t *[], int \fBaio_waitn64\fR(aiocb64_t *[], + ...); ...); +int \fBaio_write\fR(struct \fBaiocb\fR *); int \fBaio_write64\fR(struct \fBaiocb64\fR *); +int \fBlio_listio\fR(..., int \fBlio_listio64\fR(..., + const struct \fBaiocb\fR *, ...); const struct \fBaiocb64\fR *, ...); +.TE + +.SS "<\fBdirent.h\fR>" + +.TS +l l +l l . +int \fBalphasort\fR( int \fBalphasort64\fR( + const struct dirent **, const struct dirent64 **, + const struct dirent **) const struct dirent64 **) +struct \fBdirent *\fR\fBreaddir()\fR; struct \fBdirent64 *\fR\fBreaddir64()\fR; +struct \fBdirent *\fR\fBreaddir_r()\fR; struct \fBdirent64 *\fR\fBreaddir64_r()\fR; +int \fBscandir\fR(..., int \fBscandir64\fR(..., + struct dirent *(*[]), struct dirent64 *(*[]), + int (*)(const struct dirent *), int (*)(const struct dirent64 *), + int (*)(const struct dirent **, int (*)(const struct dirent64 **, + const struct dirent **)) const struct dirent64 **)) +.TE + +.SS "<\fBfcntl.h\fR>" + +.TS +l l +l l . +int \fBattropen()\fR; int \fBattropen64()\fR; +int \fBcreat()\fR; int \fBcreat64()\fR; +int \fBopen()\fR; int \fBopen64()\fR; +int \fBopenat()\fR; int \fBopenat64()\fR; +int \fBposix_fadvise()\fR int \fBposix_fadvise64()\fR +int \fBposix_fallocate()\fR int \fBposix_fallocate64()\fR +.TE + +.SS "<\fBftw.h\fR>" + +.TS +l l +l l . +int \fBftw\fR(..., int \fBftw64\fR(..., + const struct \fBstat\fR *, ...); const struct \fBstat64\fR *, ...); + +int \fBnftw\fR(.. int \fBnftw64\fR(..., + const struct \fBstat\fR *, ...); const struct \fBstat64\fR *, ...); + +.TE + +.SS "<\fBlibgen.h\fR>" + +.TS +l l . +char *\fBcopylist\fR(..., \fBoff_t\fR); char *\fBcopylist64\fR(..., \fBoff64_t\fR); +.TE + +.SS "<\fBstdio.h\fR>" + +.TS +l l +l l . +int \fBfgetpos()\fR; int \fBfgetpos64()\fR; +FILE *\fBfopen()\fR; FILE *\fBfopen64()\fR; +FILE *\fBfreopen()\fR; FILE *\fBfreopen64()\fR; +int \fBfseeko\fR(..., \fBoff_t\fR, ...); int \fBfseeko64\fR(..., \fBoff64_t\fR, ...); +int \fBfsetpos\fR(..., int \fBfsetpos64\fR(..., + const \fBfpos_t\fR *); const \fBfpos64_t\fR *); +off_t \fBftello()\fR; off64_t \fBftello64()\fR(); +FILE *\fBtmpfile()\fR; FILE *\fBtmpfile64()\fR; +.TE + +.SS "<\fBstdlib.h\fR>" + +.TS +l l . +int \fBmkstemp()\fR; int \fBmkstemp64()\fR; +.TE + +.SS "<\fBsys/async.h\fR>" + +.TS +l l +l l . +int \fBaioread\fR(..., \fBoff_t\fR, ...); int \fBaioread64\fR(..., \fBoff64_t\fR, ...); +int \fBaiowrite\fR(..., \fBoff_t\fR, ...); int \fBaiowrite64\fR(..., \fBoff64_t\fR, ...); +.TE + +.SS "<\fBsys/dirent.h\fR>" + +.TS +l l +l l . +int \fBgetdents\fR(..., \fBdirent\fR); int \fBgetdents64\fR(..., \fBdirent64\fR); + +.TE + +.SS "<\fBsys/mman.h\fR>" + +.TS +l l . +void \fBmmap\fR(..., \fBoff_t\fR); void \fBmmap64\fR(..., \fBoff64_t\fR); +.TE + +.SS "<\fBsys/resource.h\fR>" + +.TS +l l +l l . +int \fBgetrlimit\fR(..., int \fBgetrlimit64\fR(..., + struct \fBrlimit\fR *); struct \fBrlimit64\fR *); +int \fBsetrlimit\fR(..., int \fBsetrlimit64\fR(..., + const struct \fBrlimit\fR *); const struct \fBrlimit64\fR *); +.TE + +.SS "<\fBsys/sendfile.h\fR>" + +.TS +l l +l l . +ssize_t \fBsendfile\fR(..., ssize_t \fBsendfile64\fR(..., + \fBoff_t\fR *, ...); \fBoff64_t\fR *, ...); +ssize_t \fBsendfilev\fR(..., const ssize_t \fBsendfilev64\fR(..., const + struct \fBsendfilevec\fR *, ...); struct \fBsendfilevec64\fR *, ...); + +.TE + +.SS "<\fBsys/stat.h\fR>" + +.TS +l l +l l . +int \fBfstat\fR(..., struct \fBstat\fR *); int \fBfstat64\fR(..., struct \fBstat64\fR *); +int \fBfstatat\fR(..., int \fBfstatat64\fR(..., + struct \fBstat\fR *, int); struct \fBstat64\fR *, int); +int \fBlstat\fR(..., struct \fBstat\fR *); int \fBlstat64\fR(..., struct \fBstat64\fR *); +int \fBstat\fR(..., struct \fBstat\fR *); int \fBstat64\fR(..., struct \fBstat64\fR *); +.TE + +.SS "<\fBsys/statvfs.h\fR>" + +.TS +l l +l l . +int \fBstatvfs\fR(..., int \fBstatvfs64\fR(..., + struct \fBstatvfs\fR *); struct \fBstatvfs64\fR *); +int \fBfstatvfs\fR(..., int \fBfstatvfs64\fR(..., + struct \fBstatvfs\fR *); struct \fBstatvfs64\fR *); +.TE + +.SS "<\fBucbinclude/stdio.h\fR>" + +.TS +l l +l l . +FILE *\fBfopen()\fR FILE *\fBfopen64()\fR +FILE *\fBfreopen()\fR FILE *\fBfreopen64()\fR +.TE + +.SS "<\fBucbinclude/sys/dir.h\fR>" + +.TS +l l +l l . +int \fBalphasort\fR( int \fBalphasort64\fR( + struct \fBdirect\fR **, struct \fBdirect64\fR **, + struct \fBdirect\fR **); struct \fBdirect64\fR **); +struct \fBdirect *\fR\fBreaddir()\fR; struct \fBdirect64 *\fR\fBreaddir64()\fR; +int \fBscandir\fR(..., int \fBscandir64\fR(..., + struct \fBdirect\fR *(*[]);, ...); struct \fBdirect64\fR *(*[]);, ...); + +.TE + +.SS "<\fBunistd.h\fR>" + +.TS +l l +l l . +int \fBlockf\fR(..., \fBoff_t\fR); int \fBlockf64\fR(..., \fBoff64_t\fR); +\fBoff_t lseek\fR(..., \fBoff_t\fR, ...); \fBoff64_t lseek64\fR(..., \fBoff64_t\fR, ...); +int \fBftruncate\fR(..., \fBoff_t\fR); int \fBftruncate64\fR..., \fBoff64_t\fR); +ssize_t \fBpread\fR(..., \fBoff_t\fR); ssize_t \fBpread64\fR..., \fBoff64_t\fR); +ssize_t \fBpwrite\fR(..., \fBoff_t\fR); ssize_t \fBpwrite64\fR(..., \fBoff64_t\fR); +ssize_t \fBpreadv\fR(..., \fBoff_t\fR); ssize_t \fBpreadv64\fR..., \fBoff64_t\fR); +ssize_t \fBpwritev\fR(..., \fBoff_t\fR); ssize_t \fBpwritev64\fR(..., \fBoff64_t\fR); +int \fBtruncate\fR(..., \fBoff_t\fR); int \fBtruncate64\fR(..., \fBoff64_t\fR); +.TE + +.SH SEE ALSO +.BR lfcompile (7), +.BR lfcompile64 (7) diff --git a/usr/src/man/man7/lfcompile.7 b/usr/src/man/man7/lfcompile.7 new file mode 100644 index 0000000000..da5408179a --- /dev/null +++ b/usr/src/man/man7/lfcompile.7 @@ -0,0 +1,223 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH LFCOMPILE 7 "Aug 24, 2009" +.SH NAME +lfcompile \- large file compilation environment for 32-bit applications +.SH DESCRIPTION +.sp +.LP +All 64-bit applications can manipulate large files by default. The methods +described on this page allow 32-bit applications to manipulate large files. +.sp +.LP +In the large file compilation environment, source interfaces are bound to +appropriate 64-bit functions, structures, and types. Compiling in this +environment allows 32-bit applications to access files whose size is greater +than or equal to 2 Gbyte ( 2^31 bytes). +.sp +.LP +Each interface named \fIxxx\fR\fB()\fR that needs to access 64-bit entities to +access large files maps to a \fIxxx\fR\fB64()\fR call in the resulting binary. +All relevant data types are defined to be of correct size (for example, +\fBoff_t\fR has a typedef definition for a 64-bit entity). +.sp +.LP +An application compiled in this environment is able to use the +\fIxxx\fR\fB()\fR source interfaces to access both large and small files, +rather than having to explicitly utilize the transitional \fIxxx\fR\fB64()\fR +interface calls to access large files. See the \fBlfcompile64\fR(7) manual page +for information regarding the transitional compilation environment. +.sp +.LP +Applications can be compiled in the large file compilation environment by using +the following methods: +.RS +4 +.TP +.ie t \(bu +.el o +Use the \fBgetconf\fR(1) utility with one or more of the arguments listed in +the table below. This method is recommended for portable applications. +.sp + +.sp +.TS +box; +c | c +l | l . +\fBargument\fR \fBpurpose\fR +_ +\fBLFS_CFLAGS\fR T{ +obtain compilation flags necessary to enable the large file compilation environment +T} +\fBLFS_LDFLAGS\fR obtain link editor options +\fBLFS_LIBS\fR obtain link library names +\fBLFS_LINTFLAGS\fR obtain lint options +.TE + +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Set the compile-time flag \fB_FILE_OFFSET_BITS\fR to 64 before including any +headers. Applications may combine objects produced in the large file +compilation environment with objects produced in the transitional compilation +environment, but must be careful with respect to interoperability between those +objects. Applications should not declare global variables of types whose sizes +change between compilation environments. +.RE +.SS "Access to Additional Large File Interfaces" +.sp +.LP +The \fBfseek()\fR and \fBftell()\fR functions \fIdo not\fR map to functions +named \fBfseek64()\fR and \fBftell64()\fR; rather, the large file additions +\fBfseeko()\fR and \fBftello()\fR, have functionality identical to +\fBfseek()\fR and \fBftell()\fR and \fIdo\fR map to the 64-bit functions +\fBfseeko64()\fR and \fBftello64()\fR. Applications wishing to access large +files should use \fBfseeko()\fR and \fBftello()\fR in place of \fBfseek()\fR +and \fBftell()\fR. See the \fBfseek\fR(3C) and \fBftell\fR(3C) manual pages for +information about \fBfseeko()\fR and \fBftello()\fR. +.sp +.LP +Applications wishing to access \fBfseeko()\fR and \fBftello()\fR as well as +the POSIX and X/Open specification-conforming interfaces should define the +macro \fB_LARGEFILE_SOURCE\fR to be 1 and set whichever feature test macros are +appropriate to obtain the desired environment (see \fBstandards\fR(7)). +.SH EXAMPLES +.sp +.LP +In the following examples, the large file compilation environment is accessed +by invoking the \fBgetconf\fR utility with one of the arguments listed in the +table above. The additional large file interfaces are accessed by specifying +\fB-D_LARGEFILE_SOURCE\fR\&. +.sp +.LP +The examples that use the form of command substitution specifying the command +within parentheses preceded by a dollar sign can be executed only in a +POSIX-conforming shell such as the Korn Shell (see \fBksh\fR(1)). In a shell +that is not POSIX-conforming, such as the Bourne Shell (see \fBsh\fR(1)) and +the C Shell (see \fBcsh\fR(1)), the \fBgetconf\fR calls must be enclosed within +grave accent marks, as shown in the second example. +.LP +\fBExample 1 \fRCompile a program with a "large" \fBoff_t\fR that uses +\fBfseeko()\fR, \fBftello()\fR, and \fByacc\fR. +.sp +.LP +The following example compiles a program with a "large" \fBoff_t\fR and uses +\fBfseeko()\fR, \fBftello()\fR, and \fByacc\fR(1). + +.sp +.in +2 +.nf +$ c89 -D_LARGEFILE_SOURCE \e + -D_FILE_OFFSET_BITS=64 -o foo \e + $(getconf LFS_CFLAGS) y.tab.c b.o \e + $(getconf LFS_LDFLAGS) \e + -ly $(getconf LFS_LIBS) +.fi +.in -2 + +.LP +\fBExample 2 \fRCompile a program with a "large" \fBoff_t\fR that does not use +\fBfseeko()\fR and \fBftello()\fR and has no application specific libraries. +.sp +.in +2 +.nf +% c89 -D_FILE_OFFSET_BITS=64 \e + \(gagetconf LFS_CFLAGS\(ga a.c \e + \(gagetconf LFS_LDFLAGS\(ga \e + \(gagetconf LFS_LIBS\(ga \e +.fi +.in -2 + +.LP +\fBExample 3 \fRCompile a program with a "default" \fBoff_t\fR that uses +\fBfseeko()\fR and \fBftello()\fR. +.sp +.in +2 +.nf +$ c89 -D_LARGEFILE_SOURCE a.c +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +.BR csh (1), +.BR getconf (1), +.BR ksh (1), +.BR sh (1), +.BR yacc (1), +.BR fseek (3C), +.BR ftell (3C), +.BR lf64 (7), +.BR lfcompile64 (7), +.BR standards (7) +.SH NOTES +.sp +.LP +Certain system-specific or non-portable interfaces are not usable in the large +file compilation environment. Known cases are: +.RS +4 +.TP +.ie t \(bu +.el o +Kernel data structures read from \fB/dev/kmem\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Interfaces in the kernel virtual memory library, \fB-lkvm\fR\&. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Interfaces in the \fBELF\fR access library, \fB-lelf\fR\&. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Interfaces to \fB/proc\fR defined in <\fBprocfs.h\fR>. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBustat\fR(2) system call. +.RE +.sp +.LP +Programs that use these interfaces should not be compiled in the large file +compilation environment. As a partial safeguard against making this mistake, +including either of the <\fBlibelf.h\fR> or <\fBsys/procfs.h\fR> header files +will induce a compilation error when the large file compilation environment is +enabled. +.sp +.LP +In general, caution should be exercised when using any separately-compiled +library whose interfaces include data items of type \fBoff_t\fR or the other +redefined types either directly or indirectly, such as with '\fBstruct +stat\fR'. (The redefined types are \fBoff_t\fR, \fBrlim_t\fR, \fBino_t\fR, +\fBblkcnt_t\fR, \fBfsblkcnt_t\fR, and \fBfsfilcnt_t\fR.) For the large file +compilation environment to work correctly with such a library, the library +interfaces must include the appropriate \fIxxx\fR\fB64()\fR binary entry points +and must have them mapped to the corresponding primary functions when +\fB_FILE_OFFSET_BITS\fR is set to 64. +.sp +.LP +Care should be exercised using any of the \fBprintf()\fR or \fBscanf()\fR +routines on variables of the types mentioned above. In the large file +compilation environment, these variables should be printed or scanned using +\fBlong long\fR formats. +.SH BUGS +.sp +.LP +Symbolic formats analogous to those found in \fB<sys/int_fmtio.h>\fR do not +exist for printing or scanning variables of the types that are redefined in the +large file compilation environment. diff --git a/usr/src/man/man7/lfcompile64.7 b/usr/src/man/man7/lfcompile64.7 new file mode 100644 index 0000000000..440e331f06 --- /dev/null +++ b/usr/src/man/man7/lfcompile64.7 @@ -0,0 +1,137 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH LFCOMPILE64 7 "Jan 26, 1998" +.SH NAME +lfcompile64 \- transitional compilation environment +.SH DESCRIPTION +.sp +.LP +All 64-bit applications can manipulate large files by default. The transitional +interfaces described on this page can be used by 32-bit and 64-bit applications +to manipulate large files. +.sp +.LP +In the transitional compilation environment, explicit 64-bit functions, +structures, and types are added to the \fBAPI.\fR Compiling in this +environment allows both 32-bit and 64-bit applications to access files whose +size is greater than or equal to 2 Gbyte ( 2^31 bytes). +.sp +.LP +The transitional compilation environment exports all the explicit 64-bit +functions (\fIxxx\fR\fB64()\fR) and types in addition to all the regular +functions (\fIxxx\fR\fB()\fR) and types. Both \fIxxx\fR\fB()\fR and +\fIxxx\fR\fB64()\fR functions are available to the program source. A 32-bit +application must use the \fIxxx\fR\fB64()\fR functions in order to access large +files. See the \fBlf64\fR(7) manual page for a complete listing of the 64-bit +transitional interfaces. +.sp +.LP +The transitional compilation environment differs from the large file +compilation environment, wherein the underlying interfaces are bound to 64-bit +functions, structures, and types. An application compiled in the large file +compilation environment is able to use the \fIxxx\fR\fB()\fR source interfaces +to access both large and small files, rather than having to explicitly utilize +the transitional \fIxxx\fR\fB64()\fR interface calls to access large files. See +the \fBlfcompile\fR(7) manual page for more information regarding the large +file compilation environment. +.sp +.LP +Applications may combine objects produced in the large file compilation +environment with objects produced in the transitional compilation environment, +but must be careful with respect to interoperability between those objects. +Applications should not declare global variables of types whose sizes change +between compilation environments. +.sp +.LP +For applications that do not wish to conform to the POSIX or X/Open +specifications, the 64-bit transitional interfaces are available by default. +No compile-time flags need to be set. +.SS "Access to Additional Large File Interfaces" +.sp +.LP +Applications that wish to access the transitional interfaces as well as the +POSIX or X/Open specification-conforming interfaces should use the following +compilation methods and set whichever feature test macros are appropriate to +obtain the desired environment (see \fBstandards\fR(7)). +.RS +4 +.TP +.ie t \(bu +.el o +Set the compile-time flag \fB_LARGEFILE64_SOURCE\fR to 1 before including any +headers. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Use the \fBgetconf\fR(1) command with one or more of the following arguments: +.RE +.sp + +.sp +.TS +box; +c | c +l | l . +\fBargument\fR \fBpurpose\fR +_ +\fBLFS64_CFLAGS\fR T{ +obtain compilation flags necessary to enable the transitional compilation environment +T} +\fBLFS64_LDFLAGS\fR obtain link editor options +\fBLFS64_LIBS\fR obtain link library names +\fBLFS64_LINTFLAGS\fR obtain lint options +.TE + +.SH EXAMPLES +.sp +.LP +In the following examples, the transitional compilation environment is accessed +by invoking the \fBgetconf\fR utility with one of the arguments listed in the +table above. The additional large file interfaces are accessed either by +specifying \fB-D_LARGEFILE64_SOURCE\fR or by invoking the \fBgetconf\fR utility +with the arguments listed above. +.sp +.LP +The example that uses the form of command substitution specifying the command +within parentheses preceded by a dollar sign can be executed only in a +POSIX-conforming shell such as the Korn Shell (see \fBksh\fR(1)). In a shell +that is not POSIX-conforming, such as the Bourne Shell (see \fBsh\fR(1)) and +the C Shell (see \fBcsh\fR(1)), the command must be enclosed within grave +accent marks. +.LP +\fBExample 1 \fRAn example of compiling a program using transitional +interfaces such as \fBlseek64()\fR and \fBfopen64()\fR: +.sp +.in +2 +.nf +$ c89 -D_LARGEFILE64_SOURCE \e + $(getconf LFS64_CFLAGS) a.c \e + $(getconf LFS64_LDFLAGS) \e + $(getconf LFS64_LIBS) +.fi +.in -2 + +.LP +\fBExample 2 \fRAn example of running lint on a program using transitional +interfaces: +.sp +.in +2 +.nf +% lint -D_LARGEFILE64_SOURCE \e + \(gagetconf LFS64_LINTFLAGS\(ga \&.\|.\|. \e + \(gagetconf LFS64_LIBS\(ga +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +.BR getconf (1), +.BR lseek (2), +.BR fopen (3C), +.BR lf64 (7), +.BR standards (7) diff --git a/usr/src/man/man7/loader.4th.7 b/usr/src/man/man7/loader.4th.7 new file mode 100644 index 0000000000..3830d1de62 --- /dev/null +++ b/usr/src/man/man7/loader.4th.7 @@ -0,0 +1,206 @@ +.\" Copyright (c) 1999 Daniel C. Sobral +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd Apr 22, 2017 +.Dt LOADER.4TH 7 +.Os +.Sh NAME +.Nm loader.4th +.Nd loader.conf processing tools +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to manipulate +.Xr loader.conf 5 +files. +The default +.Pa /boot/loader.rc +includes +.Nm +and uses one of its commands to automatically read and process +the standard +.Xr loader.conf 5 +files. +Other commands exists to help the user specify alternate +configurations. +.Pp +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include loader.4th +.Pp +This line is present in the default +.Pa /boot/loader.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic boot +.It Ic boot Ar kernelname Op Cm ... +.It Ic boot Ar directory Op Cm ... +.It Ic boot Fl flag Cm ... +Boot as specified by the +.Xr loader.conf 5 +files read. +.Pp +Depending on the arguments passed, it can override boot flags and +either the kernel name or the search path for kernel and modules. +.Pp +.It Ic boot-conf +.It Ic boot-conf Ar kernelname Op Cm ... +.It Ic boot-conf Ar directory Op Cm ... +.It Ic boot-conf Fl flag Cm ... +Works like +.Ic boot +described above, but instead of booting immediately, uses +.Ic autoboot , +so it can be stopped. +.Pp +.It Ic start +Reads +.Pa /boot/defaults/loader.conf , +all other +.Xr loader.conf 5 +files specified in it, then loads the desired kernel and modules +.Pq if not already loaded . +After which you can use the +.Ic boot +or +.Ic autoboot +commands or simply exit (provided +.Va autoboot_delay +is not set to NO) to boot the system. +.Ic start +is the command used in the default +.Pa /boot/loader.rc +file +.Pq see Xr loader 7 . +.Pp +.It Ic initialize +Initialize the support library so commands can be used without executing +.Ic start +first. +Like +.Ic start , +it reads +.Pa /boot/defaults/loader.conf +and all other +.Xr loader.conf 5 +files specified in it +.Pq but does not load kernel or modules . +Returns a flag on the stack to indicate +if any configuration files were successfully loaded. +.Pp +.It Ic read-conf Ar filename +Reads and processes a +.Xr loader.conf 5 +file. +Does not proceed to boot. +.Pp +.It Ic enable-module Ar module +Enables the loading of +.Ar module . +.Pp +.It Ic disable-module Ar module +Disables the loading of +.Ar module . +.Pp +.It Ic toggle-module Ar module +Toggles the loading of +.Ar module +on and off. +.Pp +.It Ic show-module Ar module +Shows the information gathered in the +.Xr loader.conf 5 +files about the module +.Ar module . +.Pp +.It Ic show-module-options +Shows all modules defined in current +.Xr loader.conf 5 +configuration. +.Pp +.It Ic retry +Used inside +.Xr loader.conf 5 +files to specify the action after a module loading fails. +.Pp +.It Ic ignore +Used inside +.Xr loader.conf 5 +files to specify the action after a module loading fails. +.It Ic try-include Ar file Op Ar +Process script files if they exist. +Each file, in turn, is completely read into memory, +and then each of its lines is passed to the command line interpreter. +If any error is returned by the interpreter, the try-include +command aborts immediately, without reading any other files, and +silently returns without error. +.El +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/loader.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.It Pa /boot/defaults/loader.conf +File loaded by the +.Ic start +command. +.El +.Sh EXAMPLES +Standard +.Pa /boot/loader.rc : +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/loader.4th +start +.Ed +.Pp +Read an additional configuration file and then proceed to boot: +.Pp +.Bd -literal -offset indent -compact +unload +read-conf /boot/special.conf +boot-conf +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr loader 7 diff --git a/usr/src/man/man7/loader.7 b/usr/src/man/man7/loader.7 new file mode 100644 index 0000000000..c3ab1d35b3 --- /dev/null +++ b/usr/src/man/man7/loader.7 @@ -0,0 +1,909 @@ +.\" Copyright (c) 1999 Daniel C. Sobral +.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 25, 2022 +.Dt LOADER 7 +.Os +.Sh NAME +.Nm loader +.Nd kernel bootstrapping final stage +.Sh DESCRIPTION +The +.Nm +is the final stage of +.Nm illumos Ns 's +kernel bootstrapping process. +The actual name for the stage depends on the platform. +On IA32 (i386) architectures with BIOS firmware, it is a +.Pa BTX +client and named +.Nm loader . +It is linked statically to libstand and usually located in the directory +.Pa /boot . +.Pp +.Nm +supports booting from +.Cm ZFS , +.Cm UFS , +.Cm PCFS , +.Cm HSFS +and +.Cm NFS +file systems. +Additionally, +.Nm +can load files from the +.Cm TFTP +file service. +The NFS and TFTP based boot is enabled via +.Xr pxeboot 7 . +The +.Nm +also does support uncompressing gzip files while reading. +The uncompression will happen automatically if the compressed file is stored +without .gz suffix or if the file is accessed by leaving out the .gz suffix from +the name. +If the file is referred by full name, including .gz suffix, then the file +content is read as is and the uncompression is not performed. +.Pp +.Nm +provides a scripting language that can be used to +automate tasks, do pre-configuration or assist in recovery +procedures. +This scripting language is roughly divided in +two main components. +The smaller one is a set of commands +designed for direct use by the casual user, called "builtin +commands" for historical reasons. +The main drive behind these commands is user-friendliness. +The bigger component is an +.Tn ANS +Forth compatible Forth interpreter based on FICL, by +.An John Sadler . +.Pp +During initialization, +.Nm +will probe for a console and set the +.Va console +variable, or set it to serial console +.Pq Do Li ttya Dc - Dq Li ttyd +if the previous boot stage used that. +If multiple consoles are selected, they will be listed separated by commas. +Then, devices are probed, +.Va currdev +and +.Va loaddev +are set, and +.Va screen-#cols , +.Va screen-#rows , +and +.Va ISADIR +are set. +Next, +.Tn FICL +is initialized, the builtin words are added to its vocabulary. +The inner interpreter +.Nm +will use with +.Tn FICL +is then set to +.Ic interpret , +which is +.Tn FICL Ns 's +default. +After that, +.Pa /boot/loader.rc +is processed if available. +These files are processed through the +.Ic include +command, which reads all of them into memory before processing them, +making disk changes possible. +.Pp +At this point, if an +.Ic autoboot +has not been tried, and if +.Va autoboot_delay +is not set to +.Dq Li NO +(not case sensitive), then an +.Ic autoboot +will be tried. +If the system gets past this point, +.Va prompt +will be set and +.Nm +will engage interactive mode. +Please note that historically even when +.Va autoboot_delay +is set to +.Dq Li 0 +user will be able to interrupt autoboot process by pressing some key +on the console while kernel and modules are being loaded. +In some +cases such behaviour may be undesirable, to prevent it set +.Va autoboot_delay +to +.Dq Li -1 , +in this case +.Nm +will engage interactive mode only if +.Ic autoboot +has failed. +.Ss Builtin Commands +In +.Nm , +builtin commands take parameters from the command line. +If an error condition occurs, an exception will be generated, +which can be intercepted using +.Tn ANS +Forth exception handling +words. +If not intercepted, an error message will be displayed and +the interpreter's state will be reset, emptying the stack and restoring +interpreting mode. +.Pp +The builtin commands available are: +.Pp +.Bl -tag -width Ds -compact +.It Ic autoboot Op Ar seconds Op Ar prompt +Proceeds to bootstrap the system after a number of seconds, if not +interrupted by the user. +Displays a countdown prompt +warning the user the system is about to be booted, +unless interrupted by a key press. +The kernel will be loaded first if necessary. +Defaults to 10 seconds. +.Pp +.It Ic bcachestat +Displays statistics about disk cache usage. +For debugging only. +.Pp +.It Ic boot +.It Ic boot Ar kernelname Op Cm ... +.It Ic boot Fl flag Cm ... +Immediately proceeds to bootstrap the system, loading the kernel +if necessary. +Any flags or arguments are passed to the kernel, but they +must precede the kernel name, if a kernel name is provided. +.Pp +.Em WARNING : +The behavior of this builtin is changed if +.Xr loader.4th 7 +is loaded. +.Pp +.It Ic chain Ar device +Chain load another boot loader from the specified device. +Device can be either disk name or partition. +.Pp +.It Ic echo Xo +.Op Fl n +.Op Aq message +.Xc +Displays text on the screen. +A new line will be printed unless +.Fl n +is specified. +.Pp +.It Ic heap +Displays memory usage statistics. +For debugging purposes only. +.Pp +.It Ic help Op topic Op subtopic +Shows help messages read from +.Pa /boot/loader.help . +The special topic +.Em index +will list the topics available. +.Pp +.It Ic include Ar file Op Ar +Process script files. +Each file, in turn, is completely read into memory, +and then each of its lines is passed to the command line interpreter. +If any error is returned by the interpreter, the include +command aborts immediately, without reading any other files, and +returns an error itself (see +.Sx ERRORS ) . +.Pp +.It Ic load Xo +.Op Fl t Ar type +.Ar file Cm ... +.Xc +Loads a kernel or file of opaque contents tagged as being of the type +.Ar type . +Kernel and modules can be either in a.out or ELF format. +Any arguments passed after the name of the file to be loaded +will be passed as arguments to that file. +.Pp +.It Ic ls Xo +.Op Fl l +.Op Ar path +.Xc +Displays a listing of files in the directory +.Ar path , +or the root directory if +.Ar path +is not specified. +If +.Fl l +is specified, file sizes will be shown too. +.Pp +.It Ic lsdev Op Fl v +Lists all of the devices from which it may be possible to load modules. +In addition to disks and partitions, ZFS pools are also listed. +If +.Fl v +is specified, more details are printed. +For ZFS pools the output resembles +.Nm zpool Cm status +output. +.Pp +.It Ic lsmod Op Fl v +Displays loaded modules. +If +.Fl v +is specified, more details are shown. +.Pp +.It Ic lszfs Ar filesystem +A ZFS extended command that can be used to explore the ZFS filesystem +hierarchy in a pool. +Lists the immediate children of the +.Ar filesystem . +The filesystem hierarchy is rooted at a filesystem with the same name +as the pool. +.Pp +.It Ic more Ar file Op Ar +Display the files specified, with a pause at each +.Va screen-#rows +displayed. +.Pp +.It Ic read Xo +.Op Fl t Ar seconds +.Op Fl p Ar prompt +.Op Va variable +.Xc +Reads a line of input from the terminal, storing it in +.Va variable +if specified. +A timeout can be specified with +.Fl t , +though it will be canceled at the first key pressed. +A prompt may also be displayed through the +.Fl p +flag. +.Pp +.It Ic reboot +Immediately reboots the system. +.Pp +.It Ic set Ar variable +.It Ic set Ar variable Ns = Ns Ar value +Set loader's environment variables. +.Pp +.It Ic show Op Va variable +Displays the specified variable's value, or all variables and their +values if +.Va variable +is not specified. +.Pp +.It Ic unload +Remove all modules from memory. +.Pp +.It Ic unset Va variable +Removes +.Va variable +from the environment. +.Pp +.It Ic \&? +Lists available commands. +.El +.Ss ZFS Features +.Nm +supports the following format for specifying ZFS filesystems which +can be used wherever +.Nm +refers to a device specification: +.Pp +.Ar zfs:pool/filesystem: +.Pp +where +.Pa pool/filesystem +is a ZFS filesystem name as described in +.Xr zfs 8 . +.Ss Builtin Environment Variables +The +.Nm +has actually two different kinds of +.Sq environment +variables. +There are ANS Forth's +.Em environmental queries , +and a separate space of environment variables used by builtins, which +are not directly available to Forth words. +It is the latter type that this section covers. +.Pp +Environment variables can be set and unset through the +.Ic set +and +.Ic unset +builtins, and can have their values interactively examined through the +use of the +.Ic show +builtin. +Their values can also be accessed as described in +.Sx BUILTIN PARSER . +.Pp +Notice that these environment variables are not inherited by any shell +after the system has been booted. +.Pp +A few variables are set automatically by +.Nm . +Others can affect the behavior of either +.Nm +or the kernel at boot. +Some options may require a value, +while others define behavior just by being set. +Both types of builtin variables are described below. +.Bl -tag -width bootfile +.It Va autoboot_delay +Number of seconds +.Ic autoboot +will wait before booting. +If this variable is not defined, +.Ic autoboot +will default to 10 seconds. +.Pp +If set to +.Dq Li NO , +no +.Ic autoboot +will be automatically attempted after processing +.Pa /boot/loader.rc , +though explicit +.Ic autoboot Ns 's +will be processed normally, defaulting to 10 seconds delay. +.Pp +If set to +.Dq Li 0 , +no delay will be inserted, but user still will be able to interrupt +.Ic autoboot +process and escape into the interactive mode by pressing some key +on the console while kernel and +modules are being loaded. +.Pp +If set to +.Dq Li -1 , +no delay will be inserted and +.Nm +will engage interactive mode only if +.Ic autoboot +has failed for some reason. +.It Va boot_ask +Will set +.Xr kernel 8 +.Fl a +option. +.It Va boot_debug +Will set +.Xr kernel 8 +.Fl d +option. +.It Va boot_kmdb +Will set +.Xr kernel 8 +.Fl k +option. +.It Va boot_reconfigure +Will set +.Xr kernel 8 +.Fl r +option. +.It Va boot_single +Will set +.Xr kernel 8 +.Fl s +option. +.It Va boot_verbose +Will set +.Xr kernel 8 +.Fl v +option. +.It Va boot-args +Will set custom arguments for the kernel. +If set in +.Nm +configuration, the +.Nm +startup will parse the +.Va boot-args +value to set boot prefixed variables listed above, any unrecognized options +are added to kernel command line verbatim. +.It Va bootfile +The name of the kernel. +.It Va console +Defines the current console or consoles. +Multiple consoles may be specified. +In that case, the first listed console will become the default console for +the +.Xr kernel 8 . +.It Va currdev +Selects the default device. +Syntax for devices is odd. +.It Va interpret +Has the value +.Dq Li ok +if the Forth's current state is interpreting. +.It Va screen-#rows +Define the number of lines on the screen, to be used by the pager. +.It Va module_path +Sets the list of directories which will be searched for modules +named in a load command or implicitly required by a dependency. +The default value for this variable is +.Dq Li /platform/i86pc/${ISADIR} +.It Va prompt +Value of +.Nm Ns 's +prompt. +Defaults to +.Dq Li "${interpret}" . +If variable +.Va prompt +is unset, the default prompt is +.Ql > . +.It Va os_console +If set, the value is used to set +.Xr kernel 8 +.Va console +property. +.El +.Pp +Other variables are used for loader or to set kernel properties or for +informational purposes. +.Ss Builtin Parser +When a builtin command is executed, the rest of the line is taken +by it as arguments, and it is processed by a special parser which +is not used for regular Forth commands. +.Pp +This special parser applies the following rules to the parsed text: +.Bl -enum +.It +All backslash characters are preprocessed. +.Bl -bullet +.It +\eb , \ef , \er , \en and \et are processed as in C. +.It +\es is converted to a space. +.It +\ev is converted to +.Tn ASCII +11. +.It +\ez is just skipped. +Useful for things like +.Dq \e0xf\ez\e0xf . +.It +\e0xN and \e0xNN are replaced by the hex N or NN. +.It +\eNNN is replaced by the octal NNN +.Tn ASCII +character. +.It +\e" , \e' and \e$ will escape these characters, preventing them from +receiving special treatment in Step 2, described below. +.It +\e\e will be replaced with a single \e . +.It +In any other occurrence, backslash will just be removed. +.El +.It +Every string between non-escaped quotes or double-quotes will be treated +as a single word for the purposes of the remaining steps. +.It +Replace any +.Li $VARIABLE +or +.Li ${VARIABLE} +with the value of the environment variable +.Va VARIABLE . +.It +Space-delimited arguments are passed to the called builtin command. +Spaces can also be escaped through the use of \e\e . +.El +.Pp +An exception to this parsing rule exists, and is described in +.Sx Builtins And FORTH . +.Ss Builtins And FORTH +All builtin words are state-smart, immediate words. +If interpreted, they behave exactly as described previously. +If they are compiled, though, +they extract their arguments from the stack instead of the command line. +.Pp +If compiled, the builtin words expect to find, at execution time, the +following parameters on the stack: +.D1 Ar addrN lenN ... addr2 len2 addr1 len1 N +where +.Ar addrX lenX +are strings which will compose the command line that will be parsed +into the builtin's arguments. +Internally, these strings are concatenated in from 1 to N, +with a space put between each one. +.Pp +If no arguments are passed, a 0 +.Em must +be passed, even if the builtin accepts no arguments. +.Pp +While this behavior has benefits, it has its trade-offs. +If the execution token of a builtin is acquired (through +.Ic ' +or +.Ic ['] ) , +and then passed to +.Ic catch +or +.Ic execute , +the builtin behavior will depend on the system state +.Bf Em +at the time +.Ic catch +or +.Ic execute +is processed! +.Ef +This is particularly annoying for programs that want or need to +handle exceptions. +In this case, the use of a proxy is recommended. +For example: +.Dl : (boot) boot ; +.Ss FICL +.Tn FICL +is a Forth interpreter written in C, in the form of a forth +virtual machine library that can be called by C functions and vice +versa. +.Pp +In +.Nm , +each line read interactively is then fed to +.Tn FICL , +which may call +.Nm +back to execute the builtin words. +The builtin +.Ic include +will also feed +.Tn FICL , +one line at a time. +.Pp +The words available to +.Tn FICL +can be classified into four groups. +The +.Tn ANS +Forth standard words, extra +.Tn FICL +words, extra +.Fx +words, and the builtin commands; +the latter were already described. +The +.Tn ANS +Forth standard words are listed in the +.Sx STANDARDS +section. +The words falling in the two other groups are described in the +following subsections. +.Ss FICL Extra Words +.Bl -tag -width wid-set-super +.It Ic .env +.It Ic .ver +.It Ic -roll +.It Ic 2constant +.It Ic >name +.It Ic body> +.It Ic compare +This is the STRING word set's +.Ic compare . +.It Ic compile-only +.It Ic endif +.It Ic forget-wid +.It Ic parse-word +.It Ic sliteral +This is the STRING word set's +.Ic sliteral . +.It Ic wid-set-super +.It Ic w@ +.It Ic w! +.It Ic x. +.It Ic empty +.It Ic cell- +.It Ic -rot +.El +.Ss Loader Extra Words +.Bl -tag -width XXXXXXXX +.It Ic \&$ Pq -- +Evaluates the remainder of the input buffer, after having printed it first. +.It Ic \&% Pq -- +Evaluates the remainder of the input buffer under a +.Ic catch +exception guard. +.It Ic .# +Works like +.Ic \&. +but without outputting a trailing space. +.It Ic fclose Pq Ar fd -- +Closes a file. +.It Ic fkey Pq Ar fd -- char +Reads a single character from a file. +.It Ic fload Pq Ar fd -- +Processes a file +.Em fd . +.It Ic fopen Pq Ar addr len mode Li -- Ar fd +Opens a file. +Returns a file descriptor, or \-1 in case of failure. +The +.Ar mode +parameter selects whether the file is to be opened for read access, write +access, or both. +The constants +.Dv O_RDONLY , O_WRONLY , +and +.Dv O_RDWR +are defined in +.Pa /boot/forth/support.4th , +indicating read only, write only, and read-write access, respectively. +.It Xo +.Ic fread +.Pq Ar fd addr len -- len' +.Xc +Tries to read +.Em len +bytes from file +.Em fd +into buffer +.Em addr . +Returns the actual number of bytes read, or -1 in case of error or end of +file. +.It Ic heap? Pq -- Ar cells +Return the space remaining in the dictionary heap, in cells. +This is not related to the heap used by dynamic memory allocation words. +.It Ic inb Pq Ar port -- char +Reads a byte from a port. +.It Ic isvirtualized? Pq -- Ar addr len flag | Ar flag +Returns +.Ic true +and string with virtualization engine name or +.Ic false . +.It Ic key Pq -- Ar char +Reads a single character from the console. +.It Ic key? Pq -- Ar flag +Returns +.Ic true +if there is a character available to be read from the console. +.It Ic ms Pq Ar u -- +Waits +.Em u +microseconds. +.It Ic outb Pq Ar port char -- +Writes a byte to a port. +.It Ic seconds Pq -- Ar u +Returns the number of seconds since midnight. +.It Ic tib> Pq -- Ar addr len +Returns the remainder of the input buffer as a string on the stack. +.El +.Ss Loader Extra Framebuffer Words +.Bl -tag -width XXXXXXXX +.It Ic fb-bezier Pq Ar x1 y1 x2 y2 x3 y3 width -- +Draws a quadratic Bezier curve in the current foreground color using the +three provided points and specified line with. +.It Ic fb-drawrect Pq Ar x1 y1 x2 y2 fill -- +Draws a rectangle to the screen with the top left at +.Em (x1,y1) +and the bottom right at +.Em (x2,y2) +, using the current foreground color. +If +.Em fill +is +.Ic true +then the rectangle will be filled in. +.It Ic fb-line Pq Ar x1 y1 x2 y2 width -- +Draws a line from +.Em (x1,y1) +to +.Em (x2,y2) +in the current foreground color and with the specified width. +.It Ic fb-putimage Pq Ar flags x1 y1 x2 y2 addr len -- flag +Outputs an image to the screen. +Returns +.Ic true +if the image was able to be written and +.Ic false +otherwise. +Only truecolor PNG images are supported and the path to the file +must be provided through the +.Em addr +and +.Em len +arguments on the stack. +The image will be displayed in the rectangular screen region with the top left +at +.Em (x1,y1) +and the bottom right at +.Em (x2,y2) +. +.Pp +Either +.Em x2 +or +.Em y2 +can be set to "0" which causes it to be calculated to maintain the aspect +ratio of the image. +If both are "0" then the native resolution of the image will be used. +.Pp +If +.Em x1 +is "0", then the image will be placed as far over to the right of the +screen as possible. +Similarly, if +.Em y1 +is "0", then the image will be placed as far down the screen as possible. +.Pp +Flags is a bitfield; the following bits are defined: +.Bl -tag -width XXXXX -offset indent +.It 1 +Draw a single pixel border around the image in the current foreground color. +.It 2 +Do not scroll the image with the rest of the screen. +.It 128 +Output diagnostic information (for debugging). +.El +.It Ic fb-setpixel Pq Ar x y -- +Colors the pixel at +.Em (x,y) +with the current foreground color. +.It Ic term-drawrect Pq Ar x1 y1 x2 y2 -- +Draws a rectangle with rounded corners using terminal coordinates and the +current foreground color. +.El +.Ss Loader Defined Environmental Queries +.Bl -tag -width Ds +.It arch-i386 +.Ic TRUE +if the architecture is IA32. +.It loader_version +.Nm +version. +.El +.Ss Errors +The following values are thrown by +.Nm : +.Bl -tag -width XXXXX -offset indent +.It 100 +Any type of error in the processing of a builtin. +.It -1 +.Ic Abort +executed. +.It -2 +.Ic Abort" +executed. +.It -56 +.Ic Quit +executed. +.It -256 +Out of interpreting text. +.It -257 +Need more text to succeed -- will finish on next run. +.It -258 +.Ic Bye +executed. +.It -259 +Unspecified error. +.El +.Sh FILES +.Bl -tag -width /boot/defaults/loader.conf -compact +.It Pa /boot/defaults/loader.conf +.It Pa /boot/conf.d/* +.It Pa /boot/loader.conf +.It Pa /boot/loader.conf.local +.Nm +configuration files, as described in +.Xr loader.conf 5 . +.It Pa /boot/loader.help +Loaded by +.Ic help . +Contains the help messages. +.It Pa /boot/loader.rc +.Nm +bootstrapping script. +.It Pa /boot/forth/loader.4th +Extra builtin-like words. +.It Pa /boot/forth/support.4th +.Pa loader.conf +processing words. +.It Pa /boot/loader +.Nm +itself. +.El +.Sh EXAMPLES +Boot in single user mode: +.Pp +.Dl boot -s +.Pp +Load the kernel, a boot_archive, and then autoboot in five seconds. +Notice that a kernel must be loaded before any other +.Ic load +command is attempted. +.Bd -literal -offset indent +load /platform/i86pc/kernel/amd64/unix +load -t rootfs /platform/i86pc/amd64/boot_archive +autoboot 5 +.Ed +.Pp +Set the default device used for loading a kernel from a ZFS filesystem: +.Bd -literal -offset indent +set currdev=zfs:rpool/ROOT/knowngood: +.Ed +.Sh NOTES +Although setting the +.Va currdev +as shown in the example above is supported, it is advisable to use loader +beadm command or boot environment menu instead. +The reason is, the beadm or menu selection will also instruct loader to clean up +the currently set configuration and load configuration from the new boot +environment. +.Sh SEE ALSO +.Xr btxld 1onbld , +.Xr loader.conf 5 , +.Xr boot 8 +.Sh STANDARDS +For the purposes of ANS Forth compliance, loader is an +.Bf Em +ANS Forth System with Environmental Restrictions, Providing +.Ef +.Bf Li +.No .( , +.No :noname , +.No ?do , +parse, pick, roll, refill, to, value, \e, false, true, +.No <> , +.No 0<> , +compile\&, , erase, nip, tuck +.Ef +.Em and +.Li marker +.Bf Em +from the Core Extensions word set, Providing the Exception Extensions +word set, Providing the Locals Extensions word set, Providing the +Memory-Allocation Extensions word set, Providing +.Ef +.Bf Li +\&.s, +bye, forget, see, words, +\&[if], +\&[else] +.Ef +.Em and +.Li [then] +.Bf Em +from the Programming-Tools extension word set, Providing the +Search-Order extensions word set. +.Ef diff --git a/usr/src/man/man7/locale.7 b/usr/src/man/man7/locale.7 new file mode 100644 index 0000000000..a99304653b --- /dev/null +++ b/usr/src/man/man7/locale.7 @@ -0,0 +1,2463 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" +.TH LOCALE 7 "May 16, 2020" +.SH NAME +locale \- subset of a user's environment that depends on language and cultural +conventions +.SH DESCRIPTION +A \fBlocale\fR is the definition of the subset of a user's environment that +depends on language and cultural conventions. It is made up from one or more +categories. Each category is identified by its name and controls specific +aspects of the behavior of components of the system. Category names correspond +to the following environment variable names: +.sp +.ne 2 +.na +\fB\fBLC_CTYPE\fR\fR +.ad +.RS 15n +Character classification and case conversion. +.RE + +.sp +.ne 2 +.na +\fB\fBLC_COLLATE\fR\fR +.ad +.RS 15n +Collation order. +.RE + +.sp +.ne 2 +.na +\fB\fBLC_TIME\fR\fR +.ad +.RS 15n +Date and time formats. +.RE + +.sp +.ne 2 +.na +\fB\fBLC_NUMERIC\fR\fR +.ad +.RS 15n +Numeric formatting. +.RE + +.sp +.ne 2 +.na +\fB\fBLC_MONETARY\fR\fR +.ad +.RS 15n +Monetary formatting. +.RE + +.sp +.ne 2 +.na +\fB\fBLC_MESSAGES\fR\fR +.ad +.RS 15n +Formats of informative and diagnostic messages and interactive responses. +.RE + +.sp +.LP +The standard utilities base their behavior on the current locale, as defined +in the ENVIRONMENT VARIABLES section for each utility. The behavior of some of +the C-language functions will also be modified based on the current locale, as +defined by the last call to \fBsetlocale\fR(3C). +.sp +.LP +Locales other than those supplied by the implementation can be created by the +application via the \fBlocaledef\fR(1) utility. The value that is used to +specify a locale when using environment variables will be the string specified +as the \fIname\fR operand to \fBlocaledef\fR when the locale was created. The +strings "C" and "POSIX" are reserved as identifiers for the POSIX locale. +.sp +.LP +Applications can select the desired locale by invoking the \fBsetlocale()\fR +function with the appropriate value. If the function is invoked with an empty +string, such as: +.sp +.in +2 +.nf +setlocale(LC_ALL, ""); +.fi +.in -2 + +.sp +.LP +the value of the corresponding environment variable is used. If the environment +variable is unset or is set to the empty string, the \fBsetlocale()\fR +function sets the appropriate environment. +.SS "Locale Definition" +Locales can be described with the file format accepted by the \fBlocaledef\fR +utility. +.sp +.LP +The locale definition file must contain one or more locale category source +definitions, and must not contain more than one definition for the same locale +category. +.sp +.LP +A category source definition consists of a category header, a category body and +a category trailer. A category header consists of the character string naming +of the category, beginning with the characters \fBLC_\fR. The category trailer +consists of the string \fBEND\fR, followed by one or more blank characters and +the string used in the corresponding category header. +.sp +.LP +The category body consists of one or more lines of text. Each line contains an +identifier, optionally followed by one or more operands. Identifiers are either +keywords, identifying a particular locale element, or collating elements. Each +keyword within a locale must have a unique name (that is, two categories cannot +have a commonly-named keyword). No keyword can start with the characters +\fBLC_\fR. Identifiers must be separated from the operands by one or more blank +characters. +.sp +.LP +Operands must be characters, collating elements, or strings of characters. +Strings must be enclosed in double-quotes (\fB"\fR). Literal double-quotes +within strings must be preceded by the <\fIescape character\fR>, as described +below. When a keyword is followed by more than one operand, the operands must +be separated by semicolons (\fB;\fR). Blank characters are allowed both before +and after a semicolon. +.sp +.LP +The first category header in the file can be preceded by a line modifying the +comment character. It has the following format, starting in column 1: +.sp +.in +2 +.nf +"comment_char %c\en",<\fIcomment character\fR> +.fi +.in -2 + +.sp +.LP +The comment character defaults to the number sign (\fB#\fR). Blank lines and +lines containing the <\fIcomment character\fR> in the first position are +ignored. +.sp +.LP +The first category header in the file can be preceded by a line modifying the +escape character to be used in the file. It has the following format, starting +in column 1: +.sp +.in +2 +.nf +"escape_char %c\en",<\fIescape character\fR> +.fi +.in -2 +.sp + +.sp +.LP +The escape character defaults to backslash. +.sp +.LP +A line can be continued by placing an escape character as the last character on +the line; this continuation character will be discarded from the input. +Although the implementation need not accept any one portion of a continued line +with a length exceeding \fB{LINE_MAX}\fR bytes, it places no limits on the +accumulated length of the continued line. Comment lines cannot be continued on +a subsequent line using an escaped newline character. +.sp +.LP +Individual characters, characters in strings, and collating elements must be +represented using symbolic names, as defined below. In addition, characters can +be represented using the characters themselves or as octal, hexadecimal or +decimal constants. When non-symbolic notation is used, the resultant locale +definitions will in many cases not be portable between systems. The left angle +bracket (\fB<\fR) is a reserved symbol, denoting the start of a symbolic name; +when used to represent itself it must be preceded by the escape character. The +following rules apply to character representation: +.RS +4 +.TP +1. +A character can be represented via a symbolic name, enclosed within angle +brackets \fB<\fR and \fB>\fR. The symbolic name, including the angle brackets, +must exactly match a symbolic name defined in the charmap file specified via +the \fBlocaledef\fR \fB-f\fR option, and will be replaced by a character value +determined from the value associated with the symbolic name in the charmap +file. The use of a symbolic name not found in the charmap file constitutes an +error, unless the category is \fBLC_CTYPE\fR or \fBLC_COLLATE\fR, in which +case it constitutes a warning condition (see \fBlocaledef\fR(1) for a +description of action resulting from errors and warnings). The specification of +a symbolic name in a \fBcollating-element\fR or \fBcollating-symbol\fR section +that duplicates a symbolic name in the charmap file (if present) is an error. +Use of the escape character or a right angle bracket within a symbolic name is +invalid unless the character is preceded by the escape character. +.sp +Example: +.sp +.in +2 +.nf +<C>;<c-cedilla> "<M><a><y>" +.fi +.in -2 +.sp + +.RE +.RS +4 +.TP +2. +A character can be represented by the character itself, in which case the +value of the character is implementation-dependent. Within a string, the +double-quote character, the escape character and the right angle bracket +character must be escaped (preceded by the escape character) to be interpreted +as the character itself. Outside strings, the characters +.sp +.in +2 +.nf +\fB, ; < >\fR \fIescape_char\fR +.fi +.in -2 +.sp + +must be escaped to be interpreted as the character itself. +.sp +Example: +.sp +.in +2 +.nf +c "May" +.fi +.in -2 +.sp + +.RE +.RS +4 +.TP +3. +A character can be represented as an octal constant. An octal constant is +specified as the escape character followed by two or more octal digits. Each +constant represents a byte value. Multi-byte values can be represented by +concatenated constants specified in byte order with the last constant +specifying the least significant byte of the character. +.sp +Example: +.sp +.in +2 +.nf +\e143;\e347;\e143\e150 "\e115\e141\e171" +.fi +.in -2 +.sp + +.RE +.RS +4 +.TP +4. +A character can be represented as a hexadecimal constant. A hexadecimal +constant is specified as the escape character followed by an \fBx\fR followed +by two or more hexadecimal digits. Each constant represents a byte value. +Multi-byte values can be represented by concatenated constants specified in +byte order with the last constant specifying the least significant byte of the +character. +.sp +Example: +.sp +.in +2 +.nf +\ex63;\exe7;\ex63\ex68 "\ex4d\ex61\ex79" +.fi +.in -2 +.sp + +.RE +.RS +4 +.TP +5. +A character can be represented as a decimal constant. A decimal constant is +specified as the escape character followed by a \fBd\fR followed by two or more +decimal digits. Each constant represents a byte value. Multi-byte values can be +represented by concatenated constants specified in byte order with the last +constant specifying the least significant byte of the character. +.sp +Example: +.sp +.in +2 +.nf +\ed99;\ed231;\ed99\ed104 "\ed77\ed97\ed121" +.fi +.in -2 +.sp + +Only characters existing in the character set for which the locale definition +is created can be specified, whether using symbolic names, the characters +themselves, or octal, decimal or hexadecimal constants. If a charmap file is +present, only characters defined in the charmap can be specified using octal, +decimal or hexadecimal constants. Symbolic names not present in the charmap +file can be specified and will be ignored, as specified under item 1 above. +.RE +.SS "LC_CTYPE" +The \fBLC_CTYPE\fR category defines character classification, case conversion +and other character attributes. In addition, a series of characters can be +represented by three adjacent periods representing an ellipsis symbol +(\fB\&...\fR). The ellipsis specification is interpreted as meaning that all +values between the values preceding and following it represent valid +characters. The ellipsis specification is valid only within a single encoded +character set, that is, within a group of characters of the same size. An +ellipsis is interpreted as including in the list all characters with an encoded +value higher than the encoded value of the character preceding the ellipsis and +lower than the encoded value of the character following the ellipsis. +.sp +.LP +Example: +.sp +.in +2 +.nf +\ex30;...;\ex39; +.fi +.in -2 +.sp + +.sp +.LP +includes in the character class all characters with encoded values between the +endpoints. +.sp +.LP +The following keywords are recognized. In the descriptions, the term +``automatically included'' means that it is not an error either to include or +omit any of the referenced characters. +.sp +.LP +The character classes \fBdigit\fR, \fBxdigit\fR, \fBlower\fR, \fBupper\fR, and +\fBspace\fR have a set of automatically included characters. These only need to +be specified if the character values (that is, encoding) differ from the +implementation default values. +.sp +.ne 2 +.na +\fB\fBupper\fR\fR +.ad +.RS 18n +Define characters to be classified as upper-case letters. +.sp +In the POSIX locale, the 26 upper-case letters are included: +.sp +.in +2 +.nf +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +.fi +.in -2 +.sp + +In a locale definition file, no character specified for the keywords +\fBcntrl\fR, \fBdigit\fR, \fBpunct\fR, or \fBspace\fR can be specified. The +upper-case letters \fBA\fR to \fBZ\fR are automatically included in this class. +.RE + +.sp +.ne 2 +.na +\fB\fBlower\fR\fR +.ad +.RS 18n +Define characters to be classified as lower-case letters. In the POSIX locale, +the 26 lower-case letters are included: +.sp +.in +2 +.nf +a b c d e f g h i j k l m n o p q r s t u v w x y z +.fi +.in -2 +.sp + +In a locale definition file, no character specified for the keywords +\fBcntrl\fR, \fBdigit\fR, \fBpunct\fR, or \fBspace\fR can be specified. The +lower-case letters \fBa\fR to \fBz\fR of the portable character set are +automatically included in this class. +.RE + +.sp +.ne 2 +.na +\fB\fBalpha\fR\fR +.ad +.RS 18n +Define characters to be classified as letters. +.sp +In the POSIX locale, all characters in the classes \fBupper\fR and \fBlower\fR +are included. +.sp +In a locale definition file, no character specified for the keywords +\fBcntrl\fR, \fBdigit\fR, \fBpunct\fR, or \fBspace\fR can be specified. +Characters classified as either \fBupper\fR or \fBlower\fR are automatically +included in this class. +.RE + +.sp +.ne 2 +.na +\fB\fBdigit\fR\fR +.ad +.RS 18n +Define the characters to be classified as numeric digits. +.sp +In the POSIX locale, only +.sp +.in +2 +.nf +0 1 2 3 4 5 6 7 8 9 +.fi +.in -2 +.sp + +are included. +.sp +In a locale definition file, only the digits \fB0\fR, \fB1\fR, \fB2\fR, +\fB3\fR, \fB4\fR, \fB5\fR, \fB6\fR, \fB7\fR, \fB8\fR, and \fB9\fR can be +specified, and in contiguous ascending sequence by numerical value. The digits +\fB0\fR to \fB9\fR of the portable character set are automatically included in +this class. +.sp +The definition of character class \fBdigit\fR requires that only ten +characters; the ones defining digits can be specified; alternative digits (for +example, Hindi or Kanji) cannot be specified here. +.RE + +.sp +.ne 2 +.na +\fB\fBalnum\fR\fR +.ad +.RS 18n +Define characters to be classified as letters and numeric digits. Only the +characters specified for the \fBalpha\fR and \fBdigit\fR keywords are +specified. Characters specified for the keywords \fBalpha\fR and \fBdigit\fR +are automatically included in this class. +.RE + +.sp +.ne 2 +.na +\fB\fBspace\fR\fR +.ad +.RS 18n +Define characters to be classified as white-space characters. +.sp +In the POSIX locale, at a minimum, the characters \fBSPACE\fR, \fBFORMFEED\fR, +\fBNEWLINE\fR, \fBCARRIAGE RETURN\fR, \fBTAB\fR, and \fBVERTICAL TAB\fR are +included. +.sp +In a locale definition file, no character specified for the keywords +\fBupper\fR, \fBlower\fR, \fBalpha\fR, \fBdigit\fR, \fBgraph\fR, or +\fBxdigit\fR can be specified. The characters \fBSPACE\fR, \fBFORMFEED\fR, +\fBNEWLINE\fR, \fBCARRIAGE RETURN\fR, \fBTAB\fR, and \fBVERTICAL TAB\fR of the +portable character set, and any characters included in the class \fBblank\fR +are automatically included in this class. +.RE + +.sp +.ne 2 +.na +\fB\fBcntrl\fR\fR +.ad +.RS 18n +Define characters to be classified as control characters. +.sp +In the POSIX locale, no characters in classes \fBalpha\fR or \fBprint\fR are +included. +.sp +In a locale definition file, no character specified for the keywords +\fBupper\fR, \fBlower\fR, \fBalpha\fR, \fBdigit\fR, \fBpunct\fR, \fBgraph\fR, +\fBprint\fR, or \fBxdigit\fR can be specified. +.RE + +.sp +.ne 2 +.na +\fB\fBpunct\fR\fR +.ad +.RS 18n +Define characters to be classified as punctuation characters. +.sp +In the POSIX locale, neither the space character nor any characters in classes +\fBalpha\fR, \fBdigit\fR, or \fBcntrl\fR are included. +.sp +In a locale definition file, no character specified for the keywords +\fBupper\fR, \fBlower\fR, \fBalpha\fR, \fBdigit\fR, \fBcntrl\fR, \fBxdigit\fR +or as the space character can be specified. +.RE + +.sp +.ne 2 +.na +\fB\fBgraph\fR\fR +.ad +.RS 18n +Define characters to be classified as printable characters, not including the +space character. +.sp +In the POSIX locale, all characters in classes \fBalpha\fR, \fBdigit\fR, and +\fBpunct\fR are included; no characters in class \fBcntrl\fR are included. +.sp +In a locale definition file, characters specified for the keywords \fBupper\fR, +\fBlower\fR, \fBalpha\fR, \fBdigit\fR, \fBxdigit\fR, and \fBpunct\fR are +automatically included in this class. No character specified for the keyword +\fBcntrl\fR can be specified. +.RE + +.sp +.ne 2 +.na +\fB\fBprint\fR\fR +.ad +.RS 18n +Define characters to be classified as printable characters, including the space +character. +.sp +In the POSIX locale, all characters in class \fBgraph\fR are included; no +characters in class \fBcntrl\fR are included. +.sp +In a locale definition file, characters specified for the keywords \fBupper\fR, +\fBlower\fR, \fBalpha\fR, \fBdigit\fR, \fBxdigit\fR, \fBpunct\fR, and the space +character are automatically included in this class. No character specified for +the keyword \fBcntrl\fR can be specified. +.RE + +.sp +.ne 2 +.na +\fB\fBxdigit\fR\fR +.ad +.RS 18n +Define the characters to be classified as hexadecimal digits. +.sp +In the POSIX locale, only: +.sp +.in +2 +.nf +0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f +.fi +.in -2 +.sp + +are included. +.sp +In a locale definition file, only the characters defined for the class +\fBdigit\fR can be specified, in contiguous ascending sequence by numerical +value, followed by one or more sets of six characters representing the +hexadecimal digits 10 to 15 inclusive, with each set in ascending order (for +example \fBA\fR, \fBB\fR, \fBC\fR, \fBD\fR, \fBE\fR, \fBF\fR, \fBa\fR, \fBb\fR, +\fBc\fR, \fBd\fR, \fBe\fR, \fBf\fR). The digits \fB0\fR to \fB9\fR, the +upper-case letters \fBA\fR to \fBF\fR and the lower-case letters \fBa\fR to +\fBf\fR of the portable character set are automatically included in this class. +.sp +The definition of character class \fBxdigit\fR requires that the characters +included in character class \fBdigit\fR be included here also. +.RE + +.sp +.ne 2 +.na +\fB\fBblank\fR\fR +.ad +.RS 18n +Define characters to be classified as blank characters. +.sp +In the POSIX locale, only the space and tab characters are included. +.sp +In a locale definition file, the characters space and tab are automatically +included in this class. +.RE + +.sp +.ne 2 +.na +\fB\fBcharclass\fR\fR +.ad +.RS 18n +Define one or more locale-specific character class names as strings separated +by semi-colons. Each named character class can then be defined subsequently in +the \fBLC_CTYPE\fR definition. A character class name consists of at least one +and at most \fB{CHARCLASS_NAME_MAX}\fR bytes of alphanumeric characters from +the portable filename character set. The first character of a character class +name cannot be a digit. The name cannot match any of the \fBLC_CTYPE\fR +keywords defined in this document. +.RE + +.sp +.ne 2 +.na +\fB\fBcharclass-name\fR\fR +.ad +.RS 18n +Define characters to be classified as belonging to the named locale-specific +character class. In the POSIX locale, the locale-specific named character +classes need not exist. If a class name is defined by a \fBcharclass\fR +keyword, but no characters are subsequently assigned to it, this is not an +error; it represents a class without any characters belonging to it. The +\fBcharclass-name\fR can be used as the \fIproperty\fR argument to the +\fBwctype\fR(3C) function, in regular expression and shell pattern-matching +bracket expressions, and by the \fBtr\fR(1) command. +.RE + +.sp +.ne 2 +.na +\fB\fBtoupper\fR\fR +.ad +.RS 18n +Define the mapping of lower-case letters to upper-case letters. +.sp +In the POSIX locale, at a minimum, the 26 lower-case characters: +.sp +.in +2 +.nf +a b c d e f g h i j k l m n o p q r s t u v w x y z +.fi +.in -2 +.sp + +are mapped to the corresponding 26 upper-case characters: +.sp +.in +2 +.nf +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +.fi +.in -2 +.sp + +In a locale definition file, the operand consists of character pairs, separated +by semicolons. The characters in each character pair are separated by a comma +and the pair enclosed by parentheses. The first character in each pair is the +lower-case letter, the second the corresponding upper-case letter. Only +characters specified for the keywords \fBlower\fR and \fBupper\fR can be +specified. The lower-case letters \fBa\fR to \fBz\fR, and their corresponding +upper-case letters \fBA\fR to \fBZ\fR, of the portable character set are +automatically included in this mapping, but only when the \fBtoupper\fR keyword +is omitted from the locale definition. +.RE + +.sp +.ne 2 +.na +\fB\fBtolower\fR\fR +.ad +.RS 18n +Define the mapping of upper-case letters to lower-case letters. +.sp +In the POSIX locale, at a minimum, the 26 upper-case characters: +.sp +.in +2 +.nf +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +.fi +.in -2 +.sp + +are mapped to the corresponding 26 lower-case characters: +.sp +.in +2 +.nf +a b c d e f g h i j k l m n o p q r s t u v w x y z +.fi +.in -2 +.sp + +In a locale definition file, the operand consists of character pairs, separated +by semicolons. The characters in each character pair are separated by a comma +and the pair enclosed by parentheses. The first character in each pair is the +upper-case letter, the second the corresponding lower-case letter. Only +characters specified for the keywords \fBlower\fR and \fBupper\fR can be +specified. If the \fBtolower\fR keyword is omitted from the locale definition, +the mapping will be the reverse mapping of the one specified for \fBtoupper\fR. +.RE + +.SS "LC_COLLATE" +The \fBLC_COLLATE\fR category provides a collation sequence definition for +numerous utilities (such as \fBsort\fR(1), \fBuniq\fR(1), and so forth), +regular expression matching (see \fBregex\fR(7)), and the \fBstrcoll\fR(3C), +\fBstrxfrm\fR(3C), \fBwcscoll\fR(3C), and \fBwcsxfrm\fR(3C) functions. +.sp +.LP +A collation sequence definition defines the relative order between collating +elements (characters and multi-character collating elements) in the locale. +This order is expressed in terms of collation values, that is, by assigning +each element one or more collation values (also known as collation weights). +The following capabilities are provided: +.RS +4 +.TP +1. +\fBMulti-character collating elements\fR. Specification of multi-character +collating elements (that is, sequences of two or more characters to be collated +as an entity). +.RE +.RS +4 +.TP +2. +\fBUser-defined ordering of collating elements\fR. Each collating element is +assigned a collation value defining its order in the character (or basic) +collation sequence. This ordering is used by regular expressions and pattern +matching and, unless collation weights are explicitly specified, also as the +collation weight to be used in sorting. +.RE +.RS +4 +.TP +3. +\fBMultiple weights and equivalence classes\fR. Collating elements can be +assigned one or more (up to the limit \fB{COLL_WEIGHTS_MAX}\fR \fB)\fR +collating weights for use in sorting. The first weight is hereafter referred to +as the primary weight. +.RE +.RS +4 +.TP +4. +\fBOne-to-Many mapping\fR. A single character is mapped into a string of +collating elements. +.RE +.RS +4 +.TP +5. +\fBEquivalence class definition\fR. Two or more collating elements have the +same collation value (primary weight). +.RE +.RS +4 +.TP +6. +\fBOrdering by weights\fR. When two strings are compared to determine their +relative order, the two strings are first broken up into a series of collating +elements. The elements in each successive pair of elements are then compared +according to the relative primary weights for the elements. If equal, and more +than one weight has been assigned, the pairs of collating elements are +recompared according to the relative subsequent weights, until either a pair of +collating elements compare unequal or the weights are exhausted. +.RE +.sp +.LP +The following keywords are recognized in a collation sequence definition. They +are described in detail in the following sections. +.sp +.ne 2 +.na +\fB\fBcopy\fR\fR +.ad +.RS 21n +Specify the name of an existing locale which is used as the definition of this +category. If this keyword is specified, no other keyword is specified. +.RE + +.sp +.ne 2 +.na +\fB\fBcollating-element\fR\fR +.ad +.RS 21n +Define a collating-element symbol representing a multi-character collating +element. This keyword is optional. +.RE + +.sp +.ne 2 +.na +\fB\fBcollating-symbol\fR\fR +.ad +.RS 21n +Define a collating symbol for use in collation order statements. This keyword +is optional. +.RE + +.sp +.ne 2 +.na +\fB\fBorder_start\fR\fR +.ad +.RS 21n +Define collation rules. This statement is followed by one or more collation +order statements, assigning character collation values and collation weights to +collating elements. +.RE + +.sp +.ne 2 +.na +\fB\fBorder_end\fR\fR +.ad +.RS 21n +Specify the end of the collation-order statements. +.RE + +.SS "collating-element \fIkeyword\fR" +In addition to the collating elements in the character set, the +\fBcollating-element\fR keyword is used to define multi-character collating +elements. The syntax is: +.sp +.in +2 +.nf +\fB"collating-element %s from \e"%s\e"\en",\fR<\fIcollating-symbol\fR>,<\fIstring\fR> +.fi +.in -2 + +.sp +.LP +The <\fIcollating-symbol\fR> operand is a symbolic name, enclosed between angle +brackets (\fB<\fR and \fB>\fR), and must not duplicate any symbolic name in the +current charmap file (if any), or any other symbolic name defined in this +collation definition. The string operand is a string of two or more characters +that collates as an entity. A <\fIcollating-element\fR> defined via this +keyword is only recognized with the \fBLC_COLLATE\fR category. +.sp +.LP +Example: +.br +.in +2 +\fBcollating-element\fR <\fBch\fR> from "<\fBc\fR><\fBh\fR>" +.in -2 +.br +.in +2 +\fBcollating-element\fR <\fBe-acute\fR> from "<\fBacute\fR><\fBe\fR>" +.in -2 +.br +.in +2 +\fBcollating-element\fR <\fBll\fR> from "\fBll\fR" +.in -2 +.SS "collating-symbol \fIkeyword\fR" +This keyword will be used to define symbols for use in collation sequence +statements; that is, between the \fBorder_start\fR and the \fBorder_end\fR +keywords. The syntax is: +.sp +.in +2 +.nf +\fB"collating-symbol %s\en",\fR<\fIcollating-symbol\fR> +.fi +.in -2 + +.sp +.LP +The \fB<\fR\fIcollating-symbol\fR\fB>\fR is a symbolic name, enclosed between +angle brackets (\fB<\fR and \fB>\fR), and must not duplicate any symbolic name +in the current charmap file (if any), or any other symbolic name defined in +this collation definition. +.sp +.LP +A \fBcollating-symbol\fR defined via this keyword is only recognized with the +\fBLC_COLLATE\fR category. +.sp +.LP +Example: +.br +.in +2 +\fBcollating-symbol\fR <\fBUPPER_CASE\fR> +.in -2 +.br +.in +2 +\fBcollating-symbol\fR <\fBHIGH\fR> +.in -2 +.sp +.LP +The \fBcollating-symbol\fR keyword defines a symbolic name that can be +associated with a relative position in the character order sequence. While such +a symbolic name does not represent any collating element, it can be used as a +weight. +.SS "order_start \fIkeyword\fR" +The \fBorder_start\fR keyword must precede collation order entries and also +defines the number of weights for this collation sequence definition and other +collation rules. +.sp +.LP +The syntax of the \fBorder_start\fR keyword is: +.sp +.in +2 +.nf +\fB"order_start %s;%s;...;%s\en",\fR<\fIsort-rules\fR>,<\fIsort-rules\fR> +.fi +.in -2 + +.sp +.LP +The operands to the \fBorder_start\fR keyword are optional. If present, the +operands define rules to be applied when strings are compared. The number of +operands define how many weights each element is assigned. If no operands are +present, one \fBforward\fR operand is assumed. If present, the first operand +defines rules to be applied when comparing strings using the first (primary) +weight; the second when comparing strings using the second weight, and so on. +Operands are separated by semicolons (\fB;\fR). Each operand consists of one or +more collation directives, separated by commas (\fB,\fR). If the number of +operands exceeds the \fB{COLL_WEIGHTS_MAX}\fR limit, the utility will issue a +warning message. The following directives will be supported: +.sp +.ne 2 +.na +\fB\fBforward\fR\fR +.ad +.RS 12n +Specifies that comparison operations for the weight level proceed from start of +string towards the end of string. +.RE + +.sp +.ne 2 +.na +\fB\fBbackward\fR\fR +.ad +.RS 12n +Specifies that comparison operations for the weight level proceed from end of +string towards the beginning of string. +.RE + +.sp +.ne 2 +.na +\fB\fBposition\fR\fR +.ad +.RS 12n +Specifies that comparison operations for the weight level will consider the +relative position of elements in the strings not subject to \fBIGNORE.\fR The +string containing an element not subject to \fBIGNORE\fR after the fewest +collating elements subject to \fBIGNORE\fR from the start of the compare will +collate first. If both strings contain a character not subject to \fBIGNORE\fR +in the same relative position, the collating values assigned to the elements +will determine the ordering. In case of equality, subsequent characters not +subject to \fBIGNORE\fR are considered in the same manner. +.RE + +.sp +.LP +The directives \fBforward\fR and \fBbackward\fR are mutually exclusive. +.sp +.LP +Example: +.sp +.in +2 +.nf +order_start forward;backward +.fi +.in -2 +.sp + +.sp +.LP +If no operands are specified, a single \fBforward\fR operand is assumed. +.SS "Collation Order" +The \fBorder_start\fR keyword is followed by collating identifier entries. The +syntax for the collating element entries is: +.sp +.in +2 +.nf +\fB"%s %s;%s;...;%s\en"\fR<\fIcollating-identifier\fR>,<\fIweight\fR>,<\fIweight\fR>\fB,...\fR +.fi +.in -2 + +.sp +.LP +Each \fIcollating-identifier\fR consists of either a character described in +\fBLocale Definition\fR above, a <\fIcollating-element\fR>, a +<\fIcollating-symbol\fR>, an ellipsis, or the special symbol \fBUNDEFINED\fR. +The order in which collating elements are specified determines the character +order sequence, such that each collating element compares less than the +elements following it. The \fBNUL\fR character compares lower than any other +character. +.sp +.LP +A <\fIcollating-element\fR> is used to specify multi-character collating +elements, and indicates that the character sequence specified via the +<\fIcollating-element\fR> is to be collated as a unit and in the relative order +specified by its place. +.sp +.LP +A <\fIcollating-symbol\fR> is used to define a position in the relative order +for use in weights. No weights are specified with a <\fIcollating-symbol\fR>. +.sp +.LP +The ellipsis symbol specifies that a sequence of characters will collate +according to their encoded character values. It is interpreted as indicating +that all characters with a coded character set value higher than the value of +the character in the preceding line, and lower than the coded character set +value for the character in the following line, in the current coded character +set, will be placed in the character collation order between the previous and +the following character in ascending order according to their coded character +set values. An initial ellipsis is interpreted as if the preceding line +specified the NUL character, and a trailing ellipsis as if the following line +specified the highest coded character set value in the current coded character +set. An ellipsis is treated as invalid if the preceding or following lines do +not specify characters in the current coded character set. The use of the +ellipsis symbol ties the definition to a specific coded character set and may +preclude the definition from being portable between implementations. +.sp +.LP +The symbol \fBUNDEFINED\fR is interpreted as including all coded character set +values not specified explicitly or via the ellipsis symbol. Such characters are +inserted in the character collation order at the point indicated by the symbol, +and in ascending order according to their coded character set values. If no +\fBUNDEFINED\fR symbol is specified, and the current coded character set +contains characters not specified in this section, the utility will issue a +warning message and place such characters at the end of the character collation +order. +.sp +.LP +The optional operands for each collation-element are used to define the +primary, secondary, or subsequent weights for the collating element. The first +operand specifies the relative primary weight, the second the relative +secondary weight, and so on. Two or more collation-elements can be assigned the +same weight; they belong to the same \fIequivalence class\fR if they have the +same primary weight. Collation behaves as if, for each weight level, elements +subject to \fBIGNORE\fR are removed, unless the \fBposition\fR collation +directive is specified for the corresponding level with the \fBorder_start\fR +keyword. Then each successive pair of elements is compared according to the +relative weights for the elements. If the two strings compare equal, the +process is repeated for the next weight level, up to the limit +{\fBCOLL_WEIGHTS_MAX\fR}. +.sp +.LP +Weights are expressed as characters described in \fBLocale Definition\fR +above, <\fIcollating-symbol\fR>s, <\fIcollating-element\fR>s, an ellipsis, or +the special symbol \fBIGNORE.\fR A single character, a <\fIcollating-symbol\fR> +or a <\fIcollating-element\fR> represent the relative position in the character +collating sequence of the character or symbol, rather than the character or +characters themselves. Thus, rather than assigning absolute values to weights, +a particular weight is expressed using the relative order value assigned to a +collating element based on its order in the character collation sequence. +.sp +.LP +One-to-many mapping is indicated by specifying two or more concatenated +characters or symbolic names. For example, if the character <\fBeszet\fR> is +given the string "<\fBs\fR><\fBs\fR>" as a weight, comparisons are performed as +if all occurrences of the character <\fBeszet\fR> are replaced by +<\fBs\fR><\fBs\fR> (assuming that <\fBs\fR> has the collating weight +<\fBs\fR>). If it is necessary to define <\fBeszet\fR> and <\fBs\fR><\fBs\fR> +as an equivalence class, then a collating element must be defined for the +string \fBss\fR. +.sp +.LP +All characters specified via an ellipsis will by default be assigned unique +weights, equal to the relative order of characters. Characters specified via an +explicit or implicit \fBUNDEFINED\fR special symbol will by default be assigned +the same primary weight (that is, belong to the same equivalence class). An +ellipsis symbol as a weight is interpreted to mean that each character in the +sequence has unique weights, equal to the relative order of their character in +the character collation sequence. The use of the ellipsis as a weight is +treated as an error if the collating element is neither an ellipsis nor the +special symbol \fBUNDEFINED\fR. +.sp +.LP +The special keyword \fBIGNORE\fR as a weight indicates that when strings are +compared using the weights at the level where \fBIGNORE\fR is specified, the +collating element is ignored; that is, as if the string did not contain the +collating element. In regular expressions and pattern matching, all characters +that are subject to \fBIGNORE\fR in their primary weight form an equivalence +class. +.sp +.LP +An empty operand is interpreted as the collating element itself. +.sp +.LP +For example, the order statement: +.sp +.in +2 +.nf +<a> <a>;<a> +.fi +.in -2 +.sp + +.sp +.LP +is equal to: +.sp +.in +2 +.nf +<a> +.fi +.in -2 +.sp + +.sp +.LP +An ellipsis can be used as an operand if the collating element was an ellipsis, +and is interpreted as the value of each character defined by the ellipsis. +.sp +.LP +The collation order as defined in this section defines the interpretation of +bracket expressions in regular expressions. +.sp +.LP +Example: +.sp + +.sp +.TS +l l +l l . +\fBorder_start\fR \fBforward;backward\fR +\fBUNDEFINED\fR \fBIGNORE;IGNORE\fR +\fB<LOW>\fR +\fB<space>\fR \fB<LOW>;<space>\fR +\fB\&.\|.\|.\fR \fB<LOW>;.\|.\|.\fR +\fB<a>\fR \fB<a>;<a>\fR +\fB<a-acute>\fR \fB<a>;<a-acute>\fR +\fB<a-grave>\fR \fB<a>;<a-grave>\fR +\fB<A>\fR \fB<a>;<A>\fR +\fB<A-acute>\fR \fB<a>;<A-acute>\fR +\fB<A-grave>\fR \fB<a>;<A-grave>\fR +\fB<ch>\fR \fB<ch>;<ch>\fR +\fB<Ch>\fR \fB<ch>;<Ch>\fR +\fB<s>\fR \fB<s>;<s>\fR +\fB<eszet>\fR \fB"<s><s>";"<eszet><eszet>"\fR +\fBorder_end\fR +.TE + +.sp +.LP +This example is interpreted as follows: +.RS +4 +.TP +1. +The \fBUNDEFINED\fR means that all characters not specified in this +definition (explicitly or via the ellipsis) are ignored for collation purposes; +for regular expression purposes they are ordered first. +.RE +.RS +4 +.TP +2. +All characters between <\fBspace\fR> and <\fBa\fR> have the same primary +equivalence class and individual secondary weights based on their ordinal +encoded values. +.RE +.RS +4 +.TP +3. +All characters based on the upper- or lower-case character \fBa\fR belong to +the same primary equivalence class. +.RE +.RS +4 +.TP +4. +The multi-character collating element <\fBch\fR> is represented by the +collating symbol <\fBch\fR> and belongs to the same primary equivalence class +as the multi-character collating element <\fBCh\fR>. +.RE +.SS "order_end \fIkeyword\fR" +The collating order entries must be terminated with an \fBorder_end\fR keyword. +.SS "LC_MONETARY" +The \fBLC_MONETARY\fR category defines the rules and symbols that are used to +format monetary numeric information. This information is available through the +\fBlocaleconv\fR(3C) function +.sp +.LP +The following items are defined in this category of the locale. The item names +are the keywords recognized by the \fBlocaledef\fR(1) utility when defining a +locale. They are also similar to the member names of the \fBlconv\fR structure +defined in <\fBlocale.h\fR>. The \fBlocaleconv\fR function returns +\fB{CHAR_MAX}\fR for unspecified integer items and the empty string (\fB""\fR) +for unspecified or size zero string items. +.sp +.LP +In a locale definition file the operands are strings. For some keywords, the +strings can contain only integers. Keywords that are not provided, string +values set to the empty string (\fB""\fR), or integer keywords set to \fB-1\fR, +are used to indicate that the value is not available in the locale. +.sp +.ne 2 +.na +\fB\fBint_curr_symbol\fR\fR +.ad +.RS 22n +The international currency symbol. The operand is a four-character string, with +the first three characters containing the alphabetic international currency +symbol in accordance with those specified in the ISO 4217 standard. The fourth +character is the character used to separate the international currency symbol +from the monetary quantity. +.RE + +.sp +.ne 2 +.na +\fB\fBcurrency_symbol\fR\fR +.ad +.RS 22n +The string used as the local currency symbol. +.RE + +.sp +.ne 2 +.na +\fB\fBmon_decimal_point\fR\fR +.ad +.RS 22n +The operand is a string containing the symbol that is used as the decimal +delimiter (radix character) in monetary formatted quantities. +.RE + +.sp +.ne 2 +.na +\fB\fBmon_thousands_sep\fR\fR +.ad +.RS 22n +The operand is a string containing the symbol that is used as a separator for +groups of digits to the left of the decimal delimiter in formatted monetary +quantities. +.RE + +.sp +.ne 2 +.na +\fB\fBmon_grouping\fR\fR +.ad +.RS 22n +Define the size of each group of digits in formatted monetary quantities. The +operand is a sequence of integers separated by semicolons. Each integer +specifies the number of digits in each group, with the initial integer defining +the size of the group immediately preceding the decimal delimiter, and the +following integers defining the preceding groups. If the last integer is not +\fB-1\fR, then the size of the previous group (if any) will be repeatedly used +for the remainder of the digits. If the last integer is \fB-1\fR, then no +further grouping will be performed. +.sp +The following is an example of the interpretation of the \fBmon_grouping\fR +keyword. Assuming that the value to be formatted is \fB123456789\fR and the +\fBmon_thousands_sep\fR is \fB\&'\fR, then the following table shows the +result. The third column shows the equivalent string in the ISO C standard that +would be used by the \fBlocaleconv\fR function to accommodate this grouping. +.sp +.in +2 +.nf +mon_grouping Formatted Value ISO C String + +3;-1 123456'789 "\e3\e177" +3 123'456'789 "\e3" +3;2;-1 1234'56'789 "\e3\e2\e177" +3;2 12'34'56'789 "\e3\e2" +-1 1234567898 "\e177" +.fi +.in -2 +.sp + +In these examples, the octal value of \fB{CHAR_MAX}\fR is 177. +.RE + +.sp +.ne 2 +.na +\fB\fBpositive_sign\fR\fR +.ad +.RS 22n +A string used to indicate a non-negative-valued formatted monetary quantity. +.RE + +.sp +.ne 2 +.na +\fB\fBnegative_sign\fR\fR +.ad +.RS 22n +A string used to indicate a negative-valued formatted monetary quantity. +.RE + +.sp +.ne 2 +.na +\fB\fBint_frac_digits\fR\fR +.ad +.RS 22n +An integer representing the number of fractional digits (those to the right of +the decimal delimiter) to be written in a formatted monetary quantity using +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBfrac_digits\fR\fR +.ad +.RS 22n +An integer representing the number of fractional digits (those to the right of +the decimal delimiter) to be written in a formatted monetary quantity using +\fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBp_cs_precedes\fR\fR +.ad +.RS 22n +In an application conforming to the SUSv3 standard, an integer set to \fB1\fR +if the \fBcurrency_symbol\fR precedes the value for a monetary quantity with a +non-negative value, and set to \fB0\fR if the symbol succeeds the value. +.sp +In an application \fBnot\fR conforming to the SUSv3 standard, an integer set to +\fB1\fR if the \fBcurrency_symbol\fR or \fBint_currency_symbol\fR precedes the +value for a monetary quantity with a non-negative value, and set to \fB0\fR if +the symbol succeeds the value. +.RE + +.sp +.ne 2 +.na +\fB\fBp_sep_by_space\fR\fR +.ad +.RS 22n +In an application conforming to the SUSv3 standard, an integer set to \fB0\fR +if no space separates the \fBcurrency_symbol\fR from the value for a monetary +quantity with a non-negative value, set to \fB1\fR if a space separates the +symbol from the value, and set to \fB2\fR if a space separates the symbol and +the sign string, if adjacent. +.sp +In an application \fBnot\fR conforming to the SUSv3 standard, an integer set to +\fB0\fR if no space separates the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR from the value for a monetary quantity with a +non-negative value, set to \fB1\fR if a space separates the symbol from the +value, and set to \fB2\fR if a space separates the symbol and the sign string, +if adjacent. +.RE + +.sp +.ne 2 +.na +\fB\fBn_cs_precedes\fR\fR +.ad +.RS 22n +In an application conforming to the SUSv3 standard, an integer set to \fB1\fR +if the \fBcurrency_symbol\fR precedes the value for a monetary quantity with a +negative value, and set to \fB0\fR if the symbol succeeds the value. +.sp +In an application \fBnot\fR conforming to the SUSv3 standard, an integer set to +\fB1\fR if the \fBcurrency_symbol\fR or \fBint_currency_symbol\fR precedes the +value for a monetary quantity with a negative value, and set to \fB0\fR if the +symbol succeeds the value. +.RE + +.sp +.ne 2 +.na +\fB\fBn_sep_by_space\fR\fR +.ad +.RS 22n +In an application conforming to the SUSv3 standard, an integer set to \fB0\fR +if no space separates the \fBcurrency_symbol\fR from the value for a monetary +quantity with a negative value, set to \fB1\fR if a space separates the symbol +from the value, and set to \fB2\fR if a space separates the symbol and the sign +string, if adjacent. +.sp +In an application \fBnot\fR conforming to the SUSv3 standard, an integer set to +\fB0\fR if no space separates the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR from the value for a monetary quantity with a negative +value, set to \fB1\fR if a space separates the symbol from the value, and set +to \fB2\fR if a space separates the symbol and the sign string, if adjacent. +.RE + +.sp +.ne 2 +.na +\fB\fBp_sign_posn\fR\fR +.ad +.RS 22n +An integer set to a value indicating the positioning of the \fBpositive_sign\fR +for a monetary quantity with a non-negative value. The following integer values +are recognized for both \fBp_sign_posn\fR and \fBn_sign_posn\fR: +.sp +In an application conforming to the SUSv3 standard: +.sp +.ne 2 +.na +\fB\fB0\fR\fR +.ad +.RS 5n +Parentheses enclose the quantity and the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB1\fR\fR +.ad +.RS 5n +The sign string precedes the quantity and the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB2\fR\fR +.ad +.RS 5n +The sign string succeeds the quantity and the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB3\fR\fR +.ad +.RS 5n +The sign string precedes the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB4\fR\fR +.ad +.RS 5n +The sign string succeeds the \fBcurrency_symbol\fR. +.RE + +In an application \fBnot\fR conforming to the SUSv3 standard: +.sp +.ne 2 +.na +\fB\fB0\fR\fR +.ad +.RS 5n +Parentheses enclose the quantity and the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB1\fR\fR +.ad +.RS 5n +The sign string precedes the quantity and the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB2\fR\fR +.ad +.RS 5n +The sign string succeeds the quantity and the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB3\fR\fR +.ad +.RS 5n +The sign string precedes the \fBcurrency_symbol\fR or \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB4\fR\fR +.ad +.RS 5n +The sign string succeeds the \fBcurrency_symbol\fR or \fBint_curr_symbol\fR. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fBn_sign_posn\fR\fR +.ad +.RS 22n +An integer set to a value indicating the positioning of the \fBnegative_sign\fR +for a negative formatted monetary quantity. +.RE + +.sp +.ne 2 +.na +\fB\fBint_p_cs_precedes\fR\fR +.ad +.RS 22n +An integer set to \fB1\fR if the \fBint_curr_symbol\fR precedes the value for a +monetary quantity with a non-negative value, and set to \fB0\fR if the symbol +succeeds the value. +.RE + +.sp +.ne 2 +.na +\fB\fBint_n_cs_precedes\fR\fR +.ad +.RS 22n +An integer set to \fB1\fR if the \fBint_curr_symbol\fR precedes the value for a +monetary quantity with a negative value, and set to \fB0\fR if the symbol +succeeds the value. +.RE + +.sp +.ne 2 +.na +\fB\fBint_p_sep_by_space\fR\fR +.ad +.RS 22n +An integer set to \fB0\fR if no space separates the \fBint_curr_symbol\fR from +the value for a monetary quantity with a non-negative value, set to \fB1\fR if +a space separates the symbol from the value, and set to \fB2\fR if a space +separates the symbol and the sign string, if adjacent. +.RE + +.sp +.ne 2 +.na +\fB\fBint_n_sep_by_space\fR\fR +.ad +.RS 22n +An integer set to \fB0\fR if no space separates the \fBint_curr_symbol\fR from +the value for a monetary quantity with a negative value, set to \fB1\fR if a +space separates the symbol from the value, and set to \fB2\fR if a space +separates the symbol and the sign string, if adjacent. +.RE + +.sp +.ne 2 +.na +\fB\fBint_p_sign_posn\fR\fR +.ad +.RS 22n +An integer set to a value indicating the positioning of the \fBpositive_sign\fR +for a positive monetary quantity formatted with the international format. The +following integer values are recognized for \fBint_p_sign_posn\fR and +\fBint_n_sign_posn\fR: +.sp +.ne 2 +.na +\fB\fB0\fR\fR +.ad +.RS 5n +Parentheses enclose the quantity and the \fB\fR\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB1\fR\fR +.ad +.RS 5n +The sign string precedes the quantity and the \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB2\fR\fR +.ad +.RS 5n +The sign string precedes the quantity and the \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB3\fR\fR +.ad +.RS 5n +The sign string precedes the \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB4\fR\fR +.ad +.RS 5n +The sign string succeeds the \fBint_curr_symbol\fR. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fBint_n_sign_posn\fR\fR +.ad +.RS 22n +An integer set to a value indicating the positioning of the \fBnegative_sign\fR +for a negative monetary quantity formatted with the international format. +.RE + +.sp +.LP +The following table shows the result of various combinations: +.sp + +.sp +.TS +l l l l l l +l l l l l l . + \fBp_sep_by_space\fR + 2 1 0 +\fBp_cs_precedes\fR= 1 \fBp_sign_posn\fR= 0 \fB($1.25)\fR \fB($1.25)\fR \fB($1.25)\fR + \fBp_sign_posn\fR= 1 \fB+$1.25\fR \fB+$1.25\fR \fB+$1.25\fR + \fBp_sign_posn\fR= 2 \fB$1.25+\fR \fB$1.25+\fR \fB$1.25+\fR + \fBp_sign_posn\fR= 3 \fB+$1.25\fR \fB+$1.25\fR \fB+$1.25\fR + \fBp_sign_posn\fR= 4 \fB$+1.25\fR \fB$+1.25\fR \fB$+1.25\fR +\fBp_cs_precedes\fR= 0 \fBp_sign_posn\fR= 0 \fB(1.25 $)\fR \fB(1.25 $)\fR \fB(1.25$)\fR + \fBp_sign_posn\fR= 1 \fB+1.25 $\fR \fB+1.25 $\fR \fB+1.25$\fR + \fBp_sign_posn\fR= 2 \fB1.25$ +\fR \fB1.25 $+\fR \fB1.25$+\fR + \fBp_sign_posn\fR= 3 \fB1.25+ $\fR \fB1.25 +$\fR \fB1.25+$\fR + \fBp_sign_posn\fR= 4 \fB1.25$ +\fR \fB1.25 $+\fR \fB1.25$+\fR +.TE + +.sp +.LP +The monetary formatting definitions for the POSIX locale follow. The code +listing depicts the \fBlocaledef\fR(1) input, the table representing the same +information with the addition of \fBlocaleconv\fR(3C) and \fBnl_langinfo\fR(3C) +formats. All values are unspecified in the POSIX locale. +.sp +.in +2 +.nf +LC_MONETARY +# This is the POSIX locale definition for +# the LC_MONETARY category. +# +int_curr_symbol "" +currency_symbol "" +mon_decimal_point "" +mon_thousands_sep "" +mon_grouping -1 +positive_sign "" +negative_sign "" +int_frac_digits -1 +frac_digits -1 +p_cs_precedes -1 +p_sep_by_space -1 +n_cs_precedes -1 +n_sep_by_space -1 +p_sign_posn -1 +n_sign_posn -1 +int_p_cs_precedes -1 +int_p_sep_by_space -1 +int_n_cs_precedes -1 +int_n_sep_by_space -1 +int_p_sign_posn -1 +int_n_sign_posn -1 +# +END LC_MONETARY +.fi +.in -2 +.sp + +.sp +.LP +The entry \fBn/a\fR indicates that the value is not available in the POSIX +locale. +.SS "LC_NUMERIC" +The \fBLC_NUMERIC\fR category defines the rules and symbols that will be used +to format non-monetary numeric information. This information is available +through the \fBlocaleconv\fR(3C) function. +.sp +.LP +The following items are defined in this category of the locale. The item names +are the keywords recognized by the \fBlocaledef\fR utility when defining a +locale. They are also similar to the member names of the \fIlconv\fR structure +defined in <\fBlocale.h\fR>. The \fBlocaleconv()\fR function returns +\fB{CHAR_MAX}\fR for unspecified integer items and the empty string (\fB""\fR) +for unspecified or size zero string items. +.sp +.LP +In a locale definition file the operands are strings. For some keywords, the +strings only can contain integers. Keywords that are not provided, string +values set to the empty string (\fB""\fR), or integer keywords set to \fB-1\fR, +will be used to indicate that the value is not available in the locale. The +following keywords are recognized: +.sp +.ne 2 +.na +\fB\fBdecimal_point\fR\fR +.ad +.RS 17n +The operand is a string containing the symbol that is used as the decimal +delimiter (radix character) in numeric, non-monetary formatted quantities. This +keyword cannot be omitted and cannot be set to the empty string. In contexts +where standards limit the \fBdecimal_point\fR to a single byte, the result of +specifying a multi-byte operand is unspecified. +.RE + +.sp +.ne 2 +.na +\fB\fBthousands_sep\fR\fR +.ad +.RS 17n +The operand is a string containing the symbol that is used as a separator for +groups of digits to the left of the decimal delimiter in numeric, non-monetary +formatted monetary quantities. In contexts where standards limit the +\fBthousands_sep\fR to a single byte, the result of specifying a multi-byte +operand is unspecified. +.RE + +.sp +.ne 2 +.na +\fB\fBgrouping\fR\fR +.ad +.RS 17n +Define the size of each group of digits in formatted non-monetary quantities. +The operand is a sequence of integers separated by semicolons. Each integer +specifies the number of digits in each group, with the initial integer defining +the size of the group immediately preceding the decimal delimiter, and the +following integers defining the preceding groups. If the last integer is not +\fB\(mi1\fR, then the size of the previous group (if any) will be repeatedly +used for the remainder of the digits. If the last integer is \fB-1\fR, then no +further grouping will be performed. The non-monetary numeric formatting +definitions for the POSIX locale follow. The code listing depicts the +\fBlocaledef\fR input, the table representing the same information with the +addition of \fBlocaleconv\fR values, and \fBnl_langinfo\fR constants. +.sp +.in +2 +.nf +LC_NUMERIC +# This is the POSIX locale definition for +# the LC_NUMERIC category. +# +decimal_point "<period>" +thousands_sep "" +grouping -1 +# +END LC_NUMERIC +.fi +.in -2 +.sp + +.RE + +.sp + +.sp +.TS +l l l l l +l l l l l . + \fBPOSIX locale\fR \fBlanginfo\fR \fBlocaleconv()\fR \fBlocaledef\fR +\fBItem\fR \fBValue\fR \fBConstant\fR \fBValue\fR \fBValue\fR +_ +\fBdecimal_point\fR \fB"."\fR \fBRADIXCHAR\fR \fB"."\fR \fB\&.\fR +\fBthousands_sep\fR \fBn/a\fR \fBTHOUSEP\fR \fB""\fR \fB""\fR +\fBgrouping\fR \fBn/a\fR \fB-\fR \fB""\fR \fB\(mi1\fR +.TE + +.sp +.LP +The entry \fBn/a\fR indicates that the value is not available in the POSIX +locale. +.SS "LC_TIME" +The \fBLC_TIME\fR category defines the interpretation of the field descriptors +supported by \fBdate\fR(1) and affects the behavior of the \fBstrftime\fR(3C), +\fBwcsftime\fR(3C), \fBstrptime\fR(3C), and \fBnl_langinfo\fR(3C) functions. +Because the interfaces for C-language access and locale definition differ +significantly, they are described separately. For locale definition, the +following mandatory keywords are recognized: +.sp +.ne 2 +.na +\fB\fBabday\fR\fR +.ad +.RS 15n +Define the abbreviated weekday names, corresponding to the \fB%a\fR field +descriptor (conversion specification in the \fBstrftime()\fR, \fBwcsftime()\fR, +and \fBstrptime()\fR functions). The operand consists of seven +semicolon-separated strings, each surrounded by double-quotes. The first string +is the abbreviated name of the day corresponding to Sunday, the second the +abbreviated name of the day corresponding to Monday, and so on. +.RE + +.sp +.ne 2 +.na +\fB\fBday\fR\fR +.ad +.RS 15n +Define the full weekday names, corresponding to the \fB%A\fR field descriptor. +The operand consists of seven semicolon-separated strings, each surrounded by +double-quotes. The first string is the full name of the day corresponding to +Sunday, the second the full name of the day corresponding to Monday, and so on. +.RE + +.sp +.ne 2 +.na +\fB\fBabmon\fR\fR +.ad +.RS 15n +Define the abbreviated month names, corresponding to the \fB%b\fR field +descriptor. The operand consists of twelve semicolon-separated strings, each +surrounded by double-quotes. The first string is the abbreviated name of the +first month of the year (January), the second the abbreviated name of the +second month, and so on. +.RE + +.sp +.ne 2 +.na +\fB\fBmon\fR\fR +.ad +.RS 15n +Define the full month names, corresponding to the \fB%B\fR field descriptor. +The operand consists of twelve semicolon-separated strings, each surrounded by +double-quotes. The first string is the full name of the first month of the year +(January), the second the full name of the second month, and so on. +.RE + +.sp +.ne 2 +.na +\fB\fBd_t_fmt\fR\fR +.ad +.RS 15n +Define the appropriate date and time representation, corresponding to the +\fB%c\fR field descriptor. The operand consists of a string, and can contain +any combination of characters and field descriptors. In addition, the string +can contain the escape sequences \e\e, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, +\fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBdate_fmt\fR\fR +.ad +.RS 15n +Define the appropriate date and time representation, corresponding to the +\fB%C\fR field descriptor. The operand consists of a string, and can contain +any combination of characters and field descriptors. In addition, the string +can contain the escape sequences \fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, +\fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBd_fmt\fR\fR +.ad +.RS 15n +Define the appropriate date representation, corresponding to the \fB%x\fR field +descriptor. The operand consists of a string, and can contain any combination +of characters and field descriptors. In addition, the string can contain the +escape sequences \fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, +\fB\er\fR, \fB\et\fR, \fB\ev\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBt_fmt\fR\fR +.ad +.RS 15n +Define the appropriate time representation, corresponding to the \fB%X\fR field +descriptor. The operand consists of a string, and can contain any combination +of characters and field descriptors. In addition, the string can contain the +escape sequences \fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, +\fB\er\fR, \fB\et\fR, \fB\ev\fR\&. +.RE + +.sp +.ne 2 +.na +\fB\fBam_pm\fR\fR +.ad +.RS 15n +Define the appropriate representation of the \fIante meridiem\fR and \fIpost +meridiem\fR strings, corresponding to the \fB%p\fR field descriptor. The +operand consists of two strings, separated by a semicolon, each surrounded by +double-quotes. The first string represents the \fIante meridiem\fR designation, +the last string the \fIpost meridiem\fR designation. +.RE + +.sp +.ne 2 +.na +\fB\fBt_fmt_ampm\fR\fR +.ad +.RS 15n +Define the appropriate time representation in the 12-hour clock format with +\fBam_pm\fR, corresponding to the \fB%r\fR field descriptor. The operand +consists of a string and can contain any combination of characters and field +descriptors. If the string is empty, the 12-hour format is not supported in the +locale. +.RE + +.sp +.ne 2 +.na +\fB\fBera\fR\fR +.ad +.RS 15n +Define how years are counted and displayed for each era in a locale. The +operand consists of semicolon-separated strings. Each string is an era +description segment with the format: +.sp +\fIdirection\fR:\fIoffset\fR:\fIstart_date\fR:\fIend_date\fR:\fIera_name\fR:\fIera_format\fR +.sp +according to the definitions below. There can be as many era description +segments as are necessary to describe the different eras. +.sp +The start of an era might not be the earliest point For example, the Christian +era B.C. starts on the day before January 1, A.D. 1, and increases with earlier +time. +.sp +.ne 2 +.na +\fB\fIdirection\fR\fR +.ad +.RS 14n +Either a \fB+\fR or a \fB-\fR character. The \fB+\fR character indicates that +years closer to the \fIstart_date\fR have lower numbers than those closer to +the \fIend_date\fR. The \fB-\fR character indicates that years closer to the +\fIstart_date\fR have higher numbers than those closer to the \fIend_date\fR. +.RE + +.sp +.ne 2 +.na +\fB\fIoffset\fR\fR +.ad +.RS 14n +The number of the year closest to the \fIstart_date\fR in the era, +corresponding to the \fB%Eg\fR and \fB%Ey\fR field descriptors. +.RE + +.sp +.ne 2 +.na +\fB\fIstart_date\fR\fR +.ad +.RS 14n +A date in the form \fIyyyy\fR/\fImm\fR/\fBdd\fR, where \fIyyyy\fR, \fImm\fR, +and \fBdd\fR are the year, month and day numbers respectively of the start of +the era. Years prior to A.D. 1 are represented as negative numbers. +.RE + +.sp +.ne 2 +.na +\fB\fIend_date\fR\fR +.ad +.RS 14n +The ending date of the era, in the same format as the \fIstart_date\fR, or one +of the two special values -* or +*. The value -* indicates that the ending date +is the beginning of time. The value +* indicates that the ending date is the +end of time. +.RE + +.sp +.ne 2 +.na +\fB\fIera_name\fR\fR +.ad +.RS 14n +A string representing the name of the era, corresponding to the \fB%EC\fR field +descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fIera_format\fR\fR +.ad +.RS 14n +A string for formatting the year in the era, corresponding to the \fB%EG\fR and +\fB%EY\fR field descriptors. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fBera_d_fmt\fR\fR +.ad +.RS 15n +Define the format of the date in alternative era notation, corresponding to the +\fB%Ex\fR field descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBera_t_fmt\fR\fR +.ad +.RS 15n +Define the locale's appropriate alternative time format, corresponding to the +\fB%EX\fR field descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBera_d_t_fmt\fR\fR +.ad +.RS 15n +Define the locale's appropriate alternative date and time format, corresponding +to the \fB%Ec\fR field descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBalt_digits\fR\fR +.ad +.RS 15n +Define alternative symbols for digits, corresponding to the \fB%O\fR field +descriptor modifier. The operand consists of semicolon-separated strings, each +surrounded by double-quotes. The first string is the alternative symbol +corresponding with zero, the second string the symbol corresponding with one, +and so on. Up to 100 alternative symbol strings can be specified. The \fB%O\fR +modifier indicates that the string corresponding to the value specified via the +field descriptor will be used instead of the value. +.RE + +.SS "LC_TIME \fIC-language\fR Access" +The following information can be accessed. These correspond to constants +defined in <\fBlanginfo.h\fR> and used as arguments to the +\fBnl_langinfo\fR(3C) function. +.sp +.ne 2 +.na +\fB\fBABDAY_\fIx\fR\fR\fR +.ad +.RS 15n +The abbreviated weekday names (for example Sun), where \fIx\fR is a number from +1 to 7. +.RE + +.sp +.ne 2 +.na +\fB\fBDAY_\fIx\fR\fR\fR +.ad +.RS 15n +The full weekday names (for example Sunday), where \fIx\fR is a number from 1 +to 7. +.RE + +.sp +.ne 2 +.na +\fB\fBABMON_\fIx\fR\fR\fR +.ad +.RS 15n +The abbreviated month names (for example Jan), where \fIx\fR is a number from 1 +to 12. +.RE + +.sp +.ne 2 +.na +\fB\fBMON_\fIx\fR\fR\fR +.ad +.RS 15n +The full month names (for example January), where \fIx\fR is a number from 1 to +12. +.RE + +.sp +.ne 2 +.na +\fB\fBD_T_FMT\fR\fR +.ad +.RS 15n +The appropriate date and time representation. +.RE + +.sp +.ne 2 +.na +\fB\fBD_FMT\fR\fR +.ad +.RS 15n +The appropriate date representation. +.RE + +.sp +.ne 2 +.na +\fB\fBT_FMT\fR\fR +.ad +.RS 15n +The appropriate time representation. +.RE + +.sp +.ne 2 +.na +\fB\fBAM_STR\fR\fR +.ad +.RS 15n +The appropriate ante-meridiem affix. +.RE + +.sp +.ne 2 +.na +\fB\fBPM_STR\fR\fR +.ad +.RS 15n +The appropriate post-meridiem affix. +.RE + +.sp +.ne 2 +.na +\fB\fBT_FMT_AMPM\fR\fR +.ad +.RS 15n +The appropriate time representation in the 12-hour clock format with +\fBAM_STR\fR and \fBPM_STR.\fR +.RE + +.sp +.ne 2 +.na +\fB\fBERA\fR\fR +.ad +.RS 15n +The era description segments, which describe how years are counted and +displayed for each era in a locale. Each era description segment has the +format: +.sp +.in +2 +.nf +\fIdirection\fR:\fIoffset\fR:\fIstart_date\fR:\fIend_date\fR:\fIera_name\fR:\fIera_format\fR +.fi +.in -2 +.sp + +according to the definitions below. There will be as many era description +segments as are necessary to describe the different eras. Era description +segments are separated by semicolons. +.sp +The start of an era might not be the earliest point For example, the Christian +era B.C. starts on the day before January 1, A.D. 1, and increases with earlier +time. +.sp +.ne 2 +.na +\fB\fIdirection\fR\fR +.ad +.RS 14n +Either a + or a - character. The + character indicates that years closer to the +\fIstart_date\fR have lower numbers than those closer to the \fIend_date\fR. +The - character indicates that years closer to the \fIstart_date\fR have higher +numbers than those closer to the \fIend_date\fR. +.RE + +.sp +.ne 2 +.na +\fB\fIoffset\fR\fR +.ad +.RS 14n +The number of the year closest to the start_date in the era. +.RE + +.sp +.ne 2 +.na +\fB\fIstart_date\fR\fR +.ad +.RS 14n +A date in the form \fIyyyy\fR/\fImm\fR/\fIdd\fR, where \fIyyyy\fR, \fImm\fR, +and \fBdd\fR are the year, month and day numbers respectively of the start of +the era. Years prior to AD 1 are represented as negative numbers. +.RE + +.sp +.ne 2 +.na +\fB\fIend_date\fR\fR +.ad +.RS 14n +The ending date of the era, in the same format as the \fIstart_date\fR, or one +of the two special values, \fB-*\fR or \fB+*\fR. The value \fB-*\fR indicates +that the ending date is the beginning of time. The value \fB+*\fR indicates +that the ending date is the end of time. +.RE + +.sp +.ne 2 +.na +\fB\fIera_name\fR\fR +.ad +.RS 14n +The era, corresponding to the \fB%EC\fR conversion specification. +.RE + +.sp +.ne 2 +.na +\fB\fIera_format\fR\fR +.ad +.RS 14n +The format of the year in the era, corresponding to the \fB%EY\fR and \fB%EY\fR +conversion specifications. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fBERA_D_FMT\fR\fR +.ad +.RS 15n +The era date format. +.RE + +.sp +.ne 2 +.na +\fB\fBERA_T_FMT\fR\fR +.ad +.RS 15n +The locale's appropriate alternative time format, corresponding to the +\fB%EX\fR field descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBERA_D_T_FMT\fR\fR +.ad +.RS 15n +The locale's appropriate alternative date and time format, corresponding to the +\fB%Ec\fR field descriptor. +.RE + +.sp +.ne 2 +.na +\fB\fBALT_DIGITS\fR\fR +.ad +.RS 15n +The alternative symbols for digits, corresponding to the \fB%O\fR conversion +specification modifier. The value consists of semicolon-separated symbols. The +first is the alternative symbol corresponding to zero, the second is the symbol +corresponding to one, and so on. Up to 100 alternative symbols may be +specified. The following table displays the correspondence between the items +described above and the conversion specifiers used by \fBdate\fR(1) and the +\fBstrftime\fR(3C), \fBwcsftime\fR(3C), and \fBstrptime\fR(3C) functions. +.RE + +.sp + +.sp +.TS +box; +c | c | c +c | c | c . +\fBlocaledef\fR \fBlanginfo\fR \fBConversion\fR +\fBKeyword\fR \fBConstant\fR \fBSpecifier\fR +_ +\fBabday\fR \fBABDAY_\fR\fIx\fR \fB%a\fR +\fBday\fR \fBDAY_\fR\fIx\fR \fB%A\fR +\fBabmon\fR \fBABMON_\fR\fIx\fR \fB%b\fR +\fBmon\fR \fBMON\fR \fB%B\fR +\fBd_t_fmt\fR \fBD_T_FMT\fR \fB%c\fR +\fBdate_fmt\fR \fBDATE_FMT\fR \fB%C\fR +\fBd_fmt\fR \fBD_FMT\fR \fB%x\fR +\fBt_fmt\fR \fBT_FMT\fR \fB%X\fR +\fBam_pm\fR \fBAM_STR\fR \fB%p\fR +\fBam_pm\fR \fBPM_STR\fR \fB%p\fR +\fBt_fmt_ampm\fR \fBT_FMT_AMPM\fR \fB%r\fR +\fBera\fR \fBERA\fR \fB%EC, %Eg,\fR + \fB%EG, %Ey, %EY\fR +\fBera_d_fmt\fR \fBERA_D_FMT\fR \fB%Ex\fR +\fBera_t_fmt\fR \fBERA_T_FMT\fR \fB%EX\fR +\fBera_d_t_fmt\fR \fBERA_D_T_FMT\fR \fB%Ec\fR +\fBalt_digits\fR \fBALT_DIGITS\fR \fB%O\fR +.TE + +.SS "LC_TIME \fIGeneral\fR Information" +Although certain of the field descriptors in the POSIX locale (such as the name +of the month) are shown with initial capital letters, this need not be the case +in other locales. Programs using these fields may need to adjust the +capitalization if the output is going to be used at the beginning of a +sentence. +.sp +.LP +The \fBLC_TIME\fR descriptions of \fBabday\fR, \fBday\fR, \fBmon\fR, and +\fBabmon\fR imply a Gregorian style calendar (7-day weeks, 12-month years, leap +years, and so forth). Formatting time strings for other types of calendars is +outside the scope of this document set. +.sp +.LP +As specified under \fBdate\fR in \fBLocale Definition\fR and +\fBstrftime\fR(3C), the field descriptors corresponding to the optional +keywords consist of a modifier followed by a traditional field descriptor (for +instance \fB%Ex\fR). If the optional keywords are not supported by the +implementation or are unspecified for the current locale, these field +descriptors are treated as the traditional field descriptor. For instance, +assume the following keywords: +.sp +.in +2 +.nf +alt_digits "0th" ; "1st" ; "2nd" ; "3rd" ; "4th" ; "5th" ; \e +"6th" ; "7th" ; "8th" ; "9th" ; "10th"> +d_fmt "The %Od day of %B in %Y" +.fi +.in -2 +.sp + +.sp +.LP +On 7/4/1776, the \fB%x\fR field descriptor would result in "The 4th day of July +in 1776" while 7/14/1789 would come out as "The 14 day of July in 1789" The +above example is for illustrative purposes only. The \fB%O\fR modifier is +primarily intended to provide for Kanji or Hindi digits in \fBdate\fR formats. +.SS "LC_MESSAGES" +The \fBLC_MESSAGES\fR category defines the format and values for affirmative +and negative responses. +.sp +.LP +The following keywords are recognized as part of the locale definition file. +The \fBnl_langinfo\fR(3C) function accepts upper-case versions of the first +four keywords. +.sp +.ne 2 +.na +\fB\fByesexpr\fR\fR +.ad +.RS 11n +The operand consists of an extended regular expression (see \fBregex\fR(7)) +that describes the acceptable affirmative response to a question expecting an +affirmative or negative response. +.RE + +.sp +.ne 2 +.na +\fB\fBnoexpr\fR\fR +.ad +.RS 11n +The operand consists of an extended regular expression that describes the +acceptable negative response to a question expecting an affirmative or negative +response. +.RE + +.sp +.ne 2 +.na +\fB\fByesstr\fR\fR +.ad +.RS 11n +The operand consists of a fixed string (not a regular expression) that can be +used by an application for composition of a message that lists an acceptable +affirmative response, such as in a prompt. +.RE + +.sp +.ne 2 +.na +\fB\fBnostr\fR\fR +.ad +.RS 11n +The operand consists of a fixed string that can be used by an application for +composition of a message that lists an acceptable negative response. The format +and values for affirmative and negative responses of the POSIX locale follow; +the code listing depicting the \fBlocaledef\fR input, the table representing +the same information with the addition of \fBnl_langinfo()\fR constants. +.sp +.in +2 +.nf +LC_MESSAGES +# This is the POSIX locale definition for +# the LC_MESSAGES category. +# +yesexpr "<circumflex><left-square-bracket><y><Y>\e + <right-square-bracket>" +# +noexpr "<circumflex><left-square-bracket><n><N>\e + <right-square-bracket>" +# +yesstr "yes" +nostr "no" +END LC_MESSAGES +.fi +.in -2 +.sp + +.RE + +.sp + +.sp +.TS +box; +l | l | l +l | l | l . +\fBlocaledef Keyword\fR \fBlanginfo Constant\fR \fBPOSIX Locale Value\fR +\fByesexpr\fR \fBYESEXPR\fR \fB"^[yY]"\fR +\fBnoexpr\fR \fBNOEXPR\fR \fB"^[nN]"\fR +\fByesstr\fR \fBYESSTR\fR \fB"yes"\fR +\fBnostr\fR \fBNOSTR\fR \fB"no"\fR +.TE + +.sp +.LP +In an application conforming to the SUSv3 standard, the information on +\fByesstr\fR and \fBnostr\fR is not available. +.SH SEE ALSO +.BR date (1), +.BR locale (1), +.BR localedef (1), +.BR sort (1), +.BR tr (1), +.BR uniq (1), +.BR localeconv (3C), +.BR nl_langinfo (3C), +.BR setlocale (3C), +.BR strcoll (3C), +.BR strftime (3C), +.BR strptime (3C), +.BR strxfrm (3C), +.BR wcscoll (3C), +.BR wcsftime (3C), +.BR wcsxfrm (3C), +.BR wctype (3C), +.BR attributes (7), +.BR charmap (7), +.BR extensions (7), +.BR regex (7) diff --git a/usr/src/man/man7/man.7 b/usr/src/man/man7/man.7 new file mode 100644 index 0000000000..f68f37511c --- /dev/null +++ b/usr/src/man/man7/man.7 @@ -0,0 +1,265 @@ +.\" Copyright 2015 Nexenta Systems, Inc. All rights reserved. +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" Copyright (c) 1995, Sun Microsystems, 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] +.Dd "Feb 18, 2015" +.Dt MAN 7 +.Os +.Sh NAME +.Nm man +.Nd macros to format Reference Manual pages +.Sh SYNOPSIS +.Nm mandoc +.Fl T Ar man +.Ar +.Nm nroff +.Fl man +.Ar +.Nm troff +.Fl man +.Ar +.Sh DESCRIPTION +These macros are used to lay out the reference pages in this manual. +Note: if +.Ar file +contains format input for a preprocessor, the commands shown +above must be piped through the appropriate preprocessor. +This is handled automatically by the +.Xr man 1 +command. +See the +.Sx Conventions +section. +.Lp +Any text argument +.Ar t +may be zero to six words. +Quotes may be used to include SPACE characters in a +.Qq word . +If +.Ar text +is empty, the special +treatment is applied to the next input line with text to be printed. +In this way +.Nm \&.I +may be used to italicize a whole line, or +.Nm \&.SB +may be used to make small bold letters. +.Lp +A prevailing indent distance is remembered between successive indented +paragraphs, and is reset to default value upon reaching a non-indented +paragraph. +Default units for indents +.Nm i +are ens. +.Lp +Type font and size are reset to default values before each paragraph, and after +processing font and size setting macros. +.Pp +These strings are predefined by +.Nm -man : +.Bl -tag -width Ds +.It Nm \e*R +.Sq \(rg , +.Sq (Reg) +in +.Nm nroff . +.It Nm \e*S +Change to default type size. +.El +.Sh "Requests" +* n.t.l. = next text line; p.i. = prevailing indent +.Bl -column ".TH n s d f m" "Cause " "t=n.t.l.*" "Explanation " -offset Ds +.It Sy Request Sy Cause Sy "If No" Sy Explanation +.It "" Sy Break Sy "Argument" "" +.It Nm \&.B Ar "t" no Ar t Ns =n.t.l.* Text is in bold font. +.It Nm \&.BI Ar t no Ar t Ns =n.t.l. Join words, alternating bold and italic. +.It Nm \&.BR Ar t no Ar t Ns =n.t.l. Join words, alternating bold and roman. +.It Nm \&.DT no Li \&.5i 1i... Restore default tabs. +.It Nm \&.HP Ar i yes Ar i Ns =p.i.* "Begin paragraph with hanging indent. Set prevailing indent to" Ar i . +.It Nm \&.I Ar t no Ar t Ns =n.t.l. Text is italic. +.It Nm \&.IB Ar t no Ar t Ns =n.t.l. Join words, altenrating italic and bold. +.It Nm \&.IP Ar x Ar i yes Ar x Ns ="" Same as +.Nm \&.TP +with tag +.Ar x . +.It Nm \&.IR Ar t no Ar t Ns =n.t.l. Join words, alternating italic and roman. +.It Nm \&.IX Ar t no - Index macro, not used (obsolete). +.It Nm \&.LP yes - Begin left-aligned paragraph. Set prevailing indent to .5i. +.It Nm \&.P yes - Same as +.Nm \&.LP . +.It Nm \&.PD Ar d no Ar d Ns =.4v Set vertical distance between paragraphs. +.It Nm \&.PP yes - Same as +.Nm \&.LP . +.It Nm \&.RE yes - End of relative indent. Restores prevailing indent. +.It Nm \&.RB Ar t no Ar t Ns =n.t.l. Join words, alternating roman and bold. +.It Nm \&.RI Ar t no Ar t Ns =n.t.l. Join words, alternating roman and italic. +.It Nm \&.RS Ar i yes Ar i Ns =p.i. Start relative indent, increase indent by Ar i . +Sets prevailing indent to .5i for nested indents. +.It Nm \&.SB Ar t no - Reduce size of text by 1 point, make text bold. +.It Nm \&.SH Ar t yes - Section Heading. +.It Nm \&.SM Ar t no Ar t Ns =n.t.l. Reduce size of text by 1 point. +.It Nm \&.SS Ar t yes Ar t Ns =n.t.l. Section Subheading. +.It Nm \&.TH Ar n s d f m yes - Begin reference page Ar n , No of section Ar s ; Ar d No is the date of the most recent change. If present, Ar f No is the left page footer; Ar m No is the main page (center) header. Sets prevailing indent and tabs to .5i. +.It Nm \&.TP Ar i yes Ar i Ns =p.i. Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to +.Ar i . +.It Nm \&.TX Ar t p no - Resolve the title abbreviation Ar t ; No join to punctuation mark (or text) Ar p . +.El +.Ss "Conventions" +When formatting a manual page, +.Nm +examines the first line to determine +whether it requires special processing. +For example a first line consisting of: +.Lp +.Dl \&'\e" t +.Lp +indicates that the manual page must be run through the +.Xr tbl 1 +preprocessor. +.Lp +A typical manual page for a command or function is laid out as follows: +.Bl -tag -width ".SH RETURN VALUES" +. +.It Nm \&.TH Ar title Op "1-9" +. +The name of the command or function, which serves as the title of the manual +page. +This is followed by the number of the section in which it appears. +. +.It Nm \&.SH NAME +. +The name, or list of names, by which the command is called, followed by a dash +and then a one-line summary of the action performed. +All in roman font, this section contains no +.Xr troff 1 +commands or escapes, and no macro requests. +It is used to generate the database used by the +.Xr whatis 1 +command. +. +.It Nm \&.SH SYNOPSIS +.Bl -tag -width "Functions:" +.It Sy Commands: +The syntax of the command and its arguments, as typed on the command line. +When in boldface, a word must be typed exactly as printed. +When in italics, a word can be replaced with an argument that you supply. +References to bold or italicized items are not capitalized in other sections, +even when they begin a sentence. +.Lp +Syntactic symbols appear in roman face: +.Bl -tag -width " " +.It Op " " +An argument, when surrounded by brackets is optional. +.It | +Arguments separated by a vertical bar are exclusive. +You can supply only one item from such a list. +.It \&.\|.\|. +Arguments followed by an ellipsis can be repeated. +When an ellipsis follows a bracketed set, the expression within the brackets can +be repeated. +.El +.It Sy Functions: +If required, the data declaration, or +.Li #include +directive, is shown first, +followed by the function declaration. +Otherwise, the function declaration is shown. +.El +. +.It Nm \&.SH DESCRIPTION +. +A narrative overview of the command or function's external behavior. +This includes how it interacts with files or data, and how it handles the +standard input, standard output and standard error. +Internals and implementation details are normally omitted. +This section attempts to provide a succinct overview in answer to the question, +"what does it do?" +.Lp +Literal text from the synopsis appears in constant width, as do literal +filenames and references to items that appear elsewhere in the reference +manuals. +Arguments are italicized. +.Lp +If a command interprets either subcommands or an input grammar, its command +interface or input grammar is normally described in a +.Nm USAGE +section, which follows the +.Nm OPTIONS +section. +The +.Nm DESCRIPTION +section only +describes the behavior of the command itself, not that of subcommands. +. +.It Nm \&.SH OPTIONS +. +The list of options along with a description of how each affects the command's +operation. +. +.It Nm \&.SH RETURN VALUES +. +A list of the values the library routine will return to the calling program +and the conditions that cause these values to be returned. +. +.It Nm \&.SH EXIT STATUS +. +A list of the values the utility will return to the calling program or shell, +and the conditions that cause these values to be returned. +. +.It Nm \&.SH FILES +. +A list of files associated with the command or function. +. +.It Nm \&.SH SEE ALSO +. +A comma-separated list of related manual pages, followed by references to other +published materials. +. +.It Nm \&.SH DIAGNOSTICS +. +A list of diagnostic messages and an explanation of each. +. +.It Nm \&.SH BUGS +. +A description of limitations, known defects, and possible problems associated +with the command or function. +.El +.Sh FILES +.Pa /usr/share/man/whatis +.Sh NOTES +The +.Nm +package should not be used for new documentation. +The +.Xr mdoc 7 , +package is preferred, as it uses semantic markup rather than physical markup. +.Sh CODE SET INDEPENDENCE +When processed with +.Xr mandoc 1 , +this package is Code Set Independent. +However, when processed with legacy tools such as +.Xr nroff 1 +and +.Xr troff 1 , +the use of multi-byte characters may not be supported. +.Sh INTERFACE STABILITY +.Sy Obsolete Committed . +The +.Xr mdoc 7 +package should be used instead. +.Sh SEE ALSO +.Xr eqn 1 , +.Xr man 1 , +.Xr mandoc 1 , +.Xr nroff 1 , +.Xr tbl 1 , +.Xr troff 1 , +.Xr whatis 1 , +.Xr mdoc 7 +.Rs +.%A Dale Dougherty and Tim O'Reilly +.%B Unix Text Processing +.Re diff --git a/usr/src/man/man7/mandoc_char.7 b/usr/src/man/man7/mandoc_char.7 new file mode 100644 index 0000000000..f8d78e3099 --- /dev/null +++ b/usr/src/man/man7/mandoc_char.7 @@ -0,0 +1,829 @@ +.\" $Id: mandoc_char.7,v 1.78 2020/10/31 11:45:16 schwarze Exp $ +.\" +.\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org> +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2011,2013,2015,2017-2020 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: October 31 2020 $ +.Dt MANDOC_CHAR 7 +.Os +.Sh NAME +.Nm mandoc_char +.Nd mandoc special characters +.Sh DESCRIPTION +This page documents the +.Xr mandoc_roff 7 +escape sequences accepted by +.Xr mandoc 1 +to represent special characters in +.Xr mdoc 7 +and +.Xr man 7 +documents. +.Pp +The rendering depends on the +.Xr mandoc 1 +output mode; it can be inspected by calling +.Xr man 1 +on the +.Nm +manual page with different +.Fl T +arguments. +In ASCII output, the rendering of some characters may be hard +to interpret for the reader. +Many are rendered as descriptive strings like +.Qq <integral> , +.Qq <degree> , +or +.Qq <Gamma> , +which may look ugly, and many are replaced by similar ASCII characters. +In particular, accented characters are usually shown without the accent. +For that reason, try to avoid using any of the special characters +documented here except those discussed in the +.Sx DESCRIPTION , +unless they are essential for explaining the subject matter at hand, +for example when documenting complicated mathematical functions. +.Pp +In particular, in English manual pages, do not use special-character +escape sequences to represent national language characters in author +names; instead, provide ASCII transcriptions of the names. +.Ss Dashes and Hyphens +In typography there are different types of dashes of various width: +the hyphen (\(hy), +the en-dash (\(en), +the em-dash (\(em), +and the mathematical minus sign (\(mi). +.Pp +Hyphens are used for adjectives; +to separate the two parts of a compound word; +or to separate a word across two successive lines of text. +The hyphen does not need to be escaped: +.Bd -unfilled -offset indent +blue-eyed +lorry-driver +.Ed +.Pp +The en-dash is used to separate the two elements of a range, +or can be used the same way as an em-dash. +It should be written as +.Sq \e(en : +.Bd -unfilled -offset indent +pp. 95\e(en97. +Go away \e(en or else! +.Ed +.Pp +The em-dash can be used to show an interruption +or can be used the same way as colons, semi-colons, or parentheses. +It should be written as +.Sq \e(em : +.Bd -unfilled -offset indent +Three things \e(em apples, oranges, and bananas. +This is not that \e(em rather, this is that. +.Ed +.Pp +In +.Xr mandoc_roff 7 +documents, the minus sign is normally written as +.Sq \e- . +In manual pages, some style guides recommend to also use +.Sq \e- +if an ASCII 0x2d +.Dq hyphen-minus +output glyph that can be copied and pasted is desired in output modes +supporting it, for example in +.Fl T Cm utf8 +and +.Fl T Cm html . +But currently, no practically relevant manual page formatter requires +that subtlety, so in manual pages, it is sufficient to write plain +.Sq - +to represent hyphen, minus, and hyphen-minus. +.Pp +If a word on a text input line contains a hyphen, a formatter may decide +to insert an output line break after the hyphen if that helps filling +the current output line, but the whole word would overflow the line. +If it is important that the word is not broken across lines in this +way, a zero-width space +.Pq Sq \e& +can be inserted before or after the hyphen. +While +.Xr mandoc 1 +never breaks the output line after hyphens adjacent to a zero-width +space, after any of the other dash- or hyphen-like characters +represented by escape sequences, or after hyphens inside words in +macro arguments, other software may not respect these rules and may +break the line even in such cases. +.Pp +Some +.Xr mandoc_roff 7 +implementations contains dictionaries allowing to break the line +at syllable boundaries even inside words that contain no hyphens. +Such automatic hyphenation is not supported by +.Xr mandoc 1 , +which only breaks the line at whitespace, and inside words only +after existing hyphens. +.Ss Spaces +To separate words in normal text, for indenting and alignment +in literal context, and when none of the following special cases apply, +just use the normal space character +.Pq Sq \ . +.Pp +When filling text, output lines may be broken between words, i.e. at space +characters. +To prevent a line break between two particular words, +use the unpaddable non-breaking space escape sequence +.Pq Sq \e\ \& +instead of the normal space character. +For example, the input string +.Dq number\e\ 1 +will be kept together as +.Dq number\ 1 +on the same output line. +.Pp +On request and macro lines, the normal space character serves as an +argument delimiter. +To include whitespace into arguments, quoting is usually the best choice; +see the MACRO SYNTAX section in +.Xr mandoc_roff 7 . +In some cases, using the non-breaking space escape sequence +.Pq Sq \e\ \& +may be preferable. +.Pp +To escape macro names and to protect whitespace at the end +of input lines, the zero-width space +.Pq Sq \e& +is often useful. +For example, in +.Xr mdoc 7 , +a normal space character can be displayed in single quotes in either +of the following ways: +.Pp +.Dl .Sq \(dq \(dq +.Dl .Sq \e \e& +.Ss Quotes +On request and macro lines, the double-quote character +.Pq Sq \(dq +is handled specially to allow quoting. +One way to prevent this special handling is by using the +.Sq \e(dq +escape sequence. +.Pp +Note that on text lines, literal double-quote characters can be used +verbatim. +All other quote-like characters can be used verbatim as well, +even on request and macro lines. +.Ss Accents +In output modes supporting such special output characters, for example +.Fl T Cm pdf , +and sometimes less consistently in +.Fl T Cm utf8 , +some +.Xr mandoc_roff 7 +formatters convert the following ASCII input characters to the +following Unicode special output characters: +.Bl -column x(ga U+2018 -offset indent +.It \(ga Ta U+2018 Ta left single quotation mark +.It \(aq Ta U+2019 Ta right single quotation mark +.It \(ti Ta U+02DC Ta small tilde +.It \(ha Ta U+02C6 Ta modifier letter circumflex +.El +.Pp +In prose, this automatic substitution is often desirable; +but when these characters have to be displayed as plain ASCII +characters, for example in source code samples, they require +escaping to render as follows: +.Bl -column x(ga U+2018 -offset indent +.It \e(ga Ta U+0060 Ta grave accent +.It \e(aq Ta U+0027 Ta apostrophe +.It \e(ti Ta U+007E Ta tilde +.It \e(ha Ta U+005E Ta circumflex accent +.El +.Ss Periods +The period +.Pq Sq \&. +is handled specially at the beginning of an input line, +where it introduces a +.Xr mandoc_roff 7 +request or a macro, and when appearing alone as a macro argument in +.Xr mdoc 7 . +In such situations, prepend a zero-width space +.Pq Sq \e&. +to make it behave like normal text. +.Pp +Do not use the +.Sq \e. +escape sequence. +It does not prevent special handling of the period. +.Ss Backslashes +To include a literal backslash +.Pq Sq \e +into the output, use the +.Pq Sq \ee +escape sequence. +.Pp +Note that doubling it +.Pq Sq \e\e +is not the right way to output a backslash. +Because +.Xr mandoc 1 +does not implement full +.Xr mandoc_roff 7 +functionality, it may work with +.Xr mandoc 1 , +but it may have weird effects on complete +.Xr mandoc_roff 7 +implementations. +.Sh SPECIAL CHARACTERS +Special characters are encoded as +.Sq \eX +.Pq for a one-character escape , +.Sq \e(XX +.Pq two-character , +and +.Sq \e[N] +.Pq N-character . +For details, see the +.Em Special Characters +subsection of the +.Xr mandoc_roff 7 +manual. +.Pp +Spaces, non-breaking unless stated otherwise: +.Bl -column "Input" "Description" -offset indent -compact +.It Em Input Ta Em Description +.It Sq \e\ \& Ta unpaddable space +.It \e\(ti Ta paddable space +.It \e0 Ta digit-width space +.It \e| Ta one-sixth \e(em narrow space, zero width in nroff mode +.It \e^ Ta one-twelfth \e(em half-narrow space, zero width in nroff +.It \e& Ta zero-width space +.It \e) Ta zero-width space transparent to end-of-sentence detection +.It \e% Ta zero-width space allowing hyphenation +.It \e: Ta zero-width space allowing line break +.El +.Pp +Lines: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ba Ta \(ba Ta bar +.It \e(br Ta \(br Ta box rule +.It \e(ul Ta \(ul Ta underscore +.It \e(ru Ta \(ru Ta underscore (width 0.5m) +.It \e(rn Ta \(rn Ta overline +.It \e(bb Ta \(bb Ta broken bar +.It \e(sl Ta \(sl Ta forward slash +.It \e(rs Ta \(rs Ta backward slash +.El +.Pp +Text markers: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ci Ta \(ci Ta circle +.It \e(bu Ta \(bu Ta bullet +.It \e(dd Ta \(dd Ta double dagger +.It \e(dg Ta \(dg Ta dagger +.It \e(lz Ta \(lz Ta lozenge +.It \e(sq Ta \(sq Ta white square +.It \e(ps Ta \(ps Ta paragraph +.It \e(sc Ta \(sc Ta section +.It \e(lh Ta \(lh Ta left hand +.It \e(rh Ta \(rh Ta right hand +.It \e(at Ta \(at Ta at +.It \e(sh Ta \(sh Ta hash (pound) +.It \e(CR Ta \(CR Ta carriage return +.It \e(OK Ta \(OK Ta check mark +.It \e(CL Ta \(CL Ta club suit +.It \e(SP Ta \(SP Ta spade suit +.It \e(HE Ta \(HE Ta heart suit +.It \e(DI Ta \(DI Ta diamond suit +.El +.Pp +Legal symbols: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(co Ta \(co Ta copyright +.It \e(rg Ta \(rg Ta registered +.It \e(tm Ta \(tm Ta trademarked +.El +.Pp +Punctuation: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(em Ta \(em Ta em-dash +.It \e(en Ta \(en Ta en-dash +.It \e(hy Ta \(hy Ta hyphen +.It \ee Ta \e Ta back-slash +.It \e. Ta \. Ta period +.It \e(r! Ta \(r! Ta upside-down exclamation +.It \e(r? Ta \(r? Ta upside-down question +.El +.Pp +Quotes: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Bq Ta \(Bq Ta right low double-quote +.It \e(bq Ta \(bq Ta right low single-quote +.It \e(lq Ta \(lq Ta left double-quote +.It \e(rq Ta \(rq Ta right double-quote +.It \e(oq Ta \(oq Ta left single-quote +.It \e(cq Ta \(cq Ta right single-quote +.It \e(aq Ta \(aq Ta apostrophe quote (ASCII character) +.It \e(dq Ta \(dq Ta double quote (ASCII character) +.It \e(Fo Ta \(Fo Ta left guillemet +.It \e(Fc Ta \(Fc Ta right guillemet +.It \e(fo Ta \(fo Ta left single guillemet +.It \e(fc Ta \(fc Ta right single guillemet +.El +.Pp +Brackets: +.Bl -column "xxbracketrightbtx" Rendered Description -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(lB Ta \(lB Ta left bracket +.It \e(rB Ta \(rB Ta right bracket +.It \e(lC Ta \(lC Ta left brace +.It \e(rC Ta \(rC Ta right brace +.It \e(la Ta \(la Ta left angle +.It \e(ra Ta \(ra Ta right angle +.It \e(bv Ta \(bv Ta brace extension (special font) +.It \e[braceex] Ta \[braceex] Ta brace extension +.It \e[bracketlefttp] Ta \[bracketlefttp] Ta top-left hooked bracket +.It \e[bracketleftbt] Ta \[bracketleftbt] Ta bottom-left hooked bracket +.It \e[bracketleftex] Ta \[bracketleftex] Ta left hooked bracket extension +.It \e[bracketrighttp] Ta \[bracketrighttp] Ta top-right hooked bracket +.It \e[bracketrightbt] Ta \[bracketrightbt] Ta bottom-right hooked bracket +.It \e[bracketrightex] Ta \[bracketrightex] Ta right hooked bracket extension +.It \e(lt Ta \(lt Ta top-left hooked brace +.It \e[bracelefttp] Ta \[bracelefttp] Ta top-left hooked brace +.It \e(lk Ta \(lk Ta mid-left hooked brace +.It \e[braceleftmid] Ta \[braceleftmid] Ta mid-left hooked brace +.It \e(lb Ta \(lb Ta bottom-left hooked brace +.It \e[braceleftbt] Ta \[braceleftbt] Ta bottom-left hooked brace +.It \e[braceleftex] Ta \[braceleftex] Ta left hooked brace extension +.It \e(rt Ta \(rt Ta top-left hooked brace +.It \e[bracerighttp] Ta \[bracerighttp] Ta top-right hooked brace +.It \e(rk Ta \(rk Ta mid-right hooked brace +.It \e[bracerightmid] Ta \[bracerightmid] Ta mid-right hooked brace +.It \e(rb Ta \(rb Ta bottom-right hooked brace +.It \e[bracerightbt] Ta \[bracerightbt] Ta bottom-right hooked brace +.It \e[bracerightex] Ta \[bracerightex] Ta right hooked brace extension +.It \e[parenlefttp] Ta \[parenlefttp] Ta top-left hooked parenthesis +.It \e[parenleftbt] Ta \[parenleftbt] Ta bottom-left hooked parenthesis +.It \e[parenleftex] Ta \[parenleftex] Ta left hooked parenthesis extension +.It \e[parenrighttp] Ta \[parenrighttp] Ta top-right hooked parenthesis +.It \e[parenrightbt] Ta \[parenrightbt] Ta bottom-right hooked parenthesis +.It \e[parenrightex] Ta \[parenrightex] Ta right hooked parenthesis extension +.El +.Pp +Arrows: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(<- Ta \(<- Ta left arrow +.It \e(-> Ta \(-> Ta right arrow +.It \e(<> Ta \(<> Ta left-right arrow +.It \e(da Ta \(da Ta down arrow +.It \e(ua Ta \(ua Ta up arrow +.It \e(va Ta \(va Ta up-down arrow +.It \e(lA Ta \(lA Ta left double-arrow +.It \e(rA Ta \(rA Ta right double-arrow +.It \e(hA Ta \(hA Ta left-right double-arrow +.It \e(uA Ta \(uA Ta up double-arrow +.It \e(dA Ta \(dA Ta down double-arrow +.It \e(vA Ta \(vA Ta up-down double-arrow +.It \e(an Ta \(an Ta horizontal arrow extension +.El +.Pp +Logical: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(AN Ta \(AN Ta logical and +.It \e(OR Ta \(OR Ta logical or +.It \e[tno] Ta \[tno] Ta logical not (text font) +.It \e(no Ta \(no Ta logical not (special font) +.It \e(te Ta \(te Ta existential quantifier +.It \e(fa Ta \(fa Ta universal quantifier +.It \e(st Ta \(st Ta such that +.It \e(tf Ta \(tf Ta therefore +.It \e(3d Ta \(3d Ta therefore +.It \e(or Ta \(or Ta bitwise or +.El +.Pp +Mathematical: +.Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e- Ta \- Ta minus (text font) +.It \e(mi Ta \(mi Ta minus (special font) +.It + Ta + Ta plus (text font) +.It \e(pl Ta \(pl Ta plus (special font) +.It \e(-+ Ta \(-+ Ta minus-plus +.It \e[t+-] Ta \[t+-] Ta plus-minus (text font) +.It \e(+- Ta \(+- Ta plus-minus (special font) +.It \e(pc Ta \(pc Ta center-dot +.It \e[tmu] Ta \[tmu] Ta multiply (text font) +.It \e(mu Ta \(mu Ta multiply (special font) +.It \e(c* Ta \(c* Ta circle-multiply +.It \e(c+ Ta \(c+ Ta circle-plus +.It \e[tdi] Ta \[tdi] Ta divide (text font) +.It \e(di Ta \(di Ta divide (special font) +.It \e(f/ Ta \(f/ Ta fraction +.It \e(** Ta \(** Ta asterisk +.It \e(<= Ta \(<= Ta less-than-equal +.It \e(>= Ta \(>= Ta greater-than-equal +.It \e(<< Ta \(<< Ta much less +.It \e(>> Ta \(>> Ta much greater +.It \e(eq Ta \(eq Ta equal +.It \e(!= Ta \(!= Ta not equal +.It \e(== Ta \(== Ta equivalent +.It \e(ne Ta \(ne Ta not equivalent +.It \e(ap Ta \(ap Ta tilde operator +.It \e(|= Ta \(|= Ta asymptotically equal +.It \e(=\(ti Ta \(=~ Ta approximately equal +.It \e(\(ti\(ti Ta \(~~ Ta almost equal +.It \e(\(ti= Ta \(~= Ta almost equal +.It \e(pt Ta \(pt Ta proportionate +.It \e(es Ta \(es Ta empty set +.It \e(mo Ta \(mo Ta element +.It \e(nm Ta \(nm Ta not element +.It \e(sb Ta \(sb Ta proper subset +.It \e(nb Ta \(nb Ta not subset +.It \e(sp Ta \(sp Ta proper superset +.It \e(nc Ta \(nc Ta not superset +.It \e(ib Ta \(ib Ta reflexive subset +.It \e(ip Ta \(ip Ta reflexive superset +.It \e(ca Ta \(ca Ta intersection +.It \e(cu Ta \(cu Ta union +.It \e(/_ Ta \(/_ Ta angle +.It \e(pp Ta \(pp Ta perpendicular +.It \e(is Ta \(is Ta integral +.It \e[integral] Ta \[integral] Ta integral +.It \e[sum] Ta \[sum] Ta summation +.It \e[product] Ta \[product] Ta product +.It \e[coproduct] Ta \[coproduct] Ta coproduct +.It \e(gr Ta \(gr Ta gradient +.It \e(sr Ta \(sr Ta square root +.It \e[sqrt] Ta \[sqrt] Ta square root +.It \e(lc Ta \(lc Ta left-ceiling +.It \e(rc Ta \(rc Ta right-ceiling +.It \e(lf Ta \(lf Ta left-floor +.It \e(rf Ta \(rf Ta right-floor +.It \e(if Ta \(if Ta infinity +.It \e(Ah Ta \(Ah Ta aleph +.It \e(Im Ta \(Im Ta imaginary +.It \e(Re Ta \(Re Ta real +.It \e(wp Ta \(wp Ta Weierstrass p +.It \e(pd Ta \(pd Ta partial differential +.It \e(-h Ta \(-h Ta Planck constant over 2\(*p +.It \e[hbar] Ta \[hbar] Ta Planck constant over 2\(*p +.It \e(12 Ta \(12 Ta one-half +.It \e(14 Ta \(14 Ta one-fourth +.It \e(34 Ta \(34 Ta three-fourths +.It \e(18 Ta \(18 Ta one-eighth +.It \e(38 Ta \(38 Ta three-eighths +.It \e(58 Ta \(58 Ta five-eighths +.It \e(78 Ta \(78 Ta seven-eighths +.It \e(S1 Ta \(S1 Ta superscript 1 +.It \e(S2 Ta \(S2 Ta superscript 2 +.It \e(S3 Ta \(S3 Ta superscript 3 +.El +.Pp +Ligatures: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(ff Ta \(ff Ta ff ligature +.It \e(fi Ta \(fi Ta fi ligature +.It \e(fl Ta \(fl Ta fl ligature +.It \e(Fi Ta \(Fi Ta ffi ligature +.It \e(Fl Ta \(Fl Ta ffl ligature +.It \e(AE Ta \(AE Ta AE +.It \e(ae Ta \(ae Ta ae +.It \e(OE Ta \(OE Ta OE +.It \e(oe Ta \(oe Ta oe +.It \e(ss Ta \(ss Ta German eszett +.It \e(IJ Ta \(IJ Ta IJ ligature +.It \e(ij Ta \(ij Ta ij ligature +.El +.Pp +Accents: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(a" Ta \(a" Ta Hungarian umlaut +.It \e(a- Ta \(a- Ta macron +.It \e(a. Ta \(a. Ta dotted +.It \e(a^ Ta \(a^ Ta circumflex +.It \e(aa Ta \(aa Ta acute +.It \e\(aq Ta \' Ta acute +.It \e(ga Ta \(ga Ta grave +.It \e\(ga Ta \` Ta grave +.It \e(ab Ta \(ab Ta breve +.It \e(ac Ta \(ac Ta cedilla +.It \e(ad Ta \(ad Ta dieresis +.It \e(ah Ta \(ah Ta caron +.It \e(ao Ta \(ao Ta ring +.It \e(a\(ti Ta \(a~ Ta tilde +.It \e(ho Ta \(ho Ta ogonek +.It \e(ha Ta \(ha Ta hat (ASCII character) +.It \e(ti Ta \(ti Ta tilde (ASCII character) +.El +.Pp +Accented letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(\(aqA Ta \('A Ta acute A +.It \e(\(aqE Ta \('E Ta acute E +.It \e(\(aqI Ta \('I Ta acute I +.It \e(\(aqO Ta \('O Ta acute O +.It \e(\(aqU Ta \('U Ta acute U +.It \e(\(aqY Ta \('Y Ta acute Y +.It \e(\(aqa Ta \('a Ta acute a +.It \e(\(aqe Ta \('e Ta acute e +.It \e(\(aqi Ta \('i Ta acute i +.It \e(\(aqo Ta \('o Ta acute o +.It \e(\(aqu Ta \('u Ta acute u +.It \e(\(aqy Ta \('y Ta acute y +.It \e(\(gaA Ta \(`A Ta grave A +.It \e(\(gaE Ta \(`E Ta grave E +.It \e(\(gaI Ta \(`I Ta grave I +.It \e(\(gaO Ta \(`O Ta grave O +.It \e(\(gaU Ta \(`U Ta grave U +.It \e(\(gaa Ta \(`a Ta grave a +.It \e(\(gae Ta \(`e Ta grave e +.It \e(\(gai Ta \(`i Ta grave i +.It \e(\(gao Ta \(`i Ta grave o +.It \e(\(gau Ta \(`u Ta grave u +.It \e(\(tiA Ta \(~A Ta tilde A +.It \e(\(tiN Ta \(~N Ta tilde N +.It \e(\(tiO Ta \(~O Ta tilde O +.It \e(\(tia Ta \(~a Ta tilde a +.It \e(\(tin Ta \(~n Ta tilde n +.It \e(\(tio Ta \(~o Ta tilde o +.It \e(:A Ta \(:A Ta dieresis A +.It \e(:E Ta \(:E Ta dieresis E +.It \e(:I Ta \(:I Ta dieresis I +.It \e(:O Ta \(:O Ta dieresis O +.It \e(:U Ta \(:U Ta dieresis U +.It \e(:a Ta \(:a Ta dieresis a +.It \e(:e Ta \(:e Ta dieresis e +.It \e(:i Ta \(:i Ta dieresis i +.It \e(:o Ta \(:o Ta dieresis o +.It \e(:u Ta \(:u Ta dieresis u +.It \e(:y Ta \(:y Ta dieresis y +.It \e(^A Ta \(^A Ta circumflex A +.It \e(^E Ta \(^E Ta circumflex E +.It \e(^I Ta \(^I Ta circumflex I +.It \e(^O Ta \(^O Ta circumflex O +.It \e(^U Ta \(^U Ta circumflex U +.It \e(^a Ta \(^a Ta circumflex a +.It \e(^e Ta \(^e Ta circumflex e +.It \e(^i Ta \(^i Ta circumflex i +.It \e(^o Ta \(^o Ta circumflex o +.It \e(^u Ta \(^u Ta circumflex u +.It \e(,C Ta \(,C Ta cedilla C +.It \e(,c Ta \(,c Ta cedilla c +.It \e(/L Ta \(/L Ta stroke L +.It \e(/l Ta \(/l Ta stroke l +.It \e(/O Ta \(/O Ta stroke O +.It \e(/o Ta \(/o Ta stroke o +.It \e(oA Ta \(oA Ta ring A +.It \e(oa Ta \(oa Ta ring a +.El +.Pp +Special letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(-D Ta \(-D Ta Eth +.It \e(Sd Ta \(Sd Ta eth +.It \e(TP Ta \(TP Ta Thorn +.It \e(Tp Ta \(Tp Ta thorn +.It \e(.i Ta \(.i Ta dotless i +.It \e(.j Ta \(.j Ta dotless j +.El +.Pp +Currency: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(Do Ta \(Do Ta dollar +.It \e(ct Ta \(ct Ta cent +.It \e(Eu Ta \(Eu Ta Euro symbol +.It \e(eu Ta \(eu Ta Euro symbol +.It \e(Ye Ta \(Ye Ta yen +.It \e(Po Ta \(Po Ta pound +.It \e(Cs Ta \(Cs Ta Scandinavian +.It \e(Fn Ta \(Fn Ta florin +.El +.Pp +Units: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(de Ta \(de Ta degree +.It \e(%0 Ta \(%0 Ta per-thousand +.It \e(fm Ta \(fm Ta minute +.It \e(sd Ta \(sd Ta second +.It \e(mc Ta \(mc Ta micro +.It \e(Of Ta \(Of Ta Spanish female ordinal +.It \e(Om Ta \(Om Ta Spanish masculine ordinal +.El +.Pp +Greek letters: +.Bl -column "Input" "Rendered" "Description" -offset indent -compact +.It Em Input Ta Em Rendered Ta Em Description +.It \e(*A Ta \(*A Ta Alpha +.It \e(*B Ta \(*B Ta Beta +.It \e(*G Ta \(*G Ta Gamma +.It \e(*D Ta \(*D Ta Delta +.It \e(*E Ta \(*E Ta Epsilon +.It \e(*Z Ta \(*Z Ta Zeta +.It \e(*Y Ta \(*Y Ta Eta +.It \e(*H Ta \(*H Ta Theta +.It \e(*I Ta \(*I Ta Iota +.It \e(*K Ta \(*K Ta Kappa +.It \e(*L Ta \(*L Ta Lambda +.It \e(*M Ta \(*M Ta Mu +.It \e(*N Ta \(*N Ta Nu +.It \e(*C Ta \(*C Ta Xi +.It \e(*O Ta \(*O Ta Omicron +.It \e(*P Ta \(*P Ta Pi +.It \e(*R Ta \(*R Ta Rho +.It \e(*S Ta \(*S Ta Sigma +.It \e(*T Ta \(*T Ta Tau +.It \e(*U Ta \(*U Ta Upsilon +.It \e(*F Ta \(*F Ta Phi +.It \e(*X Ta \(*X Ta Chi +.It \e(*Q Ta \(*Q Ta Psi +.It \e(*W Ta \(*W Ta Omega +.It \e(*a Ta \(*a Ta alpha +.It \e(*b Ta \(*b Ta beta +.It \e(*g Ta \(*g Ta gamma +.It \e(*d Ta \(*d Ta delta +.It \e(*e Ta \(*e Ta epsilon +.It \e(*z Ta \(*z Ta zeta +.It \e(*y Ta \(*y Ta eta +.It \e(*h Ta \(*h Ta theta +.It \e(*i Ta \(*i Ta iota +.It \e(*k Ta \(*k Ta kappa +.It \e(*l Ta \(*l Ta lambda +.It \e(*m Ta \(*m Ta mu +.It \e(*n Ta \(*n Ta nu +.It \e(*c Ta \(*c Ta xi +.It \e(*o Ta \(*o Ta omicron +.It \e(*p Ta \(*p Ta pi +.It \e(*r Ta \(*r Ta rho +.It \e(*s Ta \(*s Ta sigma +.It \e(*t Ta \(*t Ta tau +.It \e(*u Ta \(*u Ta upsilon +.It \e(*f Ta \(*f Ta phi +.It \e(*x Ta \(*x Ta chi +.It \e(*q Ta \(*q Ta psi +.It \e(*w Ta \(*w Ta omega +.It \e(+h Ta \(+h Ta theta variant +.It \e(+f Ta \(+f Ta phi variant +.It \e(+p Ta \(+p Ta pi variant +.It \e(+e Ta \(+e Ta epsilon variant +.It \e(ts Ta \(ts Ta sigma terminal +.El +.Sh PREDEFINED STRINGS +Predefined strings are inherited from the macro packages of historical +troff implementations. +They are +.Em not recommended +for use, as they differ across implementations. +Manuals using these predefined strings are almost certainly not +portable. +.Pp +Their syntax is similar to special characters, using +.Sq \e*X +.Pq for a one-character escape , +.Sq \e*(XX +.Pq two-character , +and +.Sq \e*[N] +.Pq N-character . +.Bl -column "Input" "Rendered" "Description" -offset indent +.It Em Input Ta Em Rendered Ta Em Description +.It \e*(Ba Ta \*(Ba Ta vertical bar +.It \e*(Ne Ta \*(Ne Ta not equal +.It \e*(Ge Ta \*(Ge Ta greater-than-equal +.It \e*(Le Ta \*(Le Ta less-than-equal +.It \e*(Gt Ta \*(Gt Ta greater-than +.It \e*(Lt Ta \*(Lt Ta less-than +.It \e*(Pm Ta \*(Pm Ta plus-minus +.It \e*(If Ta \*(If Ta infinity +.It \e*(Pi Ta \*(Pi Ta pi +.It \e*(Na Ta \*(Na Ta NaN +.It \e*(Am Ta \*(Am Ta ampersand +.It \e*R Ta \*R Ta restricted mark +.It \e*(Tm Ta \*(Tm Ta trade mark +.It \e*q Ta \*q Ta double-quote +.It \e*(Rq Ta \*(Rq Ta right-double-quote +.It \e*(Lq Ta \*(Lq Ta left-double-quote +.It \e*(lp Ta \*(lp Ta right-parenthesis +.It \e*(rp Ta \*(rp Ta left-parenthesis +.It \e*(lq Ta \*(lq Ta left double-quote +.It \e*(rq Ta \*(rq Ta right double-quote +.It \e*(ua Ta \*(ua Ta up arrow +.It \e*(va Ta \*(va Ta up-down arrow +.It \e*(<= Ta \*(<= Ta less-than-equal +.It \e*(>= Ta \*(>= Ta greater-than-equal +.It \e*(aa Ta \*(aa Ta acute +.It \e*(ga Ta \*(ga Ta grave +.It \e*(Px Ta \*(Px Ta POSIX standard name +.It \e*(Ai Ta \*(Ai Ta ANSI standard name +.El +.Sh UNICODE CHARACTERS +The escape sequences +.Pp +.Dl \e[uXXXX] and \eC\(aquXXXX\(aq +.Pp +are interpreted as Unicode codepoints. +The codepoint must be in the range above U+0080 and less than U+10FFFF. +For compatibility, the hexadecimal digits +.Sq A +to +.Sq F +must be given as uppercase characters, +and points must be zero-padded to four characters; if +greater than four characters, no zero padding is allowed. +Unicode surrogates are not allowed. +.Sh NUMBERED CHARACTERS +For backward compatibility with existing manuals, +.Xr mandoc 1 +also supports the +.Pp +.Dl \eN\(aq Ns Ar number Ns \(aq and \e[ Ns Cm char Ns Ar number ] +.Pp +escape sequences, inserting the character +.Ar number +from the current character set into the output. +Of course, this is inherently non-portable and is already marked +as deprecated in the Heirloom roff manual; +on top of that, the second form is a GNU extension. +For example, do not use \eN\(aq34\(aq or \e[char34], use \e(dq, +or even the plain +.Sq \(dq +character where possible. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other +troff implementations, at this time limited to GNU troff +.Pq Qq groff . +.Pp +.Bl -dash -compact +.It +The \eN\(aq\(aq escape sequence is limited to printable characters; in +groff, it accepts arbitrary character numbers. +.It +In +.Fl T Ns Cm ascii , +the +\e(ss, \e(nm, \e(nb, \e(nc, \e(ib, \e(ip, \e(pp, \e[sum], \e[product], +\e[coproduct], \e(gr, \e(-h, and \e(a. special characters render +differently between mandoc and groff. +.It +In +.Fl T Ns Cm html , +the \e(\(ti=, \e(nb, and \e(nc special characters render differently +between mandoc and groff. +.It +The +.Fl T Ns Cm ps +and +.Fl T Ns Cm pdf +modes format like +.Fl T Ns Cm ascii +instead of rendering glyphs as in groff. +.It +The \e[radicalex], \e[sqrtex], and \e(ru special characters have been omitted +from mandoc either because they are poorly documented or they have no +known representation. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_roff 7 , +.Xr mdoc 7 +.Sh AUTHORS +The +.Nm +manual page was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +.Sh CAVEATS +The predefined string +.Sq \e*(Ba +mimics the behaviour of the +.Sq \&| +character in +.Xr mdoc 7 ; +thus, if you wish to render a vertical bar with no side effects, use +the +.Sq \e(ba +escape. diff --git a/usr/src/man/man7/mandoc_roff.7 b/usr/src/man/man7/mandoc_roff.7 new file mode 100644 index 0000000000..6c2e3583f6 --- /dev/null +++ b/usr/src/man/man7/mandoc_roff.7 @@ -0,0 +1,2342 @@ +.\" $Id: roff.7,v 1.116 2021/09/18 12:23:06 schwarze Exp $ +.\" +.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2010-2019 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: September 18 2021 $ +.Dt ROFF 7 +.Os +.Sh NAME +.Nm roff +.Nd roff language reference for mandoc +.Sh DESCRIPTION +The +.Nm roff +language is a general purpose text formatting language. +Since traditional implementations of the +.Xr mdoc 7 +and +.Xr man 7 +manual formatting languages are based on it, +many real-world manuals use small numbers of +.Nm +requests and escape sequences intermixed with their +.Xr mdoc 7 +or +.Xr man 7 +code. +To properly format such manuals, the +.Xr mandoc 1 +utility supports a subset of +.Nm +requests and escapes. +Even though this manual page lists all +.Nm +requests and escape sequences, it only contains partial information +about requests not supported by +.Xr mandoc 1 +and about language features that do not matter for manual pages. +For complete +.Nm +manuals, consult the +.Sx SEE ALSO +section. +.Pp +Input lines beginning with the control character +.Sq \&. +are parsed for requests and macros. +Such lines are called +.Dq request lines +or +.Dq macro lines , +respectively. +Requests change the processing state and manipulate the formatting; +some macros also define the document structure and produce formatted +output. +The single quote +.Pq Qq \(aq +is accepted as an alternative control character, +treated by +.Xr mandoc 1 +just like +.Ql \&. +.Pp +Lines not beginning with control characters are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context. +.Sh LANGUAGE SYNTAX +.Nm +documents may contain only graphable 7-bit ASCII characters, the space +character, and, in certain circumstances, the tab character. +The backslash character +.Sq \e +indicates the start of an escape sequence, used for example for +.Sx Comments +and +.Sx Special Characters . +For a complete listing of escape sequences, consult the +.Sx ESCAPE SEQUENCE REFERENCE +below. +.Ss Comments +Text following an escaped double-quote +.Sq \e\(dq , +whether in a request, macro, or text line, is ignored to the end of the line. +A request line beginning with a control character and comment escape +.Sq \&.\e\(dq +is also ignored. +Furthermore, request lines with only a control character and optional +trailing whitespace are stripped from input. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.\e\(dq This is a comment line. +\&.\e\(dq The next line is ignored: +\&. +\&.Sh EXAMPLES \e\(dq This is a comment, too. +\&example text \e\(dq And so is this. +.Ed +.Ss Special Characters +Special characters are used to encode special glyphs and are rendered +differently across output media. +They may occur in request, macro, and text lines. +Sequences begin with the escape character +.Sq \e +followed by either an open-parenthesis +.Sq \&( +for two-character sequences; an open-bracket +.Sq \&[ +for n-character sequences (terminated at a close-bracket +.Sq \&] ) ; +or a single one character sequence. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \e(em +Two-letter em dash escape. +.It Li \ee +One-letter backslash escape. +.El +.Pp +See +.Xr mandoc_char 7 +for a complete list. +.Ss Font Selection +In +.Xr mdoc 7 +and +.Xr man 7 +documents, fonts are usually selected with macros. +The +.Ic \ef +escape sequence and the +.Ic \&ft +request can be used to manually change the font, +but this is not recommended in +.Xr mdoc 7 +documents. +Such manual font changes are overridden by many subsequent macros. +.Pp +The following fonts are supported: +.Pp +.Bl -tag -width CW -offset indent -compact +.It Cm B +Bold font. +.It Cm BI +A font that is both bold and italic. +.It Cm CB +Bold constant width font. +Same as +.Cm B +in terminal output. +.It Cm CI +Italic constant width font. +Same as +.Cm I +in terminal output. +.It Cm CR +Regular constant width font. +Same as +.Cm R +in terminal output. +.It Cm CW +An alias for +.Cm CR . +.It Cm I +Italic font. +.It Cm P +Return to the previous font. +If a macro caused a font change since the last +.Ic \ef +eascape sequence or +.Ic \&ft +request, this returns to the font before the last font change in +the macro rather than to the font before the last manual font change. +.It Cm R +Roman font. +This is the default font. +.It Cm 1 +An alias for +.Cm R . +.It Cm 2 +An alias for +.Cm I . +.It Cm 3 +An alias for +.Cm B . +.It Cm 4 +An alias for +.Cm BI . +.El +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \efBbold\efR +Write in \fBbold\fP, then switch to regular font mode. +.It Li \efIitalic\efP +Write in \fIitalic\fP, then return to previous font mode. +.It Li \ef(BIbold italic\efP +Write in \f(BIbold italic\fP, then return to previous font mode. +.El +.Ss Whitespace +Whitespace consists of the space character. +In text lines, whitespace is preserved within a line. +In request and macro lines, whitespace delimits arguments and is discarded. +.Pp +Unescaped trailing spaces are stripped from text line input unless in a +literal context. +In general, trailing whitespace on any input line is discouraged for +reasons of portability. +In the rare case that a space character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp +Literal space characters can be produced in the output +using escape sequences. +In macro lines, they can also be included in arguments using quotation; see +.Sx MACRO SYNTAX +for details. +.Pp +Blank text lines, which may include whitespace, are only permitted +within literal contexts. +If the first character of a text line is a space, that line is printed +with a leading newline. +.Ss Scaling Widths +Many requests and macros support scaled widths for their arguments. +The syntax for a scaled width is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or followed by at least one digit. +.Pp +The following scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (1/6 inch) +.It p +point (1/72 inch) +.It f +scale +.Sq u +by 65536 +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span for the terminal +.It M +mini-em (1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +or +.Sq v +is necessarily non-portable across output media. +See +.Sx COMPATIBILITY . +.Pp +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Pp +Examples: +.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact +.It Li \&.Bl -tag -width 2i +two-inch tagged list indentation in +.Xr mdoc 7 +.It Li \&.HP 2i +two-inch tagged list indentation in +.Xr man 7 +.It Li \&.sp 2v +two vertical spaces +.El +.Ss Sentence Spacing +Each sentence should terminate at the end of an input line. +By doing this, a formatter will be able to apply the proper amount of +spacing after the end of sentence (unescaped) period, exclamation mark, +or question mark followed by zero or more non-sentence closing +delimiters +.Po +.Sq \&) , +.Sq \&] , +.Sq \&' , +.Sq \&" +.Pc . +.Pp +The proper spacing is also intelligently preserved if a sentence ends at +the boundary of a macro line. +.Pp +If an input line happens to end with a period, exclamation or question +mark that isn't the end of a sentence, append a zero-width space +.Pq Sq \e& . +.Pp +Examples: +.Bd -literal -offset indent -compact +Do not end sentences mid-line like this. Instead, +end a sentence like this. +A macro would end like this: +\&.Xr mandoc 1 \&. +An abbreviation at the end of an input line needs escaping, e.g.\e& +like this. +.Ed +.Sh REQUEST SYNTAX +A request or macro line consists of: +.Pp +.Bl -enum -compact +.It +the control character +.Sq \&. +or +.Sq \(aq +at the beginning of the line, +.It +optionally an arbitrary amount of whitespace, +.It +the name of the request or the macro, which is one word of arbitrary +length, terminated by whitespace, +.It +and zero or more arguments delimited by whitespace. +.El +.Pp +Thus, the following request lines are all equivalent: +.Bd -literal -offset indent +\&.ig end +\&.ig end +\&. ig end +.Ed +.Sh MACRO SYNTAX +Macros are provided by the +.Xr mdoc 7 +and +.Xr man 7 +languages and can be defined by the +.Ic \&de +request. +When called, they follow the same syntax as requests, except that +macro arguments may optionally be quoted by enclosing them +in double quote characters +.Pq Sq \(dq . +Quoted text, even if it contains whitespace or would cause +a macro invocation when unquoted, is always considered literal text. +Inside quoted text, pairs of double quote characters +.Pq Sq Qq +resolve to single double quote characters. +.Pp +To be recognised as the beginning of a quoted argument, the opening +quote character must be preceded by a space character. +A quoted argument extends to the next double quote character that is not +part of a pair, or to the end of the input line, whichever comes earlier. +Leaving out the terminating double quote character at the end of the line +is discouraged. +For clarity, if more arguments follow on the same input line, +it is recommended to follow the terminating double quote character +by a space character; in case the next character after the terminating +double quote character is anything else, it is regarded as the beginning +of the next, unquoted argument. +.Pp +Both in quoted and unquoted arguments, pairs of backslashes +.Pq Sq \e\e +resolve to single backslashes. +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li .Fn strlen \(dqconst char *s\(dq +Group arguments +.Qq const char *s +into one function argument. +If unspecified, +.Qq const , +.Qq char , +and +.Qq *s +would be considered separate arguments. +.It Li .Op \(dqFl a\(dq +Consider +.Qq \&Fl a +as literal text instead of a flag macro. +.El +.Sh REQUEST REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following requests. +For requests marked as "ignored" or "unsupported", any arguments are +ignored, and the number of arguments is not checked. +.Bl -tag -width Ds +.It Ic \&ab Op Ar message +Abort processing. +Currently unsupported. +.It Ic \&ad Op Cm b | c | l | n | r +Set line adjustment mode for subsequent text. +Currently ignored. +.It Ic \&af Ar registername format +Assign an output format to a number register. +Currently ignored. +.It Ic \&aln Ar newname oldname +Create an alias for a number register. +Currently unsupported. +.It Ic \&als Ar newname oldname +Create an alias for a request, string, macro, or diversion. +.It Ic \&am Ar macroname Op Ar endmacro +Append to a macro definition. +The syntax of this request is the same as that of +.Ic \&de . +.It Ic \&am1 Ar macroname Op Ar endmacro +Append to a macro definition, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Ic \&de1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&am . +.It Ic \&ami Ar macrostring Op Ar endstring +Append to a macro definition, specifying the macro name indirectly +(groff extension). +The syntax of this request is the same as that of +.Ic \&dei . +.It Ic \&ami1 Ar macrostring Op Ar endstring +Append to a macro definition, specifying the macro name indirectly +and switching roff compatibility mode off during macro execution +(groff extension). +The syntax of this request is the same as that of +.Ic \&dei1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&ami . +.It Ic \&as Ar stringname Op Ar string +Append to a user-defined string. +The syntax of this request is the same as that of +.Ic \&ds . +If a user-defined string with the specified name does not yet exist, +it is set to the empty string before appending. +.It Ic \&as1 Ar stringname Op Ar string +Append to a user-defined string, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Ic \&ds1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&as . +.It Ic \&asciify Ar divname +Fully unformat a diversion. +Currently unsupported. +.It Ic \&backtrace +Print a backtrace of the input stack. +This is a groff extension and currently ignored. +.It Ic \&bd Ar font Oo Ar curfont Oc Op Ar offset +Artificially embolden by repeated printing with small shifts. +Currently ignored. +.It Ic \&bleedat Ar left top width height +Set the BleedBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&blm Ar macroname +Set a blank line trap. +Currently unsupported. +.It Ic \&box Ar divname +Begin a diversion without including a partially filled line. +Currently unsupported. +.It Ic \&boxa Ar divname +Add to a diversion without including a partially filled line. +Currently unsupported. +.It Ic \&bp Oo Cm + Ns | Ns Cm - Oc Ns Ar pagenumber +Begin a new page. +Currently ignored. +.It Ic \&BP Ar source height width position offset flags label +Define a frame and place a picture in it. +This is a Heirloom extension and currently unsupported. +.It Ic \&br +Break the output line. +.It Ic \&break +Break out of the innermost +.Ic \&while +loop. +.It Ic \&breakchar Ar char ... +Optional line break characters. +This is a Heirloom extension and currently ignored. +.It Ic \&brnl Ar N +Break output line after the next +.Ar N +input lines. +This is a Heirloom extension and currently ignored. +.It Ic \&brp +Break and spread output line. +Currently, this is implemented as an alias for +.Ic \&br . +.It Ic \&brpnl Ar N +Break and spread output line after the next +.Ar N +input lines. +This is a Heirloom extension and currently ignored. +.It Ic \&c2 Op Ar char +Change the no-break control character. +Currently unsupported. +.It Ic \&cc Op Ar char +Change the control character. +If +.Ar char +is not specified, the control character is reset to +.Sq \&. . +Trailing characters are ignored. +.It Ic \&ce Op Ar N +Center the next +.Ar N +input lines without filling. +.Ar N +defaults to 1. +An argument of 0 or less ends centering. +Currently, high level macros abort centering. +.It Ic \&cf Ar filename +Output the contents of a file. +Ignored because insecure. +.It Ic \&cflags Ar flags char ... +Set character flags. +This is a groff extension and currently ignored. +.It Ic \&ch Ar macroname Op Ar dist +Change a trap location. +Currently ignored. +.It Ic \&char Ar glyph Op Ar string +Define or redefine the ASCII character or character escape sequence +.Ar glyph +to be rendered as +.Ar string , +which can be empty. +Only partially supported in +.Xr mandoc 1 ; +may interact incorrectly with +.Ic \&tr . +.It Ic \&chop Ar stringname +Remove the last character from a macro, string, or diversion. +Currently unsupported. +.It Ic \&class Ar classname char ... +Define a character class. +This is a groff extension and currently ignored. +.It Ic \&close Ar streamname +Close an open file. +Ignored because insecure. +.It Ic \&CL Ar color text +Print text in color. +This is a Heirloom extension and currently unsupported. +.It Ic \&color Op Cm 1 | 0 +Activate or deactivate colors. +This is a groff extension and currently ignored. +.It Ic \&composite Ar from to +Define a name component for composite glyph names. +This is a groff extension and currently unsupported. +.It Ic \&continue +Immediately start the next iteration of a +.Ic \&while +loop. +Currently unsupported. +.It Ic \&cp Op Cm 1 | 0 +Switch +.Nm +compatibility mode on or off. +Currently ignored. +.It Ic \&cropat Ar left top width height +Set the CropBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&cs Ar font Op Ar width Op Ar emsize +Constant character spacing mode. +Currently ignored. +.It Ic \&cu Op Ar N +Underline next +.Ar N +input lines including whitespace. +Currently ignored. +.It Ic \&da Ar divname +Append to a diversion. +Currently unsupported. +.It Ic \&dch Ar macroname Op Ar dist +Change a trap location in the current diversion. +This is a Heirloom extension and currently unsupported. +.It Ic \&de Ar macroname Op Ar endmacro +Define a +.Nm +macro. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Ic \&de Ar macroname +.Ar definition +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Ic \&de Ar macroname endmacro +.Ar definition +.Pf . Ar endmacro +.Ed +.Pp +Both forms define or redefine the macro +.Ar macroname +to represent the +.Ar definition , +which may consist of one or more input lines, including the newline +characters terminating each line, optionally containing calls to +.Nm +requests, +.Nm +macros or high-level macros like +.Xr man 7 +or +.Xr mdoc 7 +macros, whichever applies to the document in question. +.Pp +Specifying a custom +.Ar endmacro +works in the same way as for +.Ic \&ig ; +namely, the call to +.Sq Pf . Ar endmacro +first ends the +.Ar definition , +and after that, it is also evaluated as a +.Nm +request or +.Nm +macro, but not as a high-level macro. +.Pp +The macro can be invoked later using the syntax +.Pp +.D1 Pf . Ar macroname Op Ar argument Op Ar argument ... +.Pp +Regarding argument parsing, see +.Sx MACRO SYNTAX +above. +.Pp +The line invoking the macro will be replaced +in the input stream by the +.Ar definition , +replacing all occurrences of +.No \e\e$ Ns Ar N , +where +.Ar N +is a digit, by the +.Ar N Ns th Ar argument . +For example, +.Bd -literal -offset indent +\&.de ZN +\efI\e^\e\e$1\e^\efP\e\e$2 +\&.. +\&.ZN XtFree . +.Ed +.Pp +produces +.Pp +.D1 \efI\e^XtFree\e^\efP. +.Pp +in the input stream, and thus in the output: \fI\^XtFree\^\fP. +Each occurrence of \e\e$* is replaced with all the arguments, +joined together with single space characters. +The variant \e\e$@ is similar, except that each argument is +individually quoted. +.Pp +Since macros and user-defined strings share a common string table, +defining a macro +.Ar macroname +clobbers the user-defined string +.Ar macroname , +and the +.Ar definition +can also be printed using the +.Sq \e* +string interpolation syntax described below +.Ic ds , +but this is rarely useful because every macro definition contains at least +one explicit newline character. +.Pp +In order to prevent endless recursion, both groff and +.Xr mandoc 1 +limit the stack depth for expanding macros and strings +to a large, but finite number, and +.Xr mandoc 1 +also limits the length of the expanded input line. +Do not rely on the exact values of these limits. +.It Ic \&de1 Ar macroname Op Ar endmacro +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&de . +.It Ic \&defcolor Ar newname scheme component ... +Define a color name. +This is a groff extension and currently ignored. +.It Ic \&dei Ar macrostring Op Ar endstring +Define a +.Nm +macro, specifying the macro name indirectly (groff extension). +The syntax of this request is the same as that of +.Ic \&de . +The effect is the same as: +.Pp +.D1 Pf . Cm \&de No \e* Ns Bo Ar macrostring Bc Op \e* Ns Bq Ar endstring +.It Ic \&dei1 Ar macrostring Op Ar endstring +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution, +specifying the macro name indirectly (groff extension). +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&dei . +.It Ic \&device Ar string ... +.It Ic \&devicem Ar stringname +These two requests only make sense with the groff-specific intermediate +output format and are unsupported. +.It Ic \&di Ar divname +Begin a diversion. +Currently unsupported. +.It Ic \&do Ar command Op Ar argument ... +Execute +.Nm +request or macro line with compatibility mode disabled. +Currently unsupported. +.It Ic \&ds Ar stringname Op Oo \(dq Oc Ns Ar string +Define a user-defined string. +The +.Ar stringname +and +.Ar string +arguments are space-separated. +If the +.Ar string +begins with a double-quote character, that character will not be part +of the string. +All remaining characters on the input line form the +.Ar string , +including whitespace and double-quote characters, even trailing ones. +.Pp +The +.Ar string +can be interpolated into subsequent text by using +.No \e* Ns Bq Ar stringname +for a +.Ar stringname +of arbitrary length, or \e*(NN or \e*N if the length of +.Ar stringname +is two or one characters, respectively. +Interpolation can be prevented by escaping the leading backslash; +that is, an asterisk preceded by an even number of backslashes +does not trigger string interpolation. +.Pp +Since user-defined strings and macros share a common string table, +defining a string +.Ar stringname +clobbers the macro +.Ar stringname , +and the +.Ar stringname +used for defining a string can also be invoked as a macro, +in which case the following input line will be appended to the +.Ar string , +forming a new input line passed to the +.Nm +parser. +For example, +.Bd -literal -offset indent +\&.ds badidea .S +\&.badidea +H SYNOPSIS +.Ed +.Pp +invokes the +.Ic SH +macro when used in a +.Xr man 7 +document. +Such abuse is of course strongly discouraged. +.It Ic \&ds1 Ar stringname Op Oo \(dq Oc Ns Ar string +Define a user-defined string that will be expanded with +.Nm +compatibility mode switched off during string expansion. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Ic \&ds . +.It Ic \&dwh Ar dist macroname +Set a location trap in the current diversion. +This is a Heirloom extension and currently unsupported. +.It Ic \&dt Op Ar dist macroname +Set a trap within a diversion. +Currently unsupported. +.It Ic \&ec Op Ar char +Enable the escape mechanism and change the escape character. +The +.Ar char +argument defaults to the backslash +.Pq Sq \e . +.It Ic \&ecr +Restore the escape character. +Currently unsupported. +.It Ic \&ecs +Save the escape character. +Currently unsupported. +.It Ic \&el Ar body +The +.Dq else +half of an if/else conditional. +Pops a result off the stack of conditional evaluations pushed by +.Ic \&ie +and uses it as its conditional. +If no stack entries are present (e.g., due to no prior +.Ic \&ie +calls) +then false is assumed. +The syntax of this request is similar to +.Ic \&if +except that the conditional is missing. +.It Ic \&em Ar macroname +Set a trap at the end of input. +Currently unsupported. +.It Ic \&EN +End an equation block. +See +.Ic \&EQ . +.It Ic \&eo +Disable the escape mechanism completely. +.It Ic \&EP +End a picture started by +.Ic \&BP . +This is a Heirloom extension and currently unsupported. +.It Ic \&EQ +Begin an equation block. +See +.Xr eqn 7 +for a description of the equation language. +.It Ic \&errprint Ar message +Print a string like an error message. +This is a Heirloom extension and currently ignored. +.It Ic \&ev Op Ar envname +Switch to another environment. +Currently unsupported. +.It Ic \&evc Op Ar envname +Copy an environment into the current environment. +Currently unsupported. +.It Ic \&ex +Abort processing and exit. +Currently unsupported. +.It Ic \&fallback Ar curfont font ... +Select the fallback sequence for a font. +This is a Heirloom extension and currently ignored. +.It Ic \&fam Op Ar familyname +Change the font family. +This is a groff extension and currently ignored. +.It Ic \&fc Op Ar delimchar Op Ar padchar +Define a delimiting and a padding character for fields. +Currently unsupported. +.It Ic \&fchar Ar glyphname Op Ar string +Define a fallback glyph. +Currently unsupported. +.It Ic \&fcolor Ar colorname +Set the fill color for \eD objects. +This is a groff extension and currently ignored. +.It Ic \&fdeferlig Ar font string ... +Defer ligature building. +This is a Heirloom extension and currently ignored. +.It Ic \&feature Cm + Ns | Ns Cm - Ns Ar name +Enable or disable an OpenType feature. +This is a Heirloom extension and currently ignored. +.It Ic \&fi +Break the output line and switch to fill mode, +which is active by default but can be ended with the +.Ic \&nf +request. +In fill mode, input from subsequent input lines is added to +the same output line until the next word no longer fits, +at which point the output line is broken. +This request is implied by the +.Xr mdoc 7 +.Ic \&Sh +macro and by the +.Xr man 7 +.Ic \&SH , +.Ic \&SS , +and +.Ic \&EE +macros. +.It Ic \&fkern Ar font minkern +Control the use of kerning tables for a font. +This is a Heirloom extension and currently ignored. +.It Ic \&fl +Flush output. +Currently ignored. +.It Ic \&flig Ar font string char ... +Define ligatures. +This is a Heirloom extension and currently ignored. +.It Ic \&fp Ar position font Op Ar filename +Assign font position. +Currently ignored. +.It Ic \&fps Ar mapname ... +Mount a font with a special character map. +This is a Heirloom extension and currently ignored. +.It Ic \&fschar Ar font glyphname Op Ar string +Define a font-specific fallback glyph. +This is a groff extension and currently unsupported. +.It Ic \&fspacewidth Ar font Op Ar afmunits +Set a font-specific width for the space character. +This is a Heirloom extension and currently ignored. +.It Ic \&fspecial Ar curfont Op Ar font ... +Conditionally define a special font. +This is a groff extension and currently ignored. +.It Ic \&ft Op Ar font +Change the font; see +.Sx Font Selection . +The +.Ar font +argument defaults to +.Cm P . +.It Ic \&ftr Ar newname Op Ar oldname +Translate font name. +This is a groff extension and currently ignored. +.It Ic \&fzoom Ar font Op Ar permille +Zoom font size. +Currently ignored. +.It Ic \&gcolor Op Ar colorname +Set glyph color. +This is a groff extension and currently ignored. +.It Ic \&hc Op Ar char +Set the hyphenation character. +Currently ignored. +.It Ic \&hcode Ar char code ... +Set hyphenation codes of characters. +Currently ignored. +.It Ic \&hidechar Ar font char ... +Hide characters in a font. +This is a Heirloom extension and currently ignored. +.It Ic \&hla Ar language +Set hyphenation language. +This is a groff extension and currently ignored. +.It Ic \&hlm Op Ar number +Set maximum number of consecutive hyphenated lines. +Currently ignored. +.It Ic \&hpf Ar filename +Load hyphenation pattern file. +This is a groff extension and currently ignored. +.It Ic \&hpfa Ar filename +Load hyphenation pattern file, appending to the current patterns. +This is a groff extension and currently ignored. +.It Ic \&hpfcode Ar code code ... +Define mapping values for character codes in hyphenation patterns. +This is a groff extension and currently ignored. +.It Ic \&hw Ar word ... +Specify hyphenation points in words. +Currently ignored. +.It Ic \&hy Op Ar mode +Set automatic hyphenation mode. +Currently ignored. +.It Ic \&hylang Ar language +Set hyphenation language. +This is a Heirloom extension and currently ignored. +.It Ic \&hylen Ar nchar +Minimum word length for hyphenation. +This is a Heirloom extension and currently ignored. +.It Ic \&hym Op Ar length +Set hyphenation margin. +This is a groff extension and currently ignored. +.It Ic \&hypp Ar penalty ... +Define hyphenation penalties. +This is a Heirloom extension and currently ignored. +.It Ic \&hys Op Ar length +Set hyphenation space. +This is a groff extension and currently ignored. +.It Ic \&ie Ar condition body +The +.Dq if +half of an if/else conditional. +The result of the conditional is pushed into a stack used by subsequent +invocations of +.Ic \&el , +which may be separated by any intervening input (or not exist at all). +Its syntax is equivalent to +.Ic \&if . +.It Ic \&if Ar condition body +Begin a conditional. +This request can also be written as follows: +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{ Ns Ar body +.Ar body ... Ns \e} +.Ed +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{\e +.Ar body ... +.Pf . No \e} +.Ed +.Pp +The +.Ar condition +is a boolean expression. +Currently, +.Xr mandoc 1 +supports the following subset of roff conditionals: +.Bl -bullet +.It +If +.Sq \&! +is prefixed to +.Ar condition , +it is logically inverted. +.It +If the first character of +.Ar condition +is +.Sq n +.Pq nroff mode +or +.Sq o +.Pq odd page , +it evaluates to true, and the +.Ar body +starts with the next character. +.It +If the first character of +.Ar condition +is +.Sq e +.Pq even page , +.Sq t +.Pq troff mode , +or +.Sq v +.Pq vroff mode , +it evaluates to false, and the +.Ar body +starts with the next character. +.It +If the first character of +.Ar condition +is +.Sq c +.Pq character available , +it evaluates to true if the following character is an ASCII character +or a valid character escape sequence, or to false otherwise. +The +.Ar body +starts with the character following that next character. +.It +If the first character of +.Ar condition +is +.Sq d , +it evaluates to true if the rest of +.Ar condition +is the name of an existing user defined macro or string; +otherwise, it evaluates to false. +.It +If the first character of +.Ar condition +is +.Sq r , +it evaluates to true if the rest of +.Ar condition +is the name of an existing number register; +otherwise, it evaluates to false. +.It +If the +.Ar condition +starts with a parenthesis or with an optionally signed +integer number, it is evaluated according to the rules of +.Sx Numerical expressions +explained below. +It evaluates to true if the result is positive, +or to false if the result is zero or negative. +.It +Otherwise, the first character of +.Ar condition +is regarded as a delimiter and it evaluates to true if the string +extending from its first to its second occurrence is equal to the +string extending from its second to its third occurrence. +.It +If +.Ar condition +cannot be parsed, it evaluates to false. +.El +.Pp +If a conditional is false, its children are not processed, but are +syntactically interpreted to preserve the integrity of the input +document. +Thus, +.Pp +.D1 \&.if t .ig +.Pp +will discard the +.Sq \&.ig , +which may lead to interesting results, but +.Pp +.D1 \&.if t .if t \e{\e +.Pp +will continue to syntactically interpret to the block close of the final +conditional. +Sub-conditionals, in this case, obviously inherit the truth value of +the parent. +.Pp +If the +.Ar body +section is begun by an escaped brace +.Sq \e{ , +scope continues until the end of the input line containing the +matching closing-brace escape sequence +.Sq \e} . +If the +.Ar body +is not enclosed in braces, scope continues until the end of the line. +If the +.Ar condition +is followed by a +.Ar body +on the same line, whether after a brace or not, then requests and macros +.Em must +begin with a control character. +It is generally more intuitive, in this case, to write +.Bd -unfilled -offset indent +.Pf . Ic \&if Ar condition No \e{\e +.Pf . Ar request +.Pf . No \e} +.Ed +.Pp +than having the request or macro follow as +.Pp +.D1 Pf . Ic \&if Ar condition Pf \e{. Ar request +.Pp +The scope of a conditional is always parsed, but only executed if the +conditional evaluates to true. +.Pp +Note that the +.Sq \e} +is converted into a zero-width escape sequence if not passed as a +standalone macro +.Sq \&.\e} . +For example, +.Pp +.D1 \&.Fl a \e} b +.Pp +will result in +.Sq \e} +being considered an argument of the +.Sq \&Fl +macro. +.It Ic \&ig Op Ar endmacro +Ignore input. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&ig +.Ar ignored text +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&ig Ar endmacro +.Ar ignored text +.Pf . Ar endmacro +.Ed +.Pp +In the first case, input is ignored until a +.Sq \&.. +request is encountered on its own line. +In the second case, input is ignored until the specified +.Sq Pf . Ar endmacro +is encountered. +Do not use the escape character +.Sq \e +anywhere in the definition of +.Ar endmacro ; +it would cause very strange behaviour. +.Pp +When the +.Ar endmacro +is a roff request or a roff macro, like in +.Pp +.D1 \&.ig if +.Pp +the subsequent invocation of +.Ic \&if +will first terminate the +.Ar ignored text , +then be invoked as usual. +Otherwise, it only terminates the +.Ar ignored text , +and arguments following it or the +.Sq \&.. +request are discarded. +.It Ic \&in Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Change indentation. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.It Ic \&index Ar register stringname substring +Find a substring in a string. +This is a Heirloom extension and currently unsupported. +.It Ic \&it Ar expression macro +Set an input line trap. +The named +.Ar macro +will be invoked after processing the number of input text lines +specified by the numerical +.Ar expression . +While evaluating the +.Ar expression , +the unit suffixes described below +.Sx Scaling Widths +are ignored. +.It Ic \&itc Ar expression macro +Set an input line trap, not counting lines ending with \ec. +Currently unsupported. +.It Ic \&IX Ar class keystring +To support the generation of a table of contents, +.Xr pod2man 1 +emits this user-defined macro, usually without defining it. +To avoid reporting large numbers of spurious errors, +.Xr mandoc 1 +ignores it. +.It Ic \&kern Op Cm 1 | 0 +Switch kerning on or off. +Currently ignored. +.It Ic \&kernafter Ar font char ... afmunits ... +Increase kerning after some characters. +This is a Heirloom extension and currently ignored. +.It Ic \&kernbefore Ar font char ... afmunits ... +Increase kerning before some characters. +This is a Heirloom extension and currently ignored. +.It Ic \&kernpair Ar font char ... font char ... afmunits +Add a kerning pair to the kerning table. +This is a Heirloom extension and currently ignored. +.It Ic \&lc Op Ar glyph +Define a leader repetition character. +Currently unsupported. +.It Ic \&lc_ctype Ar localename +Set the +.Dv LC_CTYPE +locale. +This is a Heirloom extension and currently unsupported. +.It Ic \&lds Ar macroname string +Define a local string. +This is a Heirloom extension and currently unsupported. +.It Ic \&length Ar register string +Count the number of input characters in a string. +Currently unsupported. +.It Ic \&letadj Ar lspmin lshmin letss lspmax lshmax +Dynamic letter spacing and reshaping. +This is a Heirloom extension and currently ignored. +.It Ic \&lf Ar lineno Op Ar filename +Change the line number for error messages. +Ignored because insecure. +.It Ic \&lg Op Cm 1 | 0 +Switch the ligature mechanism on or off. +Currently ignored. +.It Ic \&lhang Ar font char ... afmunits +Hang characters at left margin. +This is a Heirloom extension and currently ignored. +.It Ic \&linetabs Op Cm 1 | 0 +Enable or disable line-tabs mode. +This is a groff extension and currently unsupported. +.It Ic \&ll Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Change the output line length. +If the +.Ar width +argument is omitted, the line length is reset to its previous value. +The default setting for terminal output is 78n. +If a sign is given, the line length is added to or subtracted from; +otherwise, it is set to the provided value. +Using this request in new manuals is discouraged for several reasons, +among others because it overrides the +.Xr mandoc 1 +.Fl O Cm width +command line option. +.It Ic \&lnr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment +Set local number register. +This is a Heirloom extension and currently unsupported. +.It Ic \&lnrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment +Set local floating-point register. +This is a Heirloom extension and currently unsupported. +.It Ic \&lpfx Ar string +Set a line prefix. +This is a Heirloom extension and currently unsupported. +.It Ic \&ls Op Ar factor +Set line spacing. +It takes one integer argument specifying the vertical distance of +subsequent output text lines measured in v units. +Currently ignored. +.It Ic \&lsm Ar macroname +Set a leading spaces trap. +This is a groff extension and currently unsupported. +.It Ic \< Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Set title line length. +Currently ignored. +.It Ic \&mc Ar glyph Op Ar dist +Print margin character in the right margin. +The +.Ar dist +is currently ignored; instead, 1n is used. +.It Ic \&mediasize Ar media +Set the device media size. +This is a Heirloom extension and currently ignored. +.It Ic \&minss Ar width +Set minimum word space. +This is a Heirloom extension and currently ignored. +.It Ic \&mk Op Ar register +Mark vertical position. +Currently ignored. +.It Ic \&mso Ar filename +Load a macro file using the search path. +Ignored because insecure. +.It Ic \&na +Disable adjusting without changing the adjustment mode. +Currently ignored. +.It Ic \&ne Op Ar height +Declare the need for the specified minimum vertical space +before the next trap or the bottom of the page. +Currently ignored. +.It Ic \&nf +Break the output line and switch to no-fill mode. +Subsequent input lines are kept together on the same output line +even when exceeding the right margin, +and line breaks in subsequent input cause output line breaks. +This request is implied by the +.Xr mdoc 7 +.Ic \&Bd Fl unfilled +and +.Ic \&Bd Fl literal +macros and by the +.Xr man 7 +.Ic \&EX +macro. +The +.Ic \&fi +request switches back to the default fill mode. +.It Ic \&nh +Turn off automatic hyphenation mode. +Currently ignored. +.It Ic \&nhychar Ar char ... +Define hyphenation-inhibiting characters. +This is a Heirloom extension and currently ignored. +.It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent +Print line numbers. +Currently unsupported. +.It Ic \&nn Op Ar number +Temporarily turn off line numbering. +Currently unsupported. +.It Ic \&nop Ar body +Execute the rest of the input line as a request, macro, or text line, +skipping the +.Ic \&nop +request and any space characters immediately following it. +This is mostly used to indent text lines inside macro definitions. +.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize +Define or change a register. +A register is an arbitrary string value that defines some sort of state, +which influences parsing and/or formatting. +For the syntax of +.Ar expression , +see +.Sx Numerical expressions +below. +If it is prefixed by a sign, the register will be +incremented or decremented instead of assigned to. +.Pp +The +.Ar stepsize +is used by the +.Ic \en+ +auto-increment feature. +It remains unchanged when omitted while changing an existing register, +and it defaults to 0 when defining a new register. +.Pp +The following +.Ar register +is handled specially: +.Bl -tag -width Ds +.It Cm nS +If set to a positive integer value, certain +.Xr mdoc 7 +macros will behave in the same way as in the +.Em SYNOPSIS +section. +If set to 0, these macros will behave in the same way as outside the +.Em SYNOPSIS +section, even when called within the +.Em SYNOPSIS +section itself. +Note that starting a new +.Xr mdoc 7 +section with the +.Ic \&Sh +macro will reset this register. +.El +.It Xo +.Ic \&nrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression +.Op Ar increment +.Xc +Define or change a floating-point register. +This is a Heirloom extension and currently unsupported. +.It Ic \&nroff +Force nroff mode. +This is a groff extension and currently ignored. +.It Ic \&ns +Turn on no-space mode. +Currently ignored. +.It Ic \&nx Op Ar filename +Abort processing of the current input file and process another one. +Ignored because insecure. +.It Ic \&open Ar stream file +Open a file for writing. +Ignored because insecure. +.It Ic \&opena Ar stream file +Open a file for appending. +Ignored because insecure. +.It Ic \&os +Output saved vertical space. +Currently ignored. +.It Ic \&output Ar string +Output directly to intermediate output. +Not supported. +.It Ic \&padj Op Cm 1 | 0 +Globally control paragraph-at-once adjustment. +This is a Heirloom extension and currently ignored. +.It Ic \&papersize Ar media +Set the paper size. +This is a Heirloom extension and currently ignored. +.It Ic \&pc Op Ar char +Change the page number character. +Currently ignored. +.It Ic \&pev +Print environments. +This is a groff extension and currently ignored. +.It Ic \&pi Ar command +Pipe output to a shell command. +Ignored because insecure. +.It Ic \&PI +Low-level request used by +.Ic \&BP . +This is a Heirloom extension and currently unsupported. +.It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change page length. +Currently ignored. +.It Ic \&pm +Print names and sizes of macros, strings, and diversions +to standard error output. +Currently ignored. +.It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number +Change the page number of the next page. +Currently ignored. +.It Ic \&pnr +Print all number registers on standard error output. +Currently ignored. +.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset +Set a horizontal page offset. +If no argument is specified, the page offset is reverted to its +previous value. +If a sign is specified, the new page offset is calculated relative +to the current one; otherwise, it is absolute. +The argument follows the syntax of +.Sx Scaling Widths +and the default scaling unit is +.Cm m . +.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size +Change point size. +Currently ignored. +.It Ic \&psbb Ar filename +Retrieve the bounding box of a PostScript file. +Currently unsupported. +.It Ic \&pshape Ar indent length ... +Set a special shape for the current paragraph. +This is a Heirloom extension and currently unsupported. +.It Ic \&pso Ar command +Include output of a shell command. +Ignored because insecure. +.It Ic \&ptr +Print the names and positions of all traps on standard error output. +This is a groff extension and currently ignored. +.It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change post-vertical spacing. +This is a groff extension and currently ignored. +.It Ic \&rchar Ar glyph ... +Remove glyph definitions. +Currently unsupported. +.It Ic \&rd Op Ar prompt Op Ar argument ... +Read from standard input. +Currently ignored. +.It Ic \&recursionlimit Ar maxrec maxtail +Set the maximum stack depth for recursive macros. +This is a Heirloom extension and currently ignored. +.It Ic \&return Op Ar twice +Exit the presently executed macro and return to the caller. +The argument is currently ignored. +.It Ic \&rfschar Ar font glyph ... +Remove font-specific fallback glyph definitions. +Currently unsupported. +.It Ic \&rhang Ar font char ... afmunits +Hang characters at right margin. +This is a Heirloom extension and currently ignored. +.It Ic \&rj Op Ar N +Justify the next +.Ar N +input lines to the right margin without filling. +.Ar N +defaults to 1. +An argument of 0 or less ends right adjustment. +.It Ic \&rm Ar macroname +Remove a request, macro or string. +.It Ic \&rn Ar oldname newname +Rename a request, macro, diversion, or string. +In +.Xr mandoc 1 , +user-defined macros, +.Xr mdoc 7 +and +.Xr man 7 +macros, and user-defined strings can be renamed, but renaming of +predefined strings and of +.Nm +requests is not supported, and diversions are not implemented at all. +.It Ic \&rnn Ar oldname newname +Rename a number register. +Currently unsupported. +.It Ic \&rr Ar register +Remove a register. +.It Ic \&rs +End no-space mode. +Currently ignored. +.It Ic \&rt Op Ar dist +Return to marked vertical position. +Currently ignored. +.It Ic \&schar Ar glyph Op Ar string +Define global fallback glyph. +This is a groff extension and currently unsupported. +.It Ic \&sentchar Ar char ... +Define sentence-ending characters. +This is a Heirloom extension and currently ignored. +.It Ic \&shc Op Ar glyph +Change the soft hyphen character. +Currently ignored. +.It Ic \&shift Op Ar number +Shift macro arguments +.Ar number +times, by default once: \e\e$i becomes what \e\e$i+number was. +Also decrement \en(.$ by +.Ar number . +.It Ic \&sizes Ar size ... +Define permissible point sizes. +This is a groff extension and currently ignored. +.It Ic \&so Ar filename +Include a source file. +The file is read and its contents processed as input in place of the +.Ic \&so +request line. +To avoid inadvertent inclusion of unrelated files, +.Xr mandoc 1 +only accepts relative paths not containing the strings +.Qq ../ +and +.Qq /.. . +.Pp +This request requires +.Xr man 1 +to change to the right directory before calling +.Xr mandoc 1 , +per convention to the root of the manual tree. +Typical usage looks like: +.Pp +.Dl \&.so man3/Xcursor.3 +.Pp +As the whole concept is rather fragile, the use of +.Ic \&so +is discouraged. +Use +.Xr ln 1 +instead. +.It Ic \&sp Op Ar height +Break the output line and emit vertical space. +The argument follows the syntax of +.Sx Scaling Widths +and defaults to one blank line +.Pq Li 1v . +.It Ic \&spacewidth Op Cm 1 | 0 +Set the space width from the font metrics file. +This is a Heirloom extension and currently ignored. +.It Ic \&special Op Ar font ... +Define a special font. +This is a groff extension and currently ignored. +.It Ic \&spreadwarn Op Ar width +Warn about wide spacing between words. +Currently ignored. +.It Ic \&ss Ar wordspace Op Ar sentencespace +Set space character size. +Currently ignored. +.It Ic \&sty Ar position style +Associate style with a font position. +This is a groff extension and currently ignored. +.It Ic \&substring Ar stringname startpos Op Ar endpos +Replace a user-defined string with a substring. +Currently unsupported. +.It Ic \&sv Op Ar height +Save vertical space. +Currently ignored. +.It Ic \&sy Ar command +Execute shell command. +Ignored because insecure. +.It Ic \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Ic \&TS . +.It Ic \&ta Op Ar width ... Op Cm T Ar width ... +Set tab stops. +Each +.Ar width +argument follows the syntax of +.Sx Scaling Widths . +If prefixed by a plus sign, it is relative to the previous tab stop. +The arguments after the +.Cm T +marker are used repeatedly as often as needed; for each reuse, +they are taken relative to the last previously established tab stop. +When +.Ic \&ta +is called without arguments, all tab stops are cleared. +.It Ic \&tc Op Ar glyph +Change tab repetition character. +Currently unsupported. +.It Ic \&TE +End a table context. +See +.Ic \&TS . +.It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width +Break the output line and indent the next output line by +.Ar width . +If a sign is specified, the temporary indentation is calculated +relative to the current indentation; otherwise, it is absolute. +The argument follows the syntax of +.Sx Scaling Widths +and the default scaling unit is +.Cm m . +.It Ic \&tkf Ar font minps width1 maxps width2 +Enable track kerning for a font. +Currently ignored. +.It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap +Print a title line. +Currently unsupported. +.It Ic \&tm Ar string +Print to standard error output. +Currently ignored. +.It Ic \&tm1 Ar string +Print to standard error output, allowing leading blanks. +This is a groff extension and currently ignored. +.It Ic \&tmc Ar string +Print to standard error output without a trailing newline. +This is a groff extension and currently ignored. +.It Ic \&tr Ar glyph glyph ... +Output character translation. +The first glyph in each pair is replaced by the second one. +Character escapes can be used; for example, +.Pp +.Dl tr \e(xx\e(yy +.Pp +replaces all invocations of \e(xx with \e(yy. +.It Ic \&track Ar font minps width1 maxps width2 +Static letter space tracking. +This is a Heirloom extension and currently ignored. +.It Ic \&transchar Ar char ... +Define transparent characters for sentence-ending. +This is a Heirloom extension and currently ignored. +.It Ic \&trf Ar filename +Output the contents of a file, disallowing invalid characters. +This is a groff extension and ignored because insecure. +.It Ic \&trimat Ar left top width height +Set the TrimBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.It Ic \&trin Ar glyph glyph ... +Output character translation, ignored by +.Ic \&asciify . +Currently unsupported. +.It Ic \&trnt Ar glyph glyph ... +Output character translation, ignored by \e!. +Currently unsupported. +.It Ic \&troff +Force troff mode. +This is a groff extension and currently ignored. +.It Ic \&TS +Begin a table, which formats input in aligned rows and columns. +See +.Xr tbl 7 +for a description of the tbl language. +.It Ic \&uf Ar font +Globally set the underline font. +Currently ignored. +.It Ic \&ul Op Ar N +Underline next +.Ar N +input lines. +Currently ignored. +.It Ic \&unformat Ar divname +Unformat spaces and tabs in a diversion. +Currently unsupported. +.It Ic \&unwatch Ar macroname +Disable notification for string or macro. +This is a Heirloom extension and currently ignored. +.It Ic \&unwatchn Ar register +Disable notification for register. +This is a Heirloom extension and currently ignored. +.It Ic \&vpt Op Cm 1 | 0 +Enable or disable vertical position traps. +This is a groff extension and currently ignored. +.It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height +Change vertical spacing. +Currently ignored. +.It Ic \&warn Ar flags +Set warning level. +Currently ignored. +.It Ic \&warnscale Ar si +Set the scaling indicator used in warnings. +This is a groff extension and currently ignored. +.It Ic \&watch Ar macroname +Notify on change of string or macro. +This is a Heirloom extension and currently ignored. +.It Ic \&watchlength Ar maxlength +On change, report the contents of macros and strings +up to the specified length. +This is a Heirloom extension and currently ignored. +.It Ic \&watchn Ar register +Notify on change of register. +This is a Heirloom extension and currently ignored. +.It Ic \&wh Ar dist Op Ar macroname +Set a page location trap. +Currently unsupported. +.It Ic \&while Ar condition body +Repeated execution while a +.Ar condition +is true, with syntax similar to +.Ic \&if . +Currently implemented with two restrictions: cannot nest, +and each loop must start and end in the same scope. +.It Ic \&write Oo \(dq Oc Ns Ar string +Write to an open file. +Ignored because insecure. +.It Ic \&writec Oo \(dq Oc Ns Ar string +Write to an open file without appending a newline. +Ignored because insecure. +.It Ic \&writem Ar macroname +Write macro or string to an open file. +Ignored because insecure. +.It Ic \&xflag Ar level +Set the extension level. +This is a Heirloom extension and currently ignored. +.El +.Ss Numerical expressions +The +.Ic \&nr , +.Ic \&if , +and +.Ic \&ie +requests accept integer numerical expressions as arguments. +These are always evaluated using the C +.Vt int +type; integer overflow works the same way as in the C language. +Numbers consist of an arbitrary number of digits +.Sq 0 +to +.Sq 9 +prefixed by an optional sign +.Sq + +or +.Sq - . +Each number may be followed by one optional scaling unit described below +.Sx Scaling Widths . +The following equations hold: +.Bd -literal -offset indent +1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240 +254c = 100i = 24000u = 24000 +1f = 65536u = 65536 +.Ed +.Pp +The following binary operators are implemented. +Unless otherwise stated, they behave as in the C language: +.Pp +.Bl -tag -width 2n -compact +.It Ic + +addition +.It Ic - +subtraction +.It Ic * +multiplication +.It Ic / +division +.It Ic % +remainder of division +.It Ic < +less than +.It Ic > +greater than +.It Ic == +equal to +.It Ic = +equal to, same effect as +.Ic == +(this differs from C) +.It Ic <= +less than or equal to +.It Ic >= +greater than or equal to +.It Ic <> +not equal to (corresponds to C +.Ic != ; +this one is of limited portability, it is supported by Heirloom roff, +but not by groff) +.It Ic & +logical and (corresponds to C +.Ic && ) +.It Ic \&: +logical or (corresponds to C +.Ic || ) +.It Ic <? +minimum (not available in C) +.It Ic >? +maximum (not available in C) +.El +.Pp +There is no concept of precedence; evaluation proceeds from left to right, +except when subexpressions are enclosed in parentheses. +Inside parentheses, whitespace is ignored. +.Sh ESCAPE SEQUENCE REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following escape sequences. +In +.Xr mdoc 7 +and +.Xr man 7 +documents, using escape sequences is discouraged except for those +described in the +.Sx LANGUAGE SYNTAX +section above. +.Pp +A backslash followed by any character not listed here +simply prints that character itself. +.Bl -tag -width Ds +.It Ic \e<newline> +A backslash at the end of an input line can be used to continue the +logical input line on the next physical input line, joining the text +on both lines together as if it were on a single input line. +.It Ic \e<space> +The escape sequence backslash-space +.Pq Sq \e\ \& +is an unpaddable space-sized non-breaking space character; see +.Sx Whitespace +and +.Xr mandoc_char 7 . +.It Ic \e! +Embed text up to and including the end of the input line into the +current diversion or into intermediate output without interpreting +requests, macros, and escapes. +Currently unsupported. +.It Ic \e\(dq +The rest of the input line is treated as +.Sx Comments . +.It Ic \e# +Line continuation with comment. +Discard the rest of the physical input line and continue the logical +input line on the next physical input line, joining the text on +both lines together as if it were on a single input line. +This is a groff extension. +.It Ic \e$ Ns Ar arg +Macro argument expansion, see +.Ic \&de . +.It Ic \e% +Hyphenation allowed at this point of the word; ignored by +.Xr mandoc 1 . +.It Ic \e& +Non-printing zero-width character, +often used for various kinds of escaping; see +.Sx Whitespace , +.Xr mandoc_char 7 , +and the +.Dq MACRO SYNTAX +and +.Dq Delimiters +sections in +.Xr mdoc 7 . +.It Ic \e\(aq +Acute accent special character; use +.Ic \e(aa +instead. +.It Ic \e( Ns Ar cc +.Sx Special Characters +with two-letter names, see +.Xr mandoc_char 7 . +.It Ic \e) +Zero-width space transparent to end-of-sentence detection; +ignored by +.Xr mandoc 1 . +.It Ic \e*[ Ns Ar name Ns Ic \&] +Interpolate the string with the +.Ar name . +For short names, there are variants +.Ic \e* Ns Ar c +and +.Ic \e*( Ns Ar cc . +.Pp +One string is predefined on the +.Nm +language level: +.Ic \e*(.T +expands to the name of the output device, +for example ascii, utf8, ps, pdf, html, or markdown. +.Pp +Macro sets traditionally predefine additional strings which are not +portable and differ across implementations. +Those supported by +.Xr mandoc 1 +are listed in +.Xr mandoc_char 7 . +.Pp +Strings can be defined, changed, and deleted with the +.Ic \&ds , +.Ic \&as , +and +.Ic \&rm +requests. +.It Ic \e, +Left italic correction (groff extension); ignored by +.Xr mandoc 1 . +.It Ic \e- +Special character +.Dq mathematical minus sign ; +see +.Xr mandoc_char 7 +for details. +.It Ic \e/ +Right italic correction (groff extension); ignored by +.Xr mandoc 1 . +.It Ic \e: +Breaking the line is allowed at this point of the word +without inserting a hyphen. +.It Ic \e? +Embed the text up to the next +.Ic \e? +into the current diversion without interpreting requests, macros, +and escapes. +This is a groff extension and currently unsupported. +.It Ic \e[ Ns Ar name Ns Ic \&] +.Sx Special Characters +with names of arbitrary length, see +.Xr mandoc_char 7 . +.It Ic \e^ +One-twelfth em half-narrow space character, effectively zero-width in +.Xr mandoc 1 . +.It Ic \e_ +Underline special character; use +.Ic \e(ul +instead. +.It Ic \e` +Grave accent special character; use +.Ic \e(ga +instead. +.It Ic \e{ +Begin conditional input; see +.Ic \&if . +.It Ic \e\(ba +One-sixth em narrow space character, effectively zero-width in +.Xr mandoc 1 . +.It Ic \e} +End conditional input; see +.Ic \&if . +.It Ic \e~ +Paddable non-breaking space character. +.It Ic \e0 +Digit width space character. +.It Ic \eA\(aq Ns Ar string Ns Ic \(aq +Anchor definition; ignored by +.Xr mandoc 1 . +.It Ic \ea +Leader character; ignored by +.Xr mandoc 1 . +.It Ic \eB\(aq Ns Ar string Ns Ic \(aq +Interpolate +.Sq 1 +if +.Ar string +conforms to the syntax of +.Sx Numerical expressions +explained above or +.Sq 0 +otherwise. +.It Ic \eb\(aq Ns Ar string Ns Ic \(aq +Bracket building function; ignored by +.Xr mandoc 1 . +.It Ic \eC\(aq Ns Ar name Ns Ic \(aq +.Sx Special Characters +with names of arbitrary length. +.It Ic \ec +When encountered at the end of an input text line, +the next input text line is considered to continue that line, +even if there are request or macro lines in between. +No whitespace is inserted. +.It Ic \eD\(aq Ns Ar string Ns Ic \(aq +Draw graphics function; ignored by +.Xr mandoc 1 . +.It Ic \ed +Move down by half a line; ignored by +.Xr mandoc 1 . +.It Ic \eE +Escape character intended to not be interpreted in copy mode. +In +.Xr mandoc 1 , +it currently does the same as +.Ic \e +itself. +.It Ic \ee +Backslash special character. +.It Ic \eF[ Ns Ar name Ns Ic \&] +Switch font family (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eF Ns Ar c +and +.Ic \eF( Ns Ar cc . +.It Ic \ef[ Ns Ar name Ns Ic \&] +Switch to the font +.Ar name , +see +.Sx Font Selection . +For short names, there are variants +.Ic \ef Ns Ar c +and +.Ic \ef( Ns Ar cc . +An empty name +.Ic \ef[] +defaults to +.Ic \efP . +.It Ic \eg[ Ns Ar name Ns Ic \&] +Interpolate the format of a number register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eg Ns Ar c +and +.Ic \eg( Ns Ar cc . +.It Ic \eH\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq +Set the height of the current font; ignored by +.Xr mandoc 1 . +.It Ic \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns Ic \(aq +Horizontal motion. +If the vertical bar is given, the motion is relative to the current +indentation. +Otherwise, it is relative to the current position. +The default scaling unit is +.Cm m . +.It Ic \ek[ Ns Ar name Ns Ic \&] +Mark horizontal input place in register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \ek Ns Ar c +and +.Ic \ek( Ns Ar cc . +.It Ic \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns Ic \(aq +Vertical line drawing function; ignored by +.Xr mandoc 1 . +.It Ic \el\(aq Ns Ar width Ns Oo Ar c Oc Ns Ic \(aq +Draw a horizontal line of +.Ar width +using the glyph +.Ar c . +.It Ic \eM[ Ns Ar name Ns Ic \&] +Set fill (background) color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eM Ns Ar c +and +.Ic \eM( Ns Ar cc . +.It Ic \em[ Ns Ar name Ns Ic \&] +Set glyph drawing color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \em Ns Ar c +and +.Ic \em( Ns Ar cc . +.It Ic \eN\(aq Ns Ar number Ns Ic \(aq +Character +.Ar number +on the current font. +.It Ic \en Ns Oo +|- Oc Ns Ic \&[ Ns Ar name Ns Ic \&] +Interpolate the number register +.Ar name . +For short names, there are variants +.Ic \en Ns Ar c +and +.Ic \en( Ns Ar cc . +If the optional sign is specified, +the register is first incremented or decremented by the +.Ar stepsize +that was specified in the relevant +.Ic \&nr +request, and the changed value is interpolated. +.It Ic \eO Ns Ar digit , Ic \eO[5 Ns arguments Ns Ic \&] +Suppress output. +This is a groff extension and currently unsupported. +With an argument of +.Ic 1 , 2 , 3 , +or +.Ic 4 , +it is ignored. +.It Ic \eo\(aq Ns Ar string Ns Ic \(aq +Overstrike, writing all the characters contained in the +.Ar string +to the same output position. +In terminal and HTML output modes, +only the last one of the characters is visible. +.It Ic \ep +Break the output line at the end of the current word. +.It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq +Set number register; ignored by +.Xr mandoc 1 . +.It Ic \er +Move up by one line; ignored by +.Xr mandoc 1 . +.It Ic \eS\(aq Ns Ar number Ns Ic \(aq +Slant output; ignored by +.Xr mandoc 1 . +.It Ic \es\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq +Change point size; ignored by +.Xr mandoc 1 . +Alternative forms +.Ic \es Ns Oo +|- Oc Ns Ar n , +.Ic \es Ns Oo +|- Oc Ns Ic \(aq Ns Ar number Ns Ic \(aq , +.Ic \es[ Ns Oo +|- Oc Ns Ar number Ns Ic \&] , +and +.Ic \es Ns Oo +|- Oc Ns Ic \&[ Ns Ar number Ns Ic \&] +are also parsed and ignored. +.It Ic \et +Horizontal tab; ignored by +.Xr mandoc 1 . +.It Ic \eu +Move up by half a line; ignored by +.Xr mandoc 1 . +.It Ic \eV[ Ns Ar name Ns Ic \&] +Interpolate an environment variable; ignored by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eV Ns Ar c +and +.Ic \eV( Ns Ar cc . +.It Ic \ev\(aq Ns Ar number Ns Ic \(aq +Vertical motion; ignored by +.Xr mandoc 1 . +.It Ic \ew\(aq Ns Ar string Ns Ic \(aq +Interpolate the width of the +.Ar string . +The +.Xr mandoc 1 +implementation assumes that after expansion of user-defined strings, the +.Ar string +only contains normal characters, no escape sequences, and that each +character has a width of 24 basic units. +.It Ic \eX\(aq Ns Ar string Ns Ic \(aq +Output +.Ar string +as device control function; ignored in nroff mode and by +.Xr mandoc 1 . +.It Ic \ex\(aq Ns Ar number Ns Ic \(aq +Extra line space function; ignored by +.Xr mandoc 1 . +.It Ic \eY[ Ns Ar name Ns Ic \&] +Output a string as a device control function; ignored in nroff mode and by +.Xr mandoc 1 . +For short names, there are variants +.Ic \eY Ns Ar c +and +.Ic \eY( Ns Ar cc . +.It Ic \eZ\(aq Ns Ar string Ns Ic \(aq +Print +.Ar string +with zero width and height; ignored by +.Xr mandoc 1 . +.It Ic \ez +Output the next character without advancing the cursor position. +.El +.Sh COMPATIBILITY +The +.Xr mandoc 1 +implementation of the +.Nm +language is incomplete. +Major unimplemented features include: +.Pp +.Bl -dash -compact +.It +For security reasons, +.Xr mandoc 1 +never reads or writes external files except via +.Ic \&so +requests with safe relative paths. +.It +There is no automatic hyphenation, no adjustment to the right margin, +and very limited support for centering; the output is always set flush-left. +.It +Support for setting tabulator and leader characters is missing, +and support for manually changing indentation is limited. +.It +The +.Sq u +scaling unit is the default terminal unit. +In traditional troff systems, this unit changes depending on the +output media. +.It +Width measurements are implemented in a crude way +and often yield wrong results. +Support for explicit movement requests and escapes is limited. +.It +There is no concept of output pages, no support for floats, +graphics drawing, and picture inclusion; +terminal output is always continuous. +.It +Requests regarding color, font families, font sizes, +and glyph manipulation are ignored. +Font support is very limited. +Kerning is not implemented, and no ligatures are produced. +.It +The +.Qq \(aq +macro control character does not suppress output line breaks. +.It +Diversions and environments are not implemented, +and support for traps is very incomplete. +.It +Use of macros is not supported inside +.Xr tbl 7 +code. +.El +.Pp +The special semantics of the +.Cm nS +number register is an idiosyncrasy of +.Ox +manuals and not supported by other +.Xr mdoc 7 +implementations. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mdoc 7 , +.Xr tbl 7 +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%I AT&T Bell Laboratories +.%T Troff User's Manual +.%R Computing Science Technical Report +.%N 54 +.%C Murray Hill, New Jersey +.%D 1976 and 1992 +.%U http://www.kohala.com/start/troff/cstr54.ps +.Re +.Rs +.%A Joseph F. Ossanna +.%A Brian W. Kernighan +.%A Gunnar Ritter +.%T Heirloom Documentation Tools Nroff/Troff User's Manual +.%D September 17, 2007 +.%U http://heirloom.sourceforge.net/doctools/troff.pdf +.Re +.Sh HISTORY +The RUNOFF typesetting system, whose input forms the basis for +.Nm , +was written in MAD and FAP for the CTSS operating system by Jerome E. +Saltzer in 1964. +Doug McIlroy rewrote it in BCPL in 1969, renaming it +.Nm . +Dennis M. Ritchie rewrote McIlroy's +.Nm +in PDP-11 assembly for +.At v1 , +Joseph F. Ossanna improved roff and renamed it nroff +for +.At v2 , +then ported nroff to C as troff, which Brian W. Kernighan released with +.At v7 . +In 1989, James Clark re-implemented troff in C++, naming it groff. +.Sh AUTHORS +.An -nosplit +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . diff --git a/usr/src/man/man7/mansun.7 b/usr/src/man/man7/mansun.7 new file mode 100644 index 0000000000..e5330e7302 --- /dev/null +++ b/usr/src/man/man7/mansun.7 @@ -0,0 +1,316 @@ +'\" te +.\" Copyright (c) 2017 Peter Tribble. +.\" Copyright (c) 1992, Sun Microsystems, 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 MANSUN 7 "Apr 2, 2017" +.SH NAME +mansun \- macros to format Reference Manual pages +.SH SYNOPSIS +.LP +.nf +\fBnroff\fR \fB-mansun\fR \fIfilename\fR... +.fi + +.LP +.nf +\fBtroff\fR \fB-mansun\fR \fIfilename\fR... +.fi + +.SH DESCRIPTION +.LP +These macros are used to lay out the reference pages in this manual. Note: if +\fIfilename\fR contains format input for a preprocessor, the commands shown +above must be piped through the appropriate preprocessor. This is handled +automatically by \fBman\fR(1). See the ``Conventions'' section. +.sp +.LP +Any text argument \fIt\fR may be zero to six words. Quotes may be used to +include SPACE characters in a "word". If \fItext\fR is empty, the special +treatment is applied to the next input line with text to be printed. In this +way \fB\&.I\fR may be used to italicize a whole line, or \fB\&.SB\fR may be +used to make small bold letters. +.sp +.LP +A prevailing indent distance is remembered between successive indented +paragraphs, and is reset to default value upon reaching a non-indented +paragraph. Default units for indents \fIi\fR are ens. +.sp +.LP +Type font and size are reset to default values before each paragraph, and after +processing font and size setting macros. +.sp +.LP +These strings are predefined by \fB-mansun\fR: +.sp +.ne 2 +.na +\fB\fB\e*R\fR\fR +.ad +.RS 8n +`\(rg', `(Reg)' in \fBnroff\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB\e*S\fR\fR +.ad +.RS 8n +Change to default type size. +.RE + +.SS "Requests" +.LP +* n.t.l. = next text line; p.i. = prevailing indent +.sp + +.sp +.TS +c c c c +c c c c . +\fIRequest\fR \fICause\fR \fIIf no\fR \fIExplanation\fR + \fIBreak\fR \fIArgument\fR +\fB\&.B \fR\fIt\fR no \fIt\fR=n.t.l.* Text is in bold font. +\fB\&.BI \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating bold and italic. +\fB\&.BR \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating bold and Roman. +\fB\&.DT\fR no \&.5i 1i... Restore default tabs. +\fB\&.HP \fR\fIi\fR yes \fIi\fR=p.i.* T{ +Begin paragraph with hanging indent. Set prevailing indent to \fIi\fR. +T} +\fB\&.I \fR\fIt\fR no \fIt\fR=n.t.l. Text is italic. +\fB\&.IB \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating italic and bold. +\fB\&.IP \fR\fIx i\fR yes \fIx\fR="" Same as \fB\&.TP\fR with tag \fIx\fR. +\fB\&.IR \fR\fIt\fR no \fIt\fR=n.t.l. T{ +Join words, alternating italic and Roman. +T} +\fB\&.IX \fR\fIt\fR no - Index macro, for SunSoft internal use. +\fB\&.LP\fR yes - T{ +Begin left-aligned paragraph. Set prevailing indent to .5i. +T} +\fB\&.P\fR yes - Same as \fB\&.LP\fR. +\fB\&.PD \fR\fId\fR no \fId\fR=.4v T{ +Set vertical distance between paragraphs. +T} +\fB\&.PP\fR yes - Same as \fB\&.LP\fR. +\fB\&.RE\fR yes - T{ +End of relative indent. Restores prevailing indent. +T} +\fB\&.RB \fR\fIt\fR no \fIt\fR=n.t.l. Join words, alternating Roman and bold. +\fB\&.RI \fR\fIt\fR no \fIt\fR=n.t.l. T{ +Join words, alternating Roman and italic. +T} +\fB\&.RS \fR\fIi\fR yes \fIi\fR=p.i. T{ +Start relative indent, increase indent by \fIi\fR. Sets prevailing indent to .5i for nested indents. +T} +\fB\&.SB \fR\fIt\fR no - T{ +Reduce size of text by 1 point, make text bold. +T} +\fB\&.SH \fR\fIt\fR yes - Section Heading. +\fB\&.SM \fR\fIt\fR no \fIt\fR=n.t.l. Reduce size of text by 1 point. +\fB\&.SS \fR\fIt\fR yes \fIt\fR=n.t.l. Section Subheading. +\fB\&.TH \fR\fIN S "f d, m\fR" +\fB\&.TH \fR\fIn s d f m\fR yes - T{ +Begin reference page \fIn\fR, of of section \fIs\fR; \fId\fR is the date of the most recent change. If present, \fIf\fR is the left page footer; \fIm\fR is the main page (center) header. Sets prevailing indent and tabs to .5i. +T} +\fB\&.TP \fR\fIi\fR yes \fIi\fR=p.i. T{ +Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to \fIi\fR. +T} +\fB\&.TX \fR\fIt \fR\fIp\fR no - T{ +Resolve the title abbreviation \fIt\fR; join to punctuation mark (or text) \fIp\fR. +T} +.TE + +.SS "Conventions" +.LP +When formatting a manual page, \fBmansun\fR examines the first line to +determine whether it requires special processing. For example a first line +consisting of: +.sp +.LP +\fB\&'\e" t\fR +.sp +.LP +indicates that the manual page must be run through the \fBtbl\fR(1) +preprocessor. +.sp +.LP +A typical manual page for a command or function is laid out as follows: +.sp +.ne 2 +.na +\fB\&.TH\fI TITLE \fR[1-8]\fR " , " +.ad +.RS 21n +The name of the command or function, which serves as the title of the manual +page. This is followed by the number of the section in which it appears. +.RE + +.sp +.ne 2 +.na +\fB\&.SH NAME\fR +.ad +.RS 21n +The name, or list of names, by which the command is called, followed by a dash +and then a one-line summary of the action performed. All in Roman font, this +section contains no \fBtroff\fR(1) commands or escapes, and no macro requests. +It is used to generate the \fBwhatis\fR database, which is used by the +\fBwhatis\fR(1) and \fBapropos\fR(1) commands. +.RE + +.sp +.ne 2 +.na +\fB\&.SH SYNOPSIS\fR +.ad +.RS 21n +.sp +.ne 2 +.na +\fBCommands:\fR +.ad +.RS 13n +The syntax of the command and its arguments, as typed on the command line. +When in boldface, a word must be typed exactly as printed. When in italics, a +word can be replaced with an argument that you supply. References to bold or +italicized items are not capitalized in other sections, even when they begin a +sentence. +.sp +Syntactic symbols appear in Roman face: +.sp +.ne 2 +.na +\fB[ ]\fR +.ad +.RS 13n +An argument, when surrounded by brackets is optional. +.RE + +.sp +.ne 2 +.na +\fB|\fR +.ad +.RS 13n +Arguments separated by a vertical bar are exclusive. You can supply only one +item from such a list. +.RE + +.sp +.ne 2 +.na +\fB\&.\|.\|.\fR +.ad +.RS 13n +Arguments followed by an ellipsis can be repeated. When an ellipsis follows a +bracketed set, the expression within the brackets can be repeated. +.RE + +.RE + +.sp +.ne 2 +.na +\fBFunctions:\fR +.ad +.RS 14n +If required, the data declaration, or \fB#include\fR directive, is shown first, +followed by the function declaration. Otherwise, the function declaration is +shown. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\&.SH DESCRIPTION\fR +.ad +.RS 21n +A narrative overview of the command or function's external behavior. This +includes how it interacts with files or data, and how it handles the standard +input, standard output and standard error. Internals and implementation details +are normally omitted. This section attempts to provide a succinct overview in +answer to the question, "what does it do?" +.sp +Literal text from the synopsis appears in constant width, as do literal +filenames and references to items that appear elsewhere in the reference +manuals. Arguments are italicized. +.sp +If a command interprets either subcommands or an input grammar, its command +interface or input grammar is normally described in a \fBUSAGE\fR section, +which follows the \fBOPTIONS\fR section. The \fBDESCRIPTION\fR section only +describes the behavior of the command itself, not that of subcommands. +.RE + +.sp +.ne 2 +.na +\fB\&.SH OPTIONS\fR +.ad +.RS 21n +The list of options along with a description of how each affects the command's +operation. +.RE + +.sp +.ne 2 +.na +\fB\&.SH FILES\fR +.ad +.RS 21n +A list of files associated with the command or function. +.RE + +.sp +.ne 2 +.na +\fB\&.SH SEE ALSO\fR +.ad +.RS 21n +A comma-separated list of related manual pages, followed by references to other +published materials. +.RE + +.sp +.ne 2 +.na +\fB\&.SH DIAGNOSTICS\fR +.ad +.RS 21n +A list of diagnostic messages and an explanation of each. +.RE + +.sp +.ne 2 +.na +\fB\&.SH BUGS\fR +.ad +.RS 21n +A description of limitations, known defects, and possible problems associated +with the command or function. +.RE + +.SH FILES +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/ansun\fR\fR +.ad +.RS 29n + +.RE + +.SH SEE ALSO +.LP +.BR man (1), +.BR nroff (1), +.BR troff (1) +.sp +.LP +Dale Dougherty and Tim O'Reilly, \fIUnix\fR \fIText\fR \fIProcessing\fR + +.SH NOTES +.LP +New manual pages should be coded in the \fBmdoc\fR(7) format. diff --git a/usr/src/man/man7/mdoc.7 b/usr/src/man/man7/mdoc.7 new file mode 100644 index 0000000000..b1c1e15ce0 --- /dev/null +++ b/usr/src/man/man7/mdoc.7 @@ -0,0 +1,3337 @@ +.\" $Id: mdoc.7,v 1.287 2021/07/29 17:32:01 schwarze Exp $ +.\" +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org> +.\" Copyright 2018 Nexenta Systems, Inc. +.\" +.Dd $Mdocdate: July 29 2021 $ +.Dt MDOC 7 +.Os +.Sh NAME +.Nm mdoc +.Nd semantic markup language for formatting manual pages +.Sh DESCRIPTION +The +.Nm mdoc +language supports authoring of manual pages for the +.Xr man 1 +utility by allowing semantic annotations of words, phrases, +page sections and complete manual pages. +Such annotations are used by formatting tools to achieve a uniform +presentation across all manuals written in +.Nm , +and to support hyperlinking if supported by the output medium. +.Pp +This reference document describes the structure of manual pages +and the syntax and usage of the +.Nm +language. +The reference implementation of a parsing and formatting tool is +.Xr mandoc 1 ; +the +.Sx COMPATIBILITY +section describes compatibility with other implementations. +.Pp +In an +.Nm +document, lines beginning with the control character +.Sq \&. +are called +.Dq macro lines . +The first word is the macro name. +It consists of two or three letters. +Most macro names begin with a capital letter. +For a list of available macros, see +.Sx MACRO OVERVIEW . +The words following the macro name are arguments to the macro, optionally +including the names of other, callable macros; see +.Sx MACRO SYNTAX +for details. +.Pp +Lines not beginning with the control character are called +.Dq text lines . +They provide free-form text to be printed; the formatting of the text +depends on the respective processing context: +.Bd -literal -offset indent +\&.Sh Macro lines change control state. +Text lines are interpreted within the current state. +.Ed +.Pp +Many aspects of the basic syntax of the +.Nm +language are based on the +.Xr mandoc_roff 7 +language; see the +.Em LANGUAGE SYNTAX +and +.Em MACRO SYNTAX +sections in the +.Xr mandoc_roff 7 +manual for details, in particular regarding +comments, escape sequences, whitespace, and quoting. +However, using +.Xr mandoc_roff 7 +requests in +.Nm +documents is discouraged; +.Xr mandoc 1 +supports some of them merely for backward compatibility. +.Sh MANUAL STRUCTURE +A well-formed +.Nm +document consists of a document prologue followed by one or more +sections. +.Pp +The prologue, which consists of the +.Ic \&Dd , +.Ic \&Dt , +and +.Ic \&Os +macros in that order, is required for every document. +.Pp +The first section (sections are denoted by +.Ic \&Sh ) +must be the NAME section, consisting of at least one +.Ic \&Nm +followed by +.Ic \&Nd . +.Pp +Following that, convention dictates specifying at least the +.Em SYNOPSIS +and +.Em DESCRIPTION +sections, although this varies between manual sections. +.Pp +The following is a well-formed skeleton +.Nm +file for a utility +.Qq progname : +.Bd -literal -offset indent +\&.Dd Jan 1, 1970 +\&.Dt PROGNAME section +\&.Os +\&.Sh NAME +\&.Nm progname +\&.Nd one line about what it does +\&.\e\(dq .Sh LIBRARY +\&.\e\(dq For sections 2, 3, and 9 only. +\&.Sh SYNOPSIS +\&.Nm progname +\&.Op Fl options +\&.Ar +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\(dq .Sh IMPLEMENTATION NOTES +\&.\e\(dq .Sh RETURN VALUES +\&.\e\(dq For sections 2, 3, 7, and 9 only. +\&.\e\(dq .Sh CONTEXT +\&.\e\(dq For section 9 functions only. +\&.\e\(dq .Sh ENVIRONMENT +\&.\e\(dq For sections 1, 7, and 8. +\&.\e\(dq .Sh FILES +\&.\e\(dq .Sh EXIT STATUS +\&.\e\(dq For sections 1, 7, and 8. +\&.\e\(dq .Sh EXAMPLES +\&.\e\(dq .Sh DIAGNOSTICS +\&.\e\(dq .Sh ERRORS +\&.\e\(dq For sections 2, 3, 4, and 9 only. +\&.\e\(dq .Sh ARCHITECTURE +\&.\e\(dq .Sh CODE SET INDEPENDENCE +\&.\e\(dq For sections 1, 3, and 8 only. +\&.\e\(dq .Sh INTERFACE STABILITY +\&.\e\(dq .Sh MT-LEVEL +\&.\e\(dq For sections 2 and 3 only. +\&.\e\(dq .Sh SECURITY +\&.\e\(dq .Sh SEE ALSO +\&.\e\(dq .Xr foobar 1 +\&.\e\(dq .Sh STANDARDS +\&.\e\(dq .Sh HISTORY +\&.\e\(dq .Sh AUTHORS +\&.\e\(dq .Sh CAVEATS +\&.\e\(dq .Sh BUGS +.Ed +.Pp +The sections in an +.Nm +document are conventionally ordered as they appear above. +Sections should be composed as follows: +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a one line description of the documented material. +The syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 , +\&.Nm name1 , +\&.Nm name2 +\&.Nd a one line description +.Ed +.Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp +The +.Ic \&Nm +macro(s) must precede the +.Ic \&Nd +macro. +.Pp +See +.Ic \&Nm +and +.Ic \&Nd . +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2, 3, or 9 manual. +The syntax for this is as follows: +.Bd -literal -offset indent +\&.Lb libarm +.Ed +.Pp +See +.Ic \&Lb . +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1 and 8), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +Commands should be ordered alphabetically. +.Pp +For the second, function calls (sections 2, 3, 4I, 4P, 9): +.Bd -literal -offset indent +\&.In header.h +\&.Vt extern const char *global; +\&.Ft "char *" +\&.Fn foo "const char *src" +\&.Ft "char *" +\&.Fn bar "const char *src" +.Ed +.Pp +Ordering of +.Ic \&In , +.Ic \&Vt , +.Ic \&Fn , +and +.Ic \&Fo +macros should follow C header-file conventions. +.Pp +And for the third, configurations (section 4D): +.Bd -literal -offset indent +\&.Pa /dev/device_node +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +.Pp +Some macros are displayed differently in the +.Em SYNOPSIS +section, particularly +.Ic \&Nm , +.Ic \&Cd , +.Ic \&Fd , +.Ic \&Fn , +.Ic \&Fo , +.Ic \&In , +.Ic \&Vt , +and +.Ic \&Ft . +All of these macros are output on their own line. +If two such dissimilar macros are pairwise invoked (except for +.Ic \&Ft +before +.Ic \&Fo +or +.Ic \&Fn ) , +they are separated by a vertical space, unless in the case of +.Ic \&Fo , +.Ic \&Fn , +and +.Ic \&Ft , +which are always separated by vertical space. +.Pp +When text and macros following an +.Ic \&Nm +macro starting an input line span multiple output lines, +all output lines but the first will be indented to align +with the text immediately following the +.Ic \&Nm +macro, up to the next +.Ic \&Nm , +.Ic \&Sh , +or +.Ic \&Ss +macro or the end of an enclosing block, whichever comes first. +.It Em DESCRIPTION +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The options are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +.Pp +List the options in alphabetical order, +uppercase before lowercase for each letter and +with no regard to whether an option takes an argument. +Put digits in ascending order before all letter options. +.Pp +Manuals not documenting a command won't include the above fragment. +.Pp +Since the +.Em DESCRIPTION +section usually contains most of the text of a manual, longer manuals +often use the +.Ic \&Ss +macro to form subsections. +In very long manuals, the +.Em DESCRIPTION +may be split into multiple sections, each started by an +.Ic \&Sh +macro followed by a non-standard section name, and each having +several subsections, like in the present +.Nm +manual. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. +This is useful when implementing standard functions that may have side +effects or notable algorithmic implications. +.It Em RETURN VALUES +This section documents the +return values of functions in sections 2, 3, and 9. +.Pp +See +.Ic \&Rv . +.It Em CONTEXT +This section lists the contexts in which functions can be called in section 9. +The contexts are user, kernel, or interrupt. +.It Em ENVIRONMENT +Lists the environment variables used by the utility, +and explains the syntax and semantics of their values. +The +.Xr environ 7 +manual provides examples of typical content and formatting. +.Pp +See +.Ic \&Ev . +.It Em FILES +Documents files used. +It's helpful to document both the file name and a short description of how +the file is used (created, modified, etc.). +.Pp +See +.Ic \&Pa . +.It Em EXIT STATUS +This section documents the +command exit status for sections 1 and 8. +Historically, this information was described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Ic \&Ex . +.It Em EXAMPLES +Example usages. +This often contains snippets of well-formed, well-tested invocations. +Make sure that examples work properly! +.It Em DIAGNOSTICS +Documents error and diagnostic messages displayed to the user or +sent to logs. +Note that exit status and return values should be documented in the +.Em EXIT STATUS +and +.Em RETURN VALUES +sections. +.Pp +See +.Ic \&Bl +.Fl diag . +.It Em ERRORS +Documents error handling in sections 2, 3, 7, and 9. +.Pp +See +.Ic \&Er . +.It Em ARCHITECTURE +This section is usually absent, but will be present when the +interface is specific to one or more architectures. +.It Em CODE SET INDEPENDENCE +Indicates whether the interface operates correctly with various different +code sets. +True independent code sets will support not only ASCII and Extended UNIX +Codesets (EUC), but also other multi-byte encodings such as UTF-8 and GB2312. +.Pp +Generally there will be some limitations that are fairly standard. +See +.Xr standards 7 +for more information about some of these. +Most interfaces should support at least UTF-8 in addition to ASCII. +.It Em INTERFACE STABILITY +Indicates the level of commitment to the interface. +Interfaces can be described with in the following ways: +.Bl -tag -width Ds +.It Nm Standard +Indicates that the interface is defined by one or more standards bodies. +Generally, changes to the interface will be carefully managed to conform +to the relevant standards. +These interfaces are generally the most suitable for use in portable programs. +.It Nm Committed +Indicates that the interface is intended to be preserved for the long-haul, and +will rarely, if ever change, and never without notification (barring +extraordinary and extenuating circumstances). +These interfaces are preferred over other interfaces with the exeception of +.Nm Standard +interfaces. +.It Nm Uncommitted +Indicates that the interface may change. +Generally, changes to these interfaces should be infrequent, and some effort +will be made to address compatibility considerations when changing or removing +such interfaces. +However, there is no firm commitment to the preservation of the interface. +Most often this is applied to interfaces where operational experience with the +interface is still limited and some need to change may be anticipated. +.Pp +Consumers should expect to revalidate any +.Nm Uncommitted +interfaces when crossing release boundaries. +Products intended for use on many releases or intended to support compatibility +with future releases should avoid these interfaces. +.It Nm Volatile +The interface can change at any time for any reason. +Often this relates to interfaces that are part of external software components +that are still evolving rapidly. +Consumers should not expect that the interface (either binary or source level) +will be unchanged from one release to the next. +.It Nm Not-an-Interface +Describes something that is specifically not intended for programmatic +consumption. +For example, specific human-readable output, or the layout of graphical items on +a user interface, may be described this way. +Generally programmatic alternatives to these will be available, and should be +used when programmatic consumption is needed. +.It Nm Private +This is an internal interface. +Generally these interfaces should only be used within the project, and should +not be used by other programs or modules. +The interface can and will change without notice as the project needs, at any +time. +.Pp +Most often, Private interfaces will lack any documentation whatsoever, and +generally any undocumented interface can be assumed to be Private. +.It Nm Obsolete +The interface is not intended for use in new projects or programs, and may +be removed at a future date. +The +.Nm Obsolete +word is a modifier that can +be applied to other commitment levels. +For example an +.Nm Obsolete Committed +interface is unlikely to be removed or changed, but nonetheless new use +is discouraged (perhaps a better newer alternative is present). +.El +.It Em MT-LEVEL +This section describes considerations for the interface when used within +programs that use multiple threads. +More discussion of these considerations is made in the MT-Level section of +.Xr attributes 7 . +The interface can be described in the following ways. +.Bl -tag -width Ds +.It Nm Safe +Indicates the interface is safe for use within multiple threads. +There may be additional caveats that apply, in which case those will be +described. +Note that some interfaces have semantics which may affect other threads, but +these should be an intrinsic part of the interface rather than an unexpected +side effect. +For example, closing a file in one thread will cause that file to be closed in +all threads. +.It Nm Unsafe +Indicates the interface is unsuitable for concurrent use within multiple +threads. +A threaded application may still make use of the interface, but will be required +to provide external synchronization means to ensure that only a single thread +calls the interface at a time. +.It Nm MT-Safe +Indicates that the interface is not only safe for concurrent use, but is +designed for such use. +For example, a +.Nm Safe +interface may make use of a global lock to provide safety, but at reduced +internal concurrency, whereas an +.Nm MT-Safe +interface will be designed to be efficient even when used concurrently. +.It Nm Async-Signal-Safe +Indicates that the library is safe for use within a signal handler. +An +.Nm MT-Safe +interface can be made +.Nm Async-Signal-Safe +by ensuring that it blocks signals when acquiring locks. +.It Nm Safe with Exceptions +As for +.Nm Safe +but with specific exceptions noted. +.It Nm MT-Safe with Exceptions +As for +.Nm MT-Safe +but with specific exceptions noted. +.El +.It Em SECURITY +Documents any security precautions that operators should consider. +.It Em SEE ALSO +References other manuals with related topics. +This section should exist for most manuals. +Cross-references should conventionally be ordered first by section, then +alphabetically (ignoring case). +.Pp +References to other documentation concerning the topic of the manual page, +for example authoritative books or journal articles, may also be +provided in this section. +.Pp +See +.Ic \&Rs +and +.Ic \&Xr . +.It Em STANDARDS +References any standards implemented or used. +If not adhering to any standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Ic \&St . +.It Em HISTORY +A brief history of the subject, including where it was first implemented, +and when it was ported to or reimplemented for the operating system at hand. +.It Em AUTHORS +Credits to the person or persons who wrote the code and/or documentation. +Authors should generally be noted by both name and email address. +.Pp +See +.Ic \&An . +.It Em CAVEATS +Common misuses and misunderstandings should be explained +in this section. +.It Em BUGS +Known bugs, limitations, and work-arounds should be described +in this section. +.El +.Sh MACRO OVERVIEW +This overview is sorted such that macros of similar purpose are listed +together, to help find the best macro for any given purpose. +Deprecated macros are not included in the overview, but can be found below +in the alphabetical +.Sx MACRO REFERENCE . +.Ss Document preamble and NAME section macros +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year +.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch +.It Ic \&Os Ta operating system version: Op Ar system Op Ar version +.It Ic \&Nm Ta document name (one argument) +.It Ic \&Nd Ta document description (one line) +.El +.Ss Sections and cross references +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Sh Ta section header (one line) +.It Ic \&Ss Ta subsection header (one line) +.It Ic \&Sx Ta internal cross reference to a section or subsection +.It Ic \&Xr Ta cross reference to another manual page: Ar name section +.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments +.It Ic \&Pp Ta start a text paragraph (no arguments) +.El +.Ss Displays and lists +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Bd , \&Ed Ta display block: +.Fl Ar type +.Op Fl offset Ar width +.Op Fl compact +.It Ic \&D1 Ta indented display (one line) +.It Ic \&Dl Ta indented literal display (one line) +.It Ic \&Ql Ta in-line literal display: Ql text +.It Ic \&Bl , \&El Ta list block: +.Fl Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.It Ic \&It Ta list item (syntax depends on Fl Ar type ) +.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists +.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) +.El +.Ss Spacing control +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Pf Ta prefix, no following horizontal space (one argument) +.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) +.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) +.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off +.It Ic \&Bk , \&Ek Ta keep block: Fl words +.El +.Ss Semantic markup for command line utilities +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility +.It Ic \&Fl Ta command line options (flags) (>=0 arguments) +.It Ic \&Cm Ta command modifier (>0 arguments) +.It Ic \&Ar Ta command arguments (>=0 arguments) +.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) +.It Ic \&Ic Ta internal or interactive command (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.It Ic \&Pa Ta file system path (>=0 arguments) +.El +.Ss Semantic markup for function libraries +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Lb Ta function library (one argument) +.It Ic \&In Ta include file (one argument) +.It Ic \&Fd Ta other preprocessor directive (>0 arguments) +.It Ic \&Ft Ta function type (>0 arguments) +.It Ic \&Fo , \&Fc Ta function block: Ar funcname +.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... +.It Ic \&Fa Ta function argument (>0 arguments) +.It Ic \&Vt Ta variable type (>0 arguments) +.It Ic \&Va Ta variable name (>0 arguments) +.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) +.It Ic \&Er Ta error constant (>0 arguments) +.It Ic \&Ev Ta environmental variable (>0 arguments) +.El +.Ss Various semantic markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&An Ta author name (>0 arguments) +.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name +.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain +.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) +.It Ic \&Ad Ta memory address (>0 arguments) +.It Ic \&Ms Ta mathematical symbol (>0 arguments) +.El +.Ss Physical markup +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) +.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) +.It Ic \&No Ta return to roman font (normal) (>0 arguments) +.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy +.El +.Ss Physical enclosures +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text +.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text +.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text +.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text +.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text +.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text +.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text +.It Ic \&Eo , \&Ec Ta generic enclosure +.El +.Ss Text production +.Bl -column "Brq, Bro, Brc" description +.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... +.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... +.It Ic \&St Ta reference to a standards document (one argument) +.It Ic \&At Ta At +.It Ic \&Bx Ta Bx +.It Ic \&Bsx Ta Bsx +.It Ic \&Nx Ta Nx +.It Ic \&Fx Ta Fx +.It Ic \&Ox Ta Ox +.It Ic \&Dx Ta Dx +.El +.Sh MACRO REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. +For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.Bl -tag -width 3n +.It Ic \&%A Ar first_name ... last_name +Author name of an +.Ic \&Rs +block. +Multiple authors should each be accorded their own +.Ic \%%A +line. +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. +.It Ic \&%B Ar title +Book title of an +.Ic \&Rs +block. +This macro may also be used in a non-bibliographic context when +referring to book titles. +.It Ic \&%C Ar location +Publication city or location of an +.Ic \&Rs +block. +.It Ic \&%D Oo Ar month day , Oc Ar year +Publication date of an +.Ic \&Rs +block. +Provide the full English name of the +.Ar month +and all four digits of the +.Ar year . +.It Ic \&%I Ar name +Publisher or issuer name of an +.Ic \&Rs +block. +.It Ic \&%J Ar name +Journal name of an +.Ic \&Rs +block. +.It Ic \&%N Ar number +Issue number (usually for journals) of an +.Ic \&Rs +block. +.It Ic \&%O Ar line +Optional information of an +.Ic \&Rs +block. +.It Ic \&%P Ar number +Book or journal page number of an +.Ic \&Rs +block. +Conventionally, the argument starts with +.Ql p.\& +for a single page or +.Ql pp.\& +for a range of pages, for example: +.Pp +.Dl .%P pp. 42\e(en47 +.It Ic \&%Q Ar name +Institutional author (school, government, etc.) of an +.Ic \&Rs +block. +Multiple institutional authors should each be accorded their own +.Ic \&%Q +line. +.It Ic \&%R Ar name +Technical report name of an +.Ic \&Rs +block. +.It Ic \&%T Ar title +Article title of an +.Ic \&Rs +block. +This macro may also be used in a non-bibliographical context when +referring to article titles. +.It Ic \&%U Ar protocol Ns :// Ns Ar path +URI of reference document. +.It Ic \&%V Ar number +Volume number of an +.Ic \&Rs +block. +.It Ic \&Ac +Close an +.Ic \&Ao +block. +Does not have any tail arguments. +.Tg Ad +.It Ic \&Ad Ar address +Memory address. +Do not use this for postal addresses. +.Pp +Examples: +.Dl \&.Ad [0,$] +.Dl \&.Ad 0x00000000 +.Tg An +.It Ic \&An Fl split | nosplit | Ar first_name ... last_name +Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. +Requires either the name of an author or one of the following arguments: +.Pp +.Bl -tag -width "-nosplitX" -offset indent -compact +.It Fl split +Start a new output line before each subsequent invocation of +.Ic \&An . +.It Fl nosplit +The opposite of +.Fl split . +.El +.Pp +The default is +.Fl nosplit . +The effect of selecting either of the +.Fl split +modes ends at the beginning of the +.Em AUTHORS +section. +In the +.Em AUTHORS +section, the default is +.Fl nosplit +for the first author listing and +.Fl split +for all other author listings. +.Pp +Examples: +.Dl \&.An -nosplit +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.It Ic \&Ao Ar block +Begin a block enclosed by angle brackets. +Does not have any head arguments. +This macro is almost never useful. +See +.Ic \&Aq +for more details. +.Tg Ap +.It Ic \&Ap +Inserts an apostrophe without any surrounding whitespace. +This is generally used as a grammatical device when referring to the verb +form of a function. +.Pp +Examples: +.Dl \&.Fn execve \&Ap d +.Tg Aq +.It Ic \&Aq Ar line +Enclose the rest of the input line in angle brackets. +The only important use case is for email addresses. +See +.Ic \&Mt +for an example. +.Pp +Occasionally, it is used for names of characters and keys, for example: +.Bd -literal -offset indent +Press the +\&.Aq escape +key to ... +.Ed +.Pp +For URIs, use +.Ic \&Lk +instead, and +.Ic \&In +for +.Dq #include +directives. +Never wrap +.Ic \&Ar +in +.Ic \&Aq . +.Pp +Since +.Ic \&Aq +usually renders with non-ASCII characters in non-ASCII output modes, +do not use it where the ASCII characters +.Sq < +and +.Sq > +are required as syntax elements. +Instead, use these characters directly in such cases, combining them +with the macros +.Ic \&Pf , +.Ic \&Ns , +or +.Ic \&Eo +as needed. +.Pp +See also +.Ic \&Ao . +.Tg Ar +.It Ic \&Ar Op Ar placeholder ... +Command arguments. +If an argument is not provided, the string +.Dq file ...\& +is used as a default. +.Pp +Examples: +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Ic \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Ic \&Fl +or +.Ic \&Cm . +.Tg At +.It Ic \&At Op Ar version +Formats an +.At +version. +Accepts one optional argument: +.Pp +.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact +.It Cm v[1-7] | 32v +A version of +.At . +.It Cm III +.At III . +.It Cm V | V.[1-4] +A version of +.At V . +.El +.Pp +Note that these arguments do not begin with a hyphen. +.Pp +Examples: +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 +.Pp +See also +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Bc +Close a +.Ic \&Bo +block. +Does not have any tail arguments. +.Tg Bd +.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact +Begin a display block. +Display blocks are used to select a different indentation and +justification than the one used by the surrounding text. +They may contain both macro lines and text lines. +By default, a display block is preceded by a vertical space. +.Pp +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Produce one output line from each input line, and center-justify each line. +Using this display type is not recommended; many +.Nm +implementations render it poorly. +.It Fl filled +Change the positions of line breaks to fill each line, and left- and +right-justify the resulting block. +.It Fl literal +Produce one output line from each input line, +and do not justify the block at all. +Preserve white space as it appears in the input. +Always use a constant-width font. +Use this for displaying source code. +.It Fl ragged +Change the positions of line breaks to fill each line, and left-justify +the resulting block. +.It Fl unfilled +The same as +.Fl literal , +but using the same font as for normal text, which is a variable width font +if supported by the output device. +.El +.Pp +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent +.It Fl offset Ar width +Indent the display by the +.Ar width , +which may be one of the following: +.Bl -item +.It +One of the pre-defined strings +.Cm indent , +the width of a standard indentation (six constant width characters); +.Cm indent-two , +twice +.Cm indent ; +.Cm left , +which has no effect; +.Cm right , +which justifies to the right margin; or +.Cm center , +which aligns around an imagined center axis. +.It +A macro invocation, which selects a predefined width +associated with that macro. +The most popular is the imaginary macro +.Ar \&Ds , +which resolves to +.Sy 6n . +.It +A scaling width as described in +.Xr mandoc_roff 7 . +.It +An arbitrary string, which indents by the length of this string. +.El +.Pp +When the argument is missing, +.Fl offset +is ignored. +.It Fl compact +Do not assert vertical space before the display. +.El +.Pp +Examples: +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent \-compact + Hello world. +\&.Ed +.Ed +.Pp +See also +.Ic \&D1 +and +.Ic \&Dl . +.Tg Bf +.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy +Change the font mode for a scoped block of text. +The +.Fl emphasis +and +.Cm \&Em +argument are equivalent, as are +.Fl symbolic +and +.Cm \&Sy , +and +.Fl literal +and +.Cm \&Li . +Without an argument, this macro does nothing. +The font mode continues until broken by a new font mode in a nested +scope or +.Ic \&Ef +is encountered. +.Pp +See also +.Ic \&Li , +.Ic \&Ef , +.Ic \&Em , +and +.Ic \&Sy . +.Tg Bk +.It Ic \&Bk Fl words +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. +.Pp +The +.Fl words +argument is required; additional arguments are ignored. +.Pp +The following example will not break within each +.Ic \&Op +macro line: +.Bd -literal -offset indent +\&.Bk \-words +\&.Op Fl f Ar flags +\&.Op Fl o Ar output +\&.Ek +.Ed +.Pp +Be careful in using over-long lines within a keep block! +Doing so will clobber the right margin. +.Tg Bl +.It Xo +.Ic \&Bl +.Fl Ns Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.Op Ar col ... +.Xc +Begin a list. +Lists consist of items specified using the +.Ic \&It +macro, containing a head or a body or both. +.Pp +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept macro names as described for +.Ic \&Bd +.Fl offset , +scaling widths as described in +.Xr mandoc_roff 7 , +or use the length of the given string. +The +.Fl offset +is a global indentation for the whole list, affecting both item heads +and bodies. +For those list types supporting it, the +.Fl width +argument requests an additional indentation of item bodies, +to be added to the +.Fl offset . +Unless the +.Fl compact +argument is specified, list entries are separated by vertical space. +.Pp +A list must specify one of the following list types: +.Bl -tag -width 12n -offset indent +.It Fl bullet +No item heads can be specified, but a bullet will be printed at the head +of each item. +Item bodies start on the same output line as the bullet +and are indented according to the +.Fl width +argument. +.It Fl column +A columnated list. +The +.Fl width +argument has no effect; instead, the string length of each argument +specifies the width of one column. +If the first line of the body of a +.Fl column +list is not an +.Ic \&It +macro line, +.Ic \&It +contexts spanning one input line each are implied until an +.Ic \&It +macro line is encountered, at which point items start being interpreted as +described in the +.Ic \&It +documentation. +.It Fl dash +Like +.Fl bullet , +except that dashes are used in place of bullets. +.It Fl diag +Like +.Fl inset , +except that item heads are not parsed for macro invocations. +Most often used in the +.Em DIAGNOSTICS +section with error constants in the item heads. +.It Fl enum +A numbered list. +No item heads can be specified. +Formatted like +.Fl bullet , +except that cardinal numbers are used in place of bullets, +starting at 1. +.It Fl hang +Like +.Fl tag , +except that the first lines of item bodies are not indented, but follow +the item heads like in +.Fl inset +lists. +.It Fl hyphen +Synonym for +.Fl dash . +.It Fl inset +Item bodies follow items heads on the same line, using normal inter-word +spacing. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl item +No item heads can be specified, and none are printed. +Bodies are not indented, and the +.Fl width +argument is ignored. +.It Fl ohang +Item bodies start on the line following item heads and are not indented. +The +.Fl width +argument is ignored. +.It Fl tag +Item bodies are indented according to the +.Fl width +argument. +When an item head fits inside the indentation, the item body follows +this head on the same output line. +Otherwise, the body starts on the output line following the head. +.El +.Pp +Lists may be nested within lists and displays. +Nesting of +.Fl column +and +.Fl enum +lists may not be portable. +.Pp +See also +.Ic \&El +and +.Ic \&It . +.It Ic \&Bo Ar block +Begin a block enclosed by square brackets. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bo 1 , +\&.Dv BUFSIZ \&Bc +.Ed +.Pp +See also +.Ic \&Bq . +.Tg Bq +.It Ic \&Bq Ar line +Encloses its arguments in square brackets. +.Pp +Examples: +.Dl \&.Bq 1 , \&Dv BUFSIZ +.Pp +.Em Remarks : +this macro is sometimes abused to emulate optional arguments for +commands; the correct macros to use for this purpose are +.Ic \&Op , +.Ic \&Oo , +and +.Ic \&Oc . +.Pp +See also +.Ic \&Bo . +.It Ic \&Brc +Close a +.Ic \&Bro +block. +Does not have any tail arguments. +.It Ic \&Bro Ar block +Begin a block enclosed by curly braces. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Bro 1 , ... , +\&.Va n \&Brc +.Ed +.Pp +See also +.Ic \&Brq . +.Tg Brq +.It Ic \&Brq Ar line +Encloses its arguments in curly braces. +.Pp +Examples: +.Dl \&.Brq 1 , ... , \&Va n +.Pp +See also +.Ic \&Bro . +.Tg Bsx +.It Ic \&Bsx Op Ar version +Format the +.Bsx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Bsx 1.0 +.Dl \&.Bsx +.Pp +See also +.Ic \&At , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Bt +Supported only for compatibility, do not use this in new manuals. +Prints +.Dq is currently in beta test. +.Tg Bx +.It Ic \&Bx Op Ar version Op Ar variant +Format the +.Bx +version provided as an argument, or a default value if no +argument is provided. +.Pp +Examples: +.Dl \&.Bx 4.3 Tahoe +.Dl \&.Bx 4.4 +.Dl \&.Bx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Dx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.Tg Cd +.It Ic \&Cd Ar line +Kernel configuration declaration. +It is found in pages for +.Bx +and not used here. +.Pp +Examples: +.Dl \&.Cd device le0 at scode? +.Pp +.Em Remarks : +this macro is commonly abused by using quoted literals to retain +whitespace and align consecutive +.Ic \&Cd +declarations. +This practise is discouraged. +.Tg Cm +.It Ic \&Cm Ar keyword ... +Command modifiers. +Typically used for fixed strings passed as arguments to interactive +commands, to commands in interpreted scripts, or to configuration +file directives, unless +.Ic \&Fl +is more appropriate. +Also useful when specifying configuration options or keys. +.Pp +Examples: +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Ic set Fl o Cm vi" +.Dl ".Ic lookup Cm file bind" +.Dl ".Ic permit Ar identity Op Cm as Ar target" +.Tg D1 +.It Ic \&D1 Ar line +One-line indented display. +This is formatted by the default rules and is useful for simple indented +statements. +It is followed by a newline. +.Pp +Examples: +.Dl \&.D1 \&Fl abcdefgh +.Pp +See also +.Ic \&Bd +and +.Ic \&Dl . +.It Ic \&Db +This macro is obsolete. +No replacement is needed. +It is ignored by +.Xr mandoc 1 +and groff including its arguments. +It was formerly used to toggle a debugging mode. +.It Ic \&Dc +Close a +.Ic \&Do +block. +Does not have any tail arguments. +.Tg Dd +.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year +Document date for display in the page footer, +by convention the date of the last change. +This is the mandatory first macro of any +.Nm +manual. +.Pp +The +.Ar month +is the full English month name, the +.Ar day +is an integer number, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of +.Xr cvs 1 , +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +The traditional, purely numeric +.Xr man 7 +format +.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day +is accepted, too. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El +.Pp +Examples: +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 2 2018$ +.Dl \&.Dd July 2, 2018 +.Pp +See also +.Ic \&Dt +and +.Ic \&Os . +.Tg Dl +.It Ic \&Dl Ar line +One-line indented display. +This is formatted as literal text and is useful for commands and +invocations. +It is followed by a newline. +.Pp +Examples: +.Dl \&.Dl % mandoc mdoc.5 \e(ba less +.Pp +See also +.Ic \&Ql , +.Ic \&Bd Fl literal , +and +.Ic \&D1 . +.It Ic \&Do Ar block +Begin a block enclosed by double quotes. +Does not have any head arguments. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Do +April is the cruellest month +\&.Dc +\e(em T.S. Eliot +.Ed +.Pp +See also +.Ic \&Dq . +.Tg Dq +.It Ic \&Dq Ar line +Encloses its arguments in +.Dq typographic +double-quotes. +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Dq April is the cruellest month +\e(em T.S. Eliot +.Ed +.Pp +See also +.Ic \&Qq , +.Ic \&Sq , +and +.Ic \&Do . +.Tg Dt +.It Ic \&Dt Ar TITLE section Op Ar arch +Document title for display in the page header. +This is the mandatory second macro of any +.Nm +file. +.Pp +Its arguments are as follows: +.Bl -tag -width section -offset 2n +.It Ar TITLE +The document's title (name), defaulting to +.Dq UNTITLED +if unspecified. +To achieve a uniform appearance of page header lines, +it should by convention be all caps. +.It Ar SECTION +The manual section. +It should correspond to the manual's filename suffix and defaults to +the empty string if unspecified. +This field is optional. +To achieve a uniform appearance of page header lines, +it should by convention be all caps. +.It Ar arch +This specifies the machine architecture a manual page applies to, +where relevant. +.El +.It Ic \&Dv +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. +.Pp +Examples: +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO +.Pp +See also +.Ic \&Er +and +.Ic \&Ev +for special-purpose constants, +.Ic \&Va +for variable symbols, and +.Ic \&Fd +for listing preprocessor variable definitions in the +.Em SYNOPSIS . +.Tg Dx +.It Ic \&Dx Op Ar version +Format the +.Dx +version provided as an argument, or a default +value if no argument is provided. +.Pp +Examples: +.Dl \&.Dx 2.4.1 +.Dl \&.Dx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Fx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Ec Op Ar closing_delimiter +Close a scope started by +.Ic \&Eo . +.Pp +The +.Ar closing_delimiter +argument is used as the enclosure tail, for example, specifying \e(rq +will emulate +.Ic \&Dc . +.It Ic \&Ed +End a display context started by +.Ic \&Bd . +.It Ic \&Ef +End a font mode context started by +.Ic \&Bf . +.It Ic \&Ek +End a keep context started by +.Ic \&Bk . +.It Ic \&El +End a list context started by +.Ic \&Bl . +See also +.Ic \&It . +.Tg Em +.It Ic \&Em Ar word ... +Request an italic font. +If the output device does not provide that, underline. +.Pp +This is most often used for stress emphasis (not to be confused with +importance, see +.Ic \&Sy ) . +In the rare cases where none of the semantic markup macros fit, +it can also be used for technical terms and placeholders, except +that for syntax elements, +.Ic \&Sy +and +.Ic \&Ar +are preferred, respectively. +.Pp +Examples: +.Bd -literal -compact -offset indent +Selected lines are those +\&.Em not +matching any of the specified patterns. +Some of the functions use a +\&.Em hold space +to save the pattern space for subsequent retrieval. +.Ed +.Pp +See also +.Ic \&No , +.Ic \&Ql , +and +.Ic \&Sy . +.It Ic \&En Ar word ... +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It encloses its argument in the delimiters specified by the last +.Ic \&Es +macro. +.Tg Eo +.It Ic \&Eo Op Ar opening_delimiter +An arbitrary enclosure. +The +.Ar opening_delimiter +argument is used as the enclosure head, for example, specifying \e(lq +will emulate +.Ic \&Do . +.Tg Er +.It Ic \&Er Ar identifier ... +Error constants for definitions of the +.Va errno +libc global variable. +This is most often used in section 2 and 3 manual pages. +.Pp +Examples: +.Dl \&.Er EPERM +.Dl \&.Er ENOENT +.Pp +See also +.Ic \&Dv +for general constants. +.It Ic \&Es Ar opening_delimiter closing_delimiter +This macro is obsolete. +Use +.Ic \&Eo +or any of the other enclosure macros. +.Pp +It takes two arguments, defining the delimiters to be used by subsequent +.Ic \&En +macros. +.Tg Ev +.It Ic \&Ev Ar identifier ... +Environmental variables such as those specified in +.Xr environ 7 . +.Pp +Examples: +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH +.Pp +See also +.Ic \&Dv +for general constants. +.Tg Ex +.It Ic \&Ex Fl std Op Ar utility ... +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. +This is most often used in section 1 and 8 manual pages. +.Pp +If +.Ar utility +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar utility +arguments are treated as separate utilities. +.Pp +See also +.Ic \&Rv . +.Tg Fa +.It Ic \&Fa Ar argument ... +Function argument or parameter. +Each argument may be a name and a type (recommended for the +.Em SYNOPSIS +section), a name alone (for function invocations), +or a type alone (for function prototypes). +If both a type and a name are given or if the type consists of multiple +words, all words belonging to the same function argument have to be +given in a single argument to the +.Ic \&Fa +macro. +.Pp +This macro is also used to specify the field name of a structure. +.Pp +Most often, the +.Ic \&Fa +macro is used in the +.Em SYNOPSIS +within +.Ic \&Fo +blocks when documenting multi-line function prototypes. +If invoked with multiple arguments, the arguments are separated by a +comma. +Furthermore, if the following macro is another +.Ic \&Fa , +the last argument will also have a trailing comma. +.Pp +Examples: +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa \(dqchar *\(dq size_t +.Pp +See also +.Ic \&Fo . +.It Ic \&Fc +End a function context started by +.Ic \&Fo . +.Tg Fd +.It Ic \&Fd Pf # Ar directive Op Ar argument ... +Preprocessor directive, in particular for listing it in the +.Em SYNOPSIS . +Historically, it was also used to document include files. +The latter usage has been deprecated in favour of +.Ic \&In . +.Pp +Examples: +.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler +.Dl \&.Fd #define SIO_MAXNFDS +.Dl \&.Fd #ifdef FS_DEBUG +.Dl \&.Ft void +.Dl \&.Fn dbg_open \(dqconst char *\(dq +.Dl \&.Fd #endif +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&In , +and +.Ic \&Dv . +.Tg Fl +.It Ic \&Fl Op Ar word ... +Command-line flag or option. +Used when listing arguments to command-line utilities. +For each argument, prints an ASCII hyphen-minus character +.Sq \- , +immediately followed by the argument. +If no arguments are provided, a hyphen-minus is printed followed by a space. +If the argument is a macro, a hyphen-minus is prefixed +to the subsequent macro output. +.Pp +Examples: +.Dl ".Nm du Op Fl H | L | P" +.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" +.Dl ".Nm route Cm add Fl inet Ar destination gateway" +.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" +.Dl ".Nm aucat Fl o Fl" +.Dl ".Nm kill Fl Ar signal_number" +.Pp +For GNU-sytle long options, escaping the additional hyphen-minus is not +strictly required, but may be safer with future versions of GNU troff; see +.Xr mandoc_char 7 +for details. +.Pp +See also +.Ic \&Cm . +.Tg Fn +.It Ic \&Fn Ar funcname Op Ar argument ... +A function name. +.Pp +Function arguments are surrounded in parenthesis and +are delimited by commas. +If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. +.Pp +Examples: +.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq +.Dl \&.Fn funcname \(dqint arg0\(dq +.Dl \&.Fn funcname arg0 +.Bd -literal -offset indent +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +When referring to a function documented in another manual page, use +.Ic \&Xr +instead. +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fo , +and +.Ic \&Ft . +.Tg Fo +.It Ic \&Fo Ar funcname +Begin a function block. +This is a multi-line version of +.Ic \&Fn . +.Pp +Invocations usually occur in the following context: +.Bd -ragged -offset indent +.Pf \. Ic \&Ft Ar functype +.br +.Pf \. Ic \&Fo Ar funcname +.br +.Pf \. Ic \&Fa Qq Ar argtype Ar argname +.br +\&.\.\. +.br +.Pf \. Ic \&Fc +.Ed +.Pp +A +.Ic \&Fo +scope is closed by +.Ic \&Fc . +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fa , +.Ic \&Fc , +and +.Ic \&Ft . +.It Ic \&Fr Ar number +This macro is obsolete. +No replacement markup is needed. +.Pp +It was used to show numerical function return values in an italic font. +.Tg Ft +.It Ic \&Ft Ar functype +A function type. +.Pp +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp +Examples: +.Dl \&.Ft int +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +See also +.Sx MANUAL STRUCTURE , +.Ic \&Fn , +and +.Ic \&Fo . +.Tg Fx +.It Ic \&Fx Op Ar version +Format the +.Fx +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Fx 7.1 +.Dl \&.Fx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Nx , +and +.Ic \&Ox . +.It Ic \&Hf Ar filename +This macro is not implemented in +.Xr mandoc 1 . +It was used to include the contents of a (header) file literally. +.Tg Ic +.It Ic \&Ic Ar keyword ... +Internal or interactive command, or configuration instruction +in a configuration file. +See also +.Ic \&Cm . +.Pp +Examples: +.Dl \&.Ic :wq +.Dl \&.Ic hash +.Dl \&.Ic alias +.Pp +Note that using +.Ic \&Ql , +.Ic \&Dl , +or +.Ic \&Bd Fl literal +is preferred for displaying code samples; the +.Ic \&Ic +macro is used when referring to an individual command name. +.Tg In +.It Ic \&In Ar filename +The name of an include file. +This macro is most often used in section 2, 3, and 9 manual pages. +.Pp +When invoked as the first macro on an input line in the +.Em SYNOPSIS +section, the argument is displayed in angle brackets +and preceded by +.Qq #include , +and a blank line is inserted in front if there is a preceding +function declaration. +In other sections, it only encloses its argument in angle brackets +and causes no line break. +.Pp +Examples: +.Dl \&.In sys/types.h +.Pp +See also +.Sx MANUAL STRUCTURE . +.Tg It +.It Ic \&It Op Ar head +A list item. +The syntax of this macro depends on the list type. +.Pp +Lists +of type +.Fl hang , +.Fl ohang , +.Fl inset , +and +.Fl diag +have the following syntax: +.Pp +.D1 Pf \. Ic \&It Ar args +.Pp +Lists of type +.Fl bullet , +.Fl dash , +.Fl enum , +.Fl hyphen +and +.Fl item +have the following syntax: +.Pp +.D1 Pf \. Ic \&It +.Pp +with subsequent lines interpreted within the scope of the +.Ic \&It +until either a closing +.Ic \&El +or another +.Ic \&It . +.Pp +The +.Fl tag +list has the following syntax: +.Pp +.D1 Pf \. Ic \&It Op Cm args +.Pp +Subsequent lines are interpreted as with +.Fl bullet +and family. +The line arguments correspond to the list's left-hand side; body +arguments correspond to the list's contents. +.Pp +The +.Fl column +list is the most complicated. +Its syntax is as follows: +.Pp +.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... +.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... +.Pp +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by the special +.Ic \&Ta +block macro or by literal tab characters. +.Pp +Using literal tabs is strongly discouraged because they are very +hard to use correctly and +.Nm +code using them is very hard to read. +In particular, a blank character is syntactically significant +before and after the literal tab character. +If a word precedes or follows the tab without an intervening blank, +that word is never interpreted as a macro call, but always output +literally. +.Pp +The tab cell delimiter may only be used within the +.Ic \&It +line itself; on following lines, only the +.Ic \&Ta +macro can be used to delimit cells, and portability requires that +.Ic \&Ta +is called by other macros: some parsers do not recognize it when +it appears as the first macro on a line. +.Pp +Note that quoted strings may span tab-delimited cells on an +.Ic \&It +line. +For example, +.Pp +.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; +.Pp +will preserve the whitespace before both commas, +but not the whitespace before the semicolon. +.Pp +See also +.Ic \&Bl . +.Tg Lb +.It Ic \&Lb Cm lib Ns Ar name +Specify a library. +.Pp +The +.Ar name +parameter may be a system library, such as +.Cm z +or +.Cm pam , +in which case a small library description is printed next to the linker +invocation; or a custom library, in which case the library name is +printed in quotes. +This is most commonly used in the +.Em SYNOPSIS +section as described in +.Sx MANUAL STRUCTURE . +.Pp +Examples: +.Dl \&.Lb libz +.Dl \&.Lb libmandoc +.Tg Li +.It Ic \&Li Ar word ... +Request a typewriter (literal) font. +Deprecated because on terminal output devices, this is usually +indistinguishable from normal text. +For literal displays, use +.Ic \&Ql Pq in-line , +.Ic \&Dl Pq single line , +or +.Ic \&Bd Fl literal Pq multi-line +instead. +.Tg Lk +.It Ic \&Lk Ar uri Op Ar display_name +Format a hyperlink. +.Pp +Examples: +.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq +.Dl \&.Lk https://bsd.lv +.Pp +See also +.Ic \&Mt . +.It Ic \&Lp +Deprecated synonym for +.Ic \&Pp . +.Tg Ms +.It Ic \&Ms Ar name +Display a mathematical symbol. +.Pp +Examples: +.Dl \&.Ms sigma +.Dl \&.Ms aleph +.Tg Mt +.It Ic \&Mt Ar localpart Ns @ Ns Ar domain +Format a +.Dq mailto: +hyperlink. +.Pp +Examples: +.Dl \&.Mt discuss@manpages.bsd.lv +.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv +.Tg Nd +.It Ic \&Nd Ar line +A one line description of the manual's content. +This is the mandatory last macro of the +.Em NAME +section and not appropriate for other sections. +.Pp +Examples: +.Dl Pf . Ic \&Nd mdoc language reference +.Dl Pf . Ic \&Nd format and display UNIX manuals +.Pp +The +.Ic \&Nd +macro technically accepts child macros and terminates with a subsequent +.Ic \&Sh +invocation. +Do not assume this behaviour: some +.Xr whatis 1 +database generators are not smart enough to parse more than the line +arguments and will display macros verbatim. +.Pp +See also +.Ic \&Nm . +.Tg Nm +.It Ic \&Nm Op Ar name +The name of the manual page, or \(em in particular in section 1 +pages \(em of an additional command or feature documented in +the manual page. +When first invoked, the +.Ic \&Nm +macro expects a single argument, the name of the manual page. +Usually, the first invocation happens in the +.Em NAME +section of the page. +The specified name will be remembered and used whenever the macro is +called again without arguments later in the page. +The +.Ic \&Nm +macro uses +.Sx Block full-implicit +semantics when invoked as the first macro on an input line in the +.Em SYNOPSIS +section; otherwise, it uses ordinary +.Sx In-line +semantics. +.Pp +Examples: +.Bd -literal -offset indent +\&.Sh SYNOPSIS +\&.Nm cat +\&.Op Fl benstuv +\&.Op Ar +.Ed +.Pp +In the +.Em SYNOPSIS +of section 2, 3 and 9 manual pages, use the +.Ic \&Fn +macro rather than +.Ic \&Nm +to mark up the name of the manual page. +.Tg No +.It Ic \&No Ar word ... +Normal text. +Closes the scope of any preceding in-line macro. +When used after physical formatting macros like +.Ic \&Em +or +.Ic \&Sy , +switches back to the standard font face and weight. +Can also be used to embed plain text strings in macro lines +using semantic annotation macros. +.Pp +Examples: +.Dl ".Em italic , Sy bold , No and roman" +.Bd -literal -offset indent +\&.Sm off +\&.Cm :C No / Ar pattern No / Ar replacement No / +\&.Sm on +.Ed +.Pp +See also +.Ic \&Em , +.Ic \&Ql , +and +.Ic \&Sy . +.Tg Ns +.It Ic \&Ns +Suppress a space between the output of the preceding macro +and the following text or macro. +Following invocation, input is interpreted as normal text +just like after an +.Ic \&No +macro. +.Pp +This has no effect when invoked at the start of a macro line. +.Pp +Examples: +.Dl ".Ar name Ns = Ns Ar value" +.Dl ".Cm :M Ns Ar pattern" +.Dl ".Fl o Ns Ar output" +.Pp +See also +.Ic \&No +and +.Ic \&Sm . +.Tg Nx +.It Ic \&Nx Op Ar version +Format the +.Nx +version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Dl \&.Nx 5.01 +.Dl \&.Nx +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +and +.Ic \&Ox . +.It Ic \&Oc +Close multi-line +.Ic \&Oo +context. +.It Ic \&Oo Ar block +Multi-line version of +.Ic \&Op . +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Oo +\&.Op Fl flag Ns Ar value +\&.Oc +.Ed +.Tg Op +.It Ic \&Op Ar line +Optional part of a command line. +Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. +.Pp +Examples: +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b +.Pp +See also +.Ic \&Oo . +.Tg Os +.It Ic \&Os Op Ar system Op Ar version +Operating system version for display in the page footer. +This is the mandatory third macro of +any +.Nm +file. +.Pp +The optional +.Ar system +parameter specifies the relevant operating system or environment. +It is suggested to leave it unspecified, in which case +.Xr mandoc 1 +uses its +.Fl Ios +argument or, if that isn't specified either, +.Fa sysname +and +.Fa release +as returned by +.Xr uname 3 . +.Pp +Examples: +.Dl \&.Os +.Dl \&.Os KTH/CSC/TCS +.Dl \&.Os BSD 4.3 +.Pp +See also +.Ic \&Dd +and +.Ic \&Dt . +.It Ic \&Ot Ar functype +This macro is obsolete. +Use +.Ic \&Ft +instead; with +.Xr mandoc 1 , +both have the same effect. +.Pp +Historical +.Nm +packages described it as +.Dq "old function type (FORTRAN)" . +.Tg Ox +.It Ic \&Ox Op Ar version +Format the +.Ox +version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Dl \&.Ox 4.5 +.Dl \&.Ox +.Pp +See also +.Ic \&At , +.Ic \&Bsx , +.Ic \&Bx , +.Ic \&Dx , +.Ic \&Fx , +and +.Ic \&Nx . +.Tg Pa +.It Ic \&Pa Ar name ... +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti +is used as a default. +.Pp +Examples: +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man5/mdoc.5 +.Pp +See also +.Ic \&Lk . +.It Ic \&Pc +Close parenthesised context opened by +.Ic \&Po . +.Tg Pf +.It Ic \&Pf Ar prefix macro Op Ar argument ... +Removes the space between its argument and the following macro. +It is equivalent to: +.Pp +.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... +.Pp +The +.Ar prefix +argument is not parsed for macro names or delimiters, +but used verbatim as if it were escaped. +.Pp +Examples: +.Dl ".Pf $ Ar variable_name" +.Dl ".Pf . Ar macro_name" +.Dl ".Pf 0x Ar hex_digits" +.Pp +See also +.Ic \&Ns +and +.Ic \&Sm . +.It Ic \&Po Ar block +Multi-line version of +.Ic \&Pq . +.Tg Pp +.It Ic \&Pp +Break a paragraph. +This will assert vertical space between prior and subsequent macros +and/or text. +.Pp +Paragraph breaks are not needed before or after +.Ic \&Sh +or +.Ic \&Ss +macros or before displays +.Pq Ic \&Bd Ar line +or lists +.Pq Ic \&Bl +unless the +.Fl compact +flag is given. +.Tg Pq +.It Ic \&Pq Ar line +Parenthesised enclosure. +.Pp +See also +.Ic \&Po . +.It Ic \&Qc +Close quoted context opened by +.Ic \&Qo . +.Tg Ql +.It Ic \&Ql Ar line +In-line literal display. +This can be used for complete command invocations and for multi-word +code examples when an indented display is not desired. +.Pp +See also +.Ic \&Dl +and +.Ic \&Bd +.Fl literal . +.It Ic \&Qo Ar block +Multi-line version of +.Ic \&Qq . +.Tg Qq +.It Ic \&Qq Ar line +Encloses its arguments in +.Qq typewriter +double-quotes. +Consider using +.Ic \&Dq . +.Pp +See also +.Ic \&Dq , +.Ic \&Sq , +and +.Ic \&Qo . +.It Ic \&Re +Close an +.Ic \&Rs +block. +Does not have any tail arguments. +.Tg Rs +.It Ic \&Rs +Begin a bibliographic +.Pq Dq reference +block. +Does not have any head arguments. +The block macro may only contain +.Ic \&%A , +.Ic \&%B , +.Ic \&%C , +.Ic \&%D , +.Ic \&%I , +.Ic \&%J , +.Ic \&%N , +.Ic \&%O , +.Ic \&%P , +.Ic \&%Q , +.Ic \&%R , +.Ic \&%T , +.Ic \&%U , +and +.Ic \&%V +child macros (at least one must be specified). +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusetts +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Ic \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +.Tg Rv +.It Ic \&Rv Fl std Op Ar function ... +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +.Pp +If +.Ar function +is not specified, the document's name set by +.Ic \&Nm +is used. +Multiple +.Ar function +arguments are treated as separate functions. +.Pp +See also +.Ic \&Ex . +.It Ic \&Sc +Close single-quoted context opened by +.Ic \&So . +.Tg Sh +.It Ic \&Sh Ar TITLE LINE +Begin a new section. +For a list of conventional manual sections, see +.Sx MANUAL STRUCTURE . +These sections should be used unless it's absolutely necessary that +custom sections be used. +.Pp +Section names should be unique so that they may be keyed by +.Ic \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Ic \&Sx . +.Pp +See also +.Ic \&Pp , +.Ic \&Ss , +and +.Ic \&Sx . +.Tg Sm +.It Ic \&Sm Op Cm on | off +Switches the spacing mode for output generated from macros. +.Pp +By default, spacing is +.Cm on . +When switched +.Cm off , +no white space is inserted between macro arguments and between the +output generated from adjacent macros, but text lines +still get normal spacing between words and sentences. +.Pp +When called without an argument, the +.Ic \&Sm +macro toggles the spacing mode. +Using this is not recommended because it makes the code harder to read. +.It Ic \&So Ar block +Multi-line version of +.Ic \&Sq . +.Tg Sq +.It Ic \&Sq Ar line +Encloses its arguments in +.Sq typewriter +single-quotes. +.Pp +See also +.Ic \&Dq , +.Ic \&Qq , +and +.Ic \&So . +.Tg Ss +.It Ic \&Ss Ar Title line +Begin a new subsection. +Unlike with +.Ic \&Sh , +there is no convention for the naming of subsections. +Except +.Em DESCRIPTION , +the conventional sections described in +.Sx MANUAL STRUCTURE +rarely have subsections. +.Pp +Sub-section names should be unique so that they may be keyed by +.Ic \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.Ic \&Sx . +.Pp +See also +.Ic \&Pp , +.Ic \&Sh , +and +.Ic \&Sx . +.Tg St +.It Ic \&St Fl Ns Ar abbreviation +Replace an abbreviation for a standard with the full form. +The following standards are recognised. +Where multiple lines are given without a blank line in between, +they all refer to the same standard, and using the first form +is recommended. +.Bl -tag -width 1n +.It C language standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ansiC +.St -ansiC +.It \-ansiC-89 +.St -ansiC-89 +.It \-isoC +.St -isoC +.It \-isoC-90 +.St -isoC-90 +.br +The original C standard. +.Pp +.It \-isoC-amd1 +.St -isoC-amd1 +.Pp +.It \-isoC-tcor1 +.St -isoC-tcor1 +.Pp +.It \-isoC-tcor2 +.St -isoC-tcor2 +.Pp +.It \-isoC-99 +.St -isoC-99 +.br +The second major version of the C language standard. +.Pp +.It \-isoC-2011 +.St -isoC-2011 +.br +The third major version of the C language standard. +.El +.It POSIX.1 before the Single UNIX Specification +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-88 +.St -p1003.1-88 +.It \-p1003.1 +.St -p1003.1 +.br +The original POSIX standard, based on ANSI C. +.Pp +.It \-p1003.1-90 +.St -p1003.1-90 +.It \-iso9945-1-90 +.St -iso9945-1-90 +.br +The first update of POSIX.1. +.Pp +.It \-p1003.1b-93 +.St -p1003.1b-93 +.It \-p1003.1b +.St -p1003.1b +.br +Real-time extensions. +.Pp +.It \-p1003.1c-95 +.St -p1003.1c-95 +.br +POSIX thread interfaces. +.Pp +.It \-p1003.1i-95 +.St -p1003.1i-95 +.br +Technical Corrigendum. +.Pp +.It \-p1003.1-96 +.St -p1003.1-96 +.It \-iso9945-1-96 +.St -iso9945-1-96 +.br +Includes POSIX.1-1990, 1b, 1c, and 1i. +.El +.It X/Open Portability Guide version 4 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-xpg3 +.St -xpg3 +.br +An XPG4 precursor, published in 1989. +.Pp +.It \-p1003.2 +.St -p1003.2 +.It \-p1003.2-92 +.St -p1003.2-92 +.It \-iso9945-2-93 +.St -iso9945-2-93 +.br +An XCU4 precursor. +.Pp +.It \-p1003.2a-92 +.St -p1003.2a-92 +.br +Updates to POSIX.2. +.Pp +.It \-xpg4 +.St -xpg4 +.br +Based on POSIX.1 and POSIX.2, published in 1992. +.El +.It Single UNIX Specification version 1 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv1 +.St -susv1 +.It \-xpg4.2 +.St -xpg4.2 +.br +This standard was published in 1994. +It was used as the basis for UNIX 95 certification. +The following three refer to parts of it. +.Pp +.It \-xsh4.2 +.St -xsh4.2 +.Pp +.It \-xcurses4.2 +.St -xcurses4.2 +.Pp +.It \-p1003.1g-2000 +.St -p1003.1g-2000 +.br +Networking APIs, including sockets. +.Pp +.It \-svid4 +.St -svid4 , +.br +Published in 1995. +.El +.It Single UNIX Specification version 2 and related standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-susv2 +.St -susv2 +This Standard was published in 1997 +and is also called X/Open Portability Guide version 5. +It was used as the basis for UNIX 98 certification. +The following refer to parts of it. +.Pp +.It \-xbd5 +.St -xbd5 +.Pp +.It \-xsh5 +.St -xsh5 +.Pp +.It \-xcu5 +.St -xcu5 +.Pp +.It \-xns5 +.St -xns5 +.It \-xns5.2 +.St -xns5.2 +.El +.It Single UNIX Specification version 3 +.Pp +.Bl -tag -width "-p1003.1-2001" -compact +.It \-p1003.1-2001 +.St -p1003.1-2001 +.It \-susv3 +.St -susv3 +.br +This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. +It is also called X/Open Portability Guide version 6. +It is used as the basis for UNIX 03 certification. +.Pp +.It \-p1003.1-2004 +.St -p1003.1-2004 +.br +The second and last Technical Corrigendum. +.El +.It Single UNIX Specification version 4 +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-p1003.1-2008 +.St -p1003.1-2008 +.It \-susv4 +.St -susv4 +.br +This standard is also called +X/Open Portability Guide version 7. +.El +.It Other standards +.Pp +.Bl -tag -width "-p1003.1g-2000" -compact +.It \-ieee754 +.St -ieee754 +.br +Floating-point arithmetic. +.Pp +.It \-iso8601 +.St -iso8601 +.br +Representation of dates and times, published in 1988. +.Pp +.It \-iso8802-3 +.St -iso8802-3 +.br +Ethernet local area networks. +.Pp +.It \-ieee1275-94 +.St -ieee1275-94 +.El +.El +.Tg Sx +.It Ic \&Sx Ar Title line +Reference a section or subsection in the same manual page. +The referenced section or subsection name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.Dl \&.Sx MANUAL STRUCTURE +.Pp +See also +.Ic \&Sh +and +.Ic \&Ss . +.Tg Sy +.It Ic \&Sy Ar word ... +Request a boldface font. +.Pp +This is most often used to indicate importance or seriousness (not to be +confused with stress emphasis, see +.Ic \&Em ) . +When none of the semantic macros fit, it is also adequate for syntax +elements that have to be given or that appear verbatim. +.Pp +Examples: +.Bd -literal -compact -offset indent +\&.Sy Warning : +If +\&.Sy s +appears in the owner permissions, set-user-ID mode is set. +This utility replaces the former +\&.Sy dumpdir +program. +.Ed +.Pp +See also +.Ic \&Em , +.Ic \&No , +and +.Ic \&Ql . +.Tg Ta +.It Ic \&Ta +Table cell separator in +.Ic \&Bl Fl column +lists; can only be used below +.Ic \&It . +.Tg Tg +.It Ic \&Tg Op Ar term +Announce that the next input line starts a definition of the +.Ar term . +This macro must appear alone on its own input line. +The argument defaults to the first argument of the first macro +on the next line. +The argument may not contain whitespace characters, not even when it is quoted. +This macro is a +.Xr mandoc 1 +extension and is typically ignored by other formatters. +.Pp +When viewing terminal output with +.Xr less 1 , +the interactive +.Ic :t +command can be used to go to the definition of the +.Ar term +as described for the +.Ev MANPAGER +variable in +.Xr man 1 ; +when producing HTML output, a fragment identifier +.Pq Ic id No attribute +is generated, to be used for deep linking to this place of the document. +.Pp +In most cases, adding a +.Ic \&Tg +macro would be redundant because +.Xr mandoc 1 +is able to automatically tag most definitions. +This macro is intended for cases where automatic tagging of a +.Ar term +is unsatisfactory, for example if a definition is not tagged +automatically (false negative) or if places are tagged that do +not define the +.Ar term +(false positives). +When there is at least one +.Ic \&Tg +macro for a +.Ar term , +no other places are automatically marked as definitions of that +.Ar term . +.It Ic \&Tn Ar word ... +Supported only for compatibility, do not use this in new manuals. +Even though the macro name +.Pq Dq tradename +suggests a semantic function, historic usage is inconsistent, mostly +using it as a presentation-level macro to request a small caps font. +.It Ic \&Ud +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq currently under development. +.It Ic \&Ux +Supported only for compatibility, do not use this in new manuals. +Prints out +.Dq Ux . +.Tg Va +.It Ic \&Va Oo Ar type Oc Ar identifier ... +A variable name. +.Pp +Examples: +.Dl \&.Va foo +.Dl \&.Va const char *bar ; +.Pp +For function arguments and parameters, use +.Ic \&Fa +instead. +For declarations of global variables in the +.Em SYNOPSIS +section, use +.Ic \&Vt . +.Tg Vt +.It Ic \&Vt Ar type Op Ar identifier +A variable type. +.Pp +This is also used for indicating global variables in the +.Em SYNOPSIS +section, in which case a variable name is also specified. +Note that it accepts +.Sx Block partial-implicit +syntax when invoked as the first macro on an input line in the +.Em SYNOPSIS +section, else it accepts ordinary +.Sx In-line +syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. +.Pp +Examples: +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; +.Pp +For parameters in function prototypes, use +.Ic \&Fa +instead, for function return types +.Ic \&Ft , +and for variable names outside the +.Em SYNOPSIS +section +.Ic \&Va , +even when including a type with the name. +See also +.Sx MANUAL STRUCTURE . +.It Ic \&Xc +Close a scope opened by +.Ic \&Xo . +.It Ic \&Xo Ar block +Extend the header of an +.Ic \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr mandoc_roff 7 . +.Tg Xr +.It Ic \&Xr Ar name section +Link to another manual +.Pq Qq cross-reference . +.Pp +Cross reference the +.Ar name +and +.Ar section +number of another man page. +.Pp +Examples: +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.Xr mandoc 1 \&Ns s behaviour +.El +.Sh MACRO SYNTAX +The syntax of a macro depends on its classification. +In this section, +.Sq \-arg +refers to macro arguments, which may be followed by zero or more +.Sq parm +parameters; +.Sq \&Yo +opens the scope of a macro; and if specified, +.Sq \&Yc +closes it out. +.Pp +The +.Em Callable +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . +.Pp +The +.Em Parsed +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. +.Pp +The +.Em Scope +column, if applicable, describes closure rules. +.Ss Block full-explicit +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only +.Ic \&Bf +and +.Pq optionally +.Ic \&Bl +contain a head. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed +.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef +.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek +.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El +.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd +.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf +.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk +.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl +.El +.Ss Block full-implicit +Multi-line scope closed by end-of-file or implicitly by another macro. +All macros have bodies; some +.Po +.Ic \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item +.Pc +don't have heads; only one +.Po +.Ic \&It +in +.Ic \&Bl Fl column +.Pc +has multiple heads. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El +.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh +.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss +.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh +.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss +.El +.Pp +Note that the +.Ic \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Block partial-explicit +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head +.Po +.Ic \&Fo , +.Ic \&Eo +.Pc +and/or tail +.Pq Ic \&Ec . +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB + +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ +\(lBbody...\(rB \&Yc \(lBtail...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao +.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac +.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo +.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc +.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro +.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc +.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do +.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc +.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo +.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec +.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo +.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc +.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo +.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc +.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po +.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc +.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo +.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc +.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs +.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re +.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So +.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc +.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo +.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc +.El +.Ss Block partial-implicit +Like block full-implicit, but with single-line scope closed by the +end of the line. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed +.It Ic \&Aq Ta Yes Ta Yes +.It Ic \&Bq Ta Yes Ta Yes +.It Ic \&Brq Ta Yes Ta Yes +.It Ic \&D1 Ta \&No Ta \&Yes +.It Ic \&Dl Ta \&No Ta Yes +.It Ic \&Dq Ta Yes Ta Yes +.It Ic \&En Ta Yes Ta Yes +.It Ic \&Op Ta Yes Ta Yes +.It Ic \&Pq Ta Yes Ta Yes +.It Ic \&Ql Ta Yes Ta Yes +.It Ic \&Qq Ta Yes Ta Yes +.It Ic \&Sq Ta Yes Ta Yes +.It Ic \&Vt Ta Yes Ta Yes +.El +.Pp +Note that the +.Ic \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . +.Ss Special block macro +The +.Ic \&Ta +macro can only be used below +.Ic \&It +in +.Ic \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope +.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It +.El +.Ss In-line +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +.Ed +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments +.It Ic \&%A Ta \&No Ta \&No Ta >0 +.It Ic \&%B Ta \&No Ta \&No Ta >0 +.It Ic \&%C Ta \&No Ta \&No Ta >0 +.It Ic \&%D Ta \&No Ta \&No Ta >0 +.It Ic \&%I Ta \&No Ta \&No Ta >0 +.It Ic \&%J Ta \&No Ta \&No Ta >0 +.It Ic \&%N Ta \&No Ta \&No Ta >0 +.It Ic \&%O Ta \&No Ta \&No Ta >0 +.It Ic \&%P Ta \&No Ta \&No Ta >0 +.It Ic \&%Q Ta \&No Ta \&No Ta >0 +.It Ic \&%R Ta \&No Ta \&No Ta >0 +.It Ic \&%T Ta \&No Ta \&No Ta >0 +.It Ic \&%U Ta \&No Ta \&No Ta >0 +.It Ic \&%V Ta \&No Ta \&No Ta >0 +.It Ic \&Ad Ta Yes Ta Yes Ta >0 +.It Ic \&An Ta Yes Ta Yes Ta >0 +.It Ic \&Ap Ta Yes Ta Yes Ta 0 +.It Ic \&Ar Ta Yes Ta Yes Ta n +.It Ic \&At Ta Yes Ta Yes Ta 1 +.It Ic \&Bsx Ta Yes Ta Yes Ta n +.It Ic \&Bt Ta \&No Ta \&No Ta 0 +.It Ic \&Bx Ta Yes Ta Yes Ta n +.It Ic \&Cd Ta Yes Ta Yes Ta >0 +.It Ic \&Cm Ta Yes Ta Yes Ta >0 +.It Ic \&Db Ta \&No Ta \&No Ta 1 +.It Ic \&Dd Ta \&No Ta \&No Ta n +.It Ic \&Dt Ta \&No Ta \&No Ta n +.It Ic \&Dv Ta Yes Ta Yes Ta >0 +.It Ic \&Dx Ta Yes Ta Yes Ta n +.It Ic \&Em Ta Yes Ta Yes Ta >0 +.It Ic \&Er Ta Yes Ta Yes Ta >0 +.It Ic \&Es Ta Yes Ta Yes Ta 2 +.It Ic \&Ev Ta Yes Ta Yes Ta >0 +.It Ic \&Ex Ta \&No Ta \&No Ta n +.It Ic \&Fa Ta Yes Ta Yes Ta >0 +.It Ic \&Fd Ta \&No Ta \&No Ta >0 +.It Ic \&Fl Ta Yes Ta Yes Ta n +.It Ic \&Fn Ta Yes Ta Yes Ta >0 +.It Ic \&Fr Ta Yes Ta Yes Ta >0 +.It Ic \&Ft Ta Yes Ta Yes Ta >0 +.It Ic \&Fx Ta Yes Ta Yes Ta n +.It Ic \&Hf Ta \&No Ta \&No Ta n +.It Ic \&Ic Ta Yes Ta Yes Ta >0 +.It Ic \&In Ta \&No Ta \&No Ta 1 +.It Ic \&Lb Ta \&No Ta \&No Ta 1 +.It Ic \&Li Ta Yes Ta Yes Ta >0 +.It Ic \&Lk Ta Yes Ta Yes Ta >0 +.It Ic \&Lp Ta \&No Ta \&No Ta 0 +.It Ic \&Ms Ta Yes Ta Yes Ta >0 +.It Ic \&Mt Ta Yes Ta Yes Ta >0 +.It Ic \&Nm Ta Yes Ta Yes Ta n +.It Ic \&No Ta Yes Ta Yes Ta >0 +.It Ic \&Ns Ta Yes Ta Yes Ta 0 +.It Ic \&Nx Ta Yes Ta Yes Ta n +.It Ic \&Os Ta \&No Ta \&No Ta n +.It Ic \&Ot Ta Yes Ta Yes Ta >0 +.It Ic \&Ox Ta Yes Ta Yes Ta n +.It Ic \&Pa Ta Yes Ta Yes Ta n +.It Ic \&Pf Ta Yes Ta Yes Ta 1 +.It Ic \&Pp Ta \&No Ta \&No Ta 0 +.It Ic \&Rv Ta \&No Ta \&No Ta n +.It Ic \&Sm Ta \&No Ta \&No Ta <2 +.It Ic \&St Ta \&No Ta Yes Ta 1 +.It Ic \&Sx Ta Yes Ta Yes Ta >0 +.It Ic \&Sy Ta Yes Ta Yes Ta >0 +.It Ic \&Tg Ta \&No Ta \&No Ta <2 +.It Ic \&Tn Ta Yes Ta Yes Ta >0 +.It Ic \&Ud Ta \&No Ta \&No Ta 0 +.It Ic \&Ux Ta Yes Ta Yes Ta n +.It Ic \&Va Ta Yes Ta Yes Ta n +.It Ic \&Vt Ta Yes Ta Yes Ta >0 +.It Ic \&Xr Ta Yes Ta Yes Ta 2 +.El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +Spacing is suppressed after opening delimiters +and before closing delimiters. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&.\& +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter, which does not suppress spacing: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. +.Pp +Appending a zero-width space +.Pq Sq \e& +to the end of an input line is also useful to prevent the interpretation +of a trailing period, exclamation or question mark as the end of a +sentence, for example when an abbreviation happens to occur +at the end of a text or macro input line. +.Ss Font handling +In +.Nm +documents, usage of semantic markup is recommended in order to have +proper fonts automatically selected; only when no fitting semantic markup +is available, consider falling back to +.Sx Physical markup +macros. +Whenever any +.Nm +macro switches the +.Xr mandoc_roff 7 +font mode, it will automatically restore the previous font when exiting +its scope. +Manually switching the font using the +.Xr mandoc_roff 7 +.Ql \ef +font escape sequences is never required. +.Sh COMPATIBILITY +This section provides an incomplete list of compatibility issues +between mandoc and GNU troff +.Pq Qq groff . +.Pp +The following problematic behaviour is found in groff: +.Pp +.Bl -dash -compact +.It +.Ic \&Pa +does not format its arguments when used in the FILES section under +certain list types. +.It +.Ic \&Ta +can only be called by other macros, but not at the beginning of a line. +.It +.Sq \ef +.Pq font face +and +.Sq \eF +.Pq font family face +.Sx Text Decoration +escapes behave irregularly when specified within line-macro scopes. +.It +Negative scaling units return to prior lines. +Instead, mandoc truncates them to zero. +.El +.Pp +The following features are unimplemented in mandoc: +.Pp +.Bl -dash -compact +.It +.Ic \&Bd Fl file Ar file +is unsupported for security reasons. +.It +.Ic \&Bd +.Fl filled +does not adjust the right margin, but is an alias for +.Ic \&Bd +.Fl ragged . +.It +.Ic \&Bd +.Fl literal +does not use a literal font, but is an alias for +.Ic \&Bd +.Fl unfilled . +.It +.Ic \&Bd +.Fl offset Cm center +and +.Fl offset Cm right +don't work. +Groff does not implement centered and flush-right rendering either, +but produces large indentations. +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mandoc_roff 7 , +.Xr tbl 7 +.Pp +The web page +.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" +provides a few tutorial-style pages for beginners, an extensive style +guide for advanced authors, and an alphabetic index helping to choose +the best macros for various kinds of content. +.Pp +The manual page +.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(4)" +contained in the +.Dq groff +package documents exactly the same language in a somewhat different style. +.Sh HISTORY +The +.Nm +language first appeared as a troff macro package in +.Bx 4.4 . +It was later significantly updated by Werner Lemberg and Ruslan Ermilov +in groff-1.17. +The standalone implementation that is part of the +.Xr mandoc 1 +utility written by Kristaps Dzonsons appeared in +.Ox 4.6 . +.Sh AUTHORS +The +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . diff --git a/usr/src/man/man7/me.7 b/usr/src/man/man7/me.7 new file mode 100644 index 0000000000..10966adc9f --- /dev/null +++ b/usr/src/man/man7/me.7 @@ -0,0 +1,246 @@ +'\" te +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.TH ME 7 "Feb 25, 1992" +.SH NAME +me \- macros for formatting papers +.SH SYNOPSIS +.LP +.nf +\fBnroff\fR \fB-me\fR [\fIoptions\fR] \fIfilename\fR... +.fi + +.LP +.nf +\fBtroff\fR \fB-me\fR [\fIoptions\fR] \fIfilename\fR... +.fi + +.SH DESCRIPTION +.sp +.LP +This package of \fBnroff\fR and \fBtroff\fR macro definitions provides a canned +formatting facility for technical papers in various formats. When producing +2-column output on a terminal, filter the output through \fBcol\fR(1). +.sp +.LP +The macro requests are defined below. Many \fBnroff\fR and \fBtroff\fR requests +are unsafe in conjunction with this package, however, these requests may be +used with impunity after the first \fB\&.pp\fR: +.sp +.ne 2 +.na +\fB\&.bp\fR +.ad +.RS 12n +begin new page +.RE + +.sp +.ne 2 +.na +\fB\&.br\fR +.ad +.RS 12n +break output line here +.RE + +.sp +.ne 2 +.na +\fB\&.sp \fIn\fR\fR +.ad +.RS 12n +insert \fIn\fR spacing lines +.RE + +.sp +.ne 2 +.na +\fB\&.ls \fIn\fR\fR +.ad +.RS 12n +(line spacing) \fIn\fR=1 single, \fIn\fR=2 double space +.RE + +.sp +.ne 2 +.na +\fB\&.na\fR +.ad +.RS 12n +no alignment of right margin +.RE + +.sp +.ne 2 +.na +\fB\&.ce \fIn\fR\fR +.ad +.RS 12n +center next \fIn\fR lines +.RE + +.sp +.ne 2 +.na +\fB\&.ul \fIn\fR\fR +.ad +.RS 12n +underline next \fIn\fR lines +.RE + +.sp +.ne 2 +.na +\fB\&.sz \fI+n\fR\fR +.ad +.RS 12n +add \fIn\fR to point size +.RE + +.sp +.LP +Output of the \fBeqn\fR(1), \fBneqn\fR(1), \fBrefer\fR(1), and \fBtbl\fR(1) +preprocessors for equations and tables is acceptable as input. +.SH REQUESTS +.sp +.LP +In the following list, "initialization" refers to the first \fB\&.pp,\fR +\fB\&.lp\fR, \fB\&.ip\fR, \fB\&.np\fR, \fB\&.sh\fR, or \fB\&.uh\fR macro. This +list is incomplete. +.sp + +.sp +.TS +c c c c +c c c c . +\fIRequest\fR \fIInitial\fR \fICause\fR \fIExplanation\fR + \fIValue\fR \fIBreak\fR +\fB\&.(c\fR - yes Begin centered block. +\fB\&.(d\fR - no Begin delayed text. +\fB\&.(f\fR - no Begin footnote. +\fB\&.(l\fR - yes Begin list. +\fB\&.(q\fR - yes Begin major quote. +\fB\&.(x\fR\fIx\fR - no Begin indexed item in index \fIx\fR. +\fB\&.(z\fR - no Begin floating keep. +\fB\&.)c\fR - yes End centered block. +\fB\&.)d\fR - yes End delayed text. +\fB\&.)f\fR - yes End footnote. +\fB\&.)l\fR - yes End list. +\fB\&.)q\fR - yes End major quote. +\fB\&.)x\fR - yes End index item. +\fB\&.)z\fR - yes End floating keep. +\fB\&.++\fR \fIm H\fR - no Define paper section. + \fIm\fR defines the part of the paper, + T{ +and can be \fBC\fR (chapter), \fBA\fR (appendix), \fBP\fR (preliminary, for instance, +T} + abstract, table of contents, etc.), + \fBB\fR (bibliography), \fBRC\fR (chapters + renumbered from page one each + chapter), or \fBRA\fR (appendix renumbered + from page one). +\fB\&.+c \fR\fIT\fR - yes Begin chapter (or appendix, etc., + as set by \fB\&.++\fR). \fIT\fR is + the chapter title. +\fB\&.1c\fR 1 yes One column format on a new page. +\fB\&.2c\fR 1 yes Two column format. +\fB\&.EN\fR - yes Space after equation produced by \fBeqn\fR + or \fBneqn\fR. +\fB\&.EQ\fR \fIx y\fR - yes Precede equation; break out and + add space. Equation number is \fIy\fR. + The optional argument \fIx\fR may be \fII\fR + to indent equation (default), + \fIL\fR to left-adjust the equation, or + \fIC\fR to center the equation. +\fB\&.GE\fR - yes End \fIgremlin\fR picture. +\fB\&.GS\fR - yes Begin \fIgremlin\fR picture. +\fB\&.PE\fR - yes End \fBpic\fR picture. +\fB\&.PS\fR - yes Begin \fBpic\fR picture. +\fB\&.TH\fR - YES "heading End, section" +\fB\&.TE\fR - yes End table. +\fB\&.TS\fR \fIx\fR - yes Begin table; if \fIx\fR is \fIH\fR table + has repeated heading. +\fB\&.ac\fR \fIA N\fR - no Set up for ACM style output. + \fIA\fR is the Author's name(s), \fIN\fR is the + total number of pages. Must be given + before the first initialization. +\fB\&.b\fR \fIx\fR no no Print \fIx\fR in boldface; if no argument + switch to boldface. +\fB\&.ba\fR \fI+n\fR 0 yes Augments the base indent by \fIn\fR. + This indent is used to set the indent + on regular text (like paragraphs). +\fB\&.bc\fR no yes Begin new column. +\fB\&.bi\fR \fIx\fR no no Print \fIx\fR in bold italics + (nofill only). +\fB\&.bu\fR - yes Begin bulleted paragraph. +\fB\&.bx\fR \fIx\fR no no Print \fIx\fR in a box (nofill only). +\fB\&.ef\fR \fI\&'x'y'z\fR \&''''' no Set even footer to \fIx y z\fR. +\fB\&.eh\fR \fI\&'x'y'z\fR \&''''' no Set even header to \fIx y z\fR. +\fB\&.fo\fR \fI\&'x'y'z\fR \&''''' no Set footer to \fIx y z\fR. +\fB\&.hx\fR - no Suppress headers and footers on + next page. +\fB\&.he\fR \fI\&'x'y'z\fR \&''''' no Set header to \fIx y z\fR. +\fB\&.hl\fR - yes Draw a horizontal line. +\fB\&.i\fR \fIx\fR no no Italicize \fIx\fR; if \fIx\fR missing, italic + text follows. +\fB\&.ip\fR \fIx y\fR no yes Start indented paragraph, with + hanging tag \fIx\fR. Indentation is + \fIy\fR ens (default 5). +\fB\&.lp\fR yes yes Start left-blocked paragraph. +\fB\&.lo\fR - no Read in a file of local macros + of the form \fB\&.*\fR\fIx.\fR Must be + given before initialization. +\fB\&.np\fR 1 yes Start numbered paragraph. +\fB\&.of\fR \fI\&'x'y'z\fR \&''''' no Set odd footer to x y z. +\fB\&.oh\fR \fI\&'x'y'z\fR \&''''' no Set odd header to x y z. +\fB\&.pd\fR - yes Print delayed text. +\fB\&.pp\fR no yes Begin paragraph. First line indented. +\fB\&.r\fR yes no Roman text follows. +\fB\&.re\fR - no Reset tabs to default values. +\fB\&.sc\fR no no Read in a file of special characters + and diacritical marks. Must be + given before initialization. +\fB\&.sh\fR \fIn x\fR - yes Section head follows, font + automatically bold. \fIn\fR is level + of section, \fIx\fR is title of section. +\fB\&.sk\fR no no Leave the next page blank. + Only one page is remembered ahead. +\fB\&.sm\fR \fIx\fR - no Set \fIx\fR in a smaller pointsize. +\fB\&.sz\fR \fI+n\fR 10p no Augment the point size by \fIn\fR points. +\fB\&.th\fR no no Produce the paper in thesis format. + Must be given before initialization. +\fB\&.tp\fR no yes Begin title page. +\fB\&.u\fR \fIx\fR - no Underline argument (even in \fBtroff\fR). + (Nofill only). +\fB\&.uh\fR - yes Like \fB\&.sh\fR but unnumbered. +\fB\&.xp\fR \fIx\fR - no Print index \fIx\fR. +.TE + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/e\fR\fR +.ad +.RS 28n + +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/*.me\fR\fR +.ad +.RS 28n + +.RE + +.SH SEE ALSO +.sp +.LP +.BR col (1), +.BR eqn (1), +.BR nroff (1), +.BR refer (1), +.BR tbl (1), +.BR troff (1) diff --git a/usr/src/man/man7/mech_spnego.7 b/usr/src/man/man7/mech_spnego.7 new file mode 100644 index 0000000000..1827e29703 --- /dev/null +++ b/usr/src/man/man7/mech_spnego.7 @@ -0,0 +1,122 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH MECH_SPNEGO 7 "Oct 4, 2004" +.SH NAME +mech_spnego \- Simple and Protected GSS-API Negotiation Mechanism +.SH SYNOPSIS +.LP +.nf +/usr/lib/gss/mech_spnego.so.1 +.fi + +.SH DESCRIPTION +.sp +.LP +The SPNEGO security mechanism for \fBGSS\fR-\fBAPI\fR allows +\fBGSS\fR-\fBAPI\fR applications to negotiate the actual security mechanism to +be used in the \fBGSS\fR-\fBAPI\fR session. \fBmech_spnego.so.1\fR is a shared +object module that is dynamically opened by applications that specify the +SPNEGO Object Identifier (\fBOID\fR) in calls to the \fBGSS\fR-\fBAPI\fR +functions (see \fBlibgss\fR(3LIB)). +.sp +.LP +SPNEGO is described by IETF RFC 2478 and is intended to be used in environments +where multiple \fBGSS\fR-\fBAPI \fRmechanisms are available to the client or +server and neither side knows what mechanisms are supported by the other. +.sp +.LP +When SPNEGO is used, it selects the list of mechanisms to advertise by reading +the \fBGSS\fR mechanism configuration file, \fB/etc/gss/mech\fR (see +\fBmech\fR(5)), and by listing all active mechanisms except for itself. +.SH OPTIONS +.sp +.LP +SPNEGO may be configured to function in two ways. The first way is to +interoperate with Microsoft SSPI clients and servers that use the Microsoft +"\fBNegotiate\fR" method, which is also based on SPNEGO. The Microsoft +"\fBNegotiate\fR" mechanism does not strictly follow the IETF RFC. Therefore, +use special handling in order to enable full interoperability. In order to +interoperate, place option "\fB[ msinterop ]\fR" at the end of the SPNEGO line +in \fB/etc/gss/mech\fR. +.sp +.LP +This is an example (from \fB/etc/gss/mech\fR): +.sp +.in +2 +.nf +\fBspnego 1.3.6.1.5.5.2 mech_spnego.so [ msinterop ]\fR +.fi +.in -2 +.sp + +.sp +.LP +Without the "\fB[ msinterop ]\fR" option, \fBmech_spnego\fR will follow the +strict IETF RFC 2478 specification and will not be able to negotiate with +Microsoft applications that try to use the SSPI "\fBNegotiate\fR" mechanism. +.SH INTERFACES +.sp +.LP +\fBmech_spnego.so.1\fR has no public interfaces. It is only activated and used +through the \fBGSS\fR-\fBAPI\fR interface provided by \fBlibgss.so.1\fR (see +\fBlibgss\fR(3LIB)). +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/lib/gss/mech_spnego.so.1\fR\fR +.ad +.sp .6 +.RS 4n +shared object file +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/sparcv9/gss/mech_spnego.so.1\fR\fR +.ad +.sp .6 +.RS 4n +SPARC 64-bit shared object file +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/lib/amd64/gss/mech_spnego.so.1\fR\fR +.ad +.sp .6 +.RS 4n +x86 64-bit shared object file +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR Intro (3), +.BR libgss (3LIB), +.BR mech (5), +.BR attributes (7) +.sp +.LP +\fISolaris Security for Developers Guide\fR diff --git a/usr/src/man/man7/menu.4th.7 b/usr/src/man/man7/menu.4th.7 new file mode 100644 index 0000000000..79c4712298 --- /dev/null +++ b/usr/src/man/man7/menu.4th.7 @@ -0,0 +1,307 @@ +.\" Copyright (c) 2011-2013 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt MENU.4TH 7 +.Os +.Sh NAME +.Nm menu.4th +.Nd loader dynamic menu boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to display a dynamic menu system managed through +a system of carefully named environment variables. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include menu.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic menu-init +Draws the menu bounding box and initializes some internal state variables. +This should be called before any other menu-related functions. +.It Ic menu-display +Displays the menu (configured via the below documented environment variables) +and blocks on keyboard input, awaiting user action. +.It Ic menu-erase +Clears the screen area within the menu bounding box. +.It Ic menu-redraw +Calls +.Ic menu-erase +and then redraws the menu. +.It Ic menu-unset +Unsets the environment variables associated with individual menu items, +clearing the way for a new menu. +.It Ic menu-clear +Calls +.Ic menu-unset +and then +.Ic menu-erase . +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_color +If set to +.Dq Li NO +(case-insensitive) or +.Dq Li 0 , +causes the menu to be displayed without color. +The default is to use ANSI coloring whenever possible. +If serial boot is enabled, color is disabled by default. +Color features include the use of ANSI bold for numbers appearing to the left +of menuitems and the use of special +.Dq Li ansi +variables described below. +.It Va autoboot_delay +Number of seconds +.Ic menu-display +will wait before executing +.Va menu_timeout_command +.Ic ( boot +by default) unless a key is pressed. +If set to +.Dq Li NO +(case-insensitive) +.Ic menu-display +will wait for user input and never execute +.Ic menu_timeout_command . +If set to +.Dq Li -1 , +.Ic menu-display +will boot immediately, preventing both interruption of the +.Ic autoboot +process and escaping to the loader prompt. +Default is +.Dq Li 10 . +See +.Xr loader 7 +for additional information. +.It Va menu_timeout_command +The command to be executed after +.Va autoboot_delay +seconds if a key is not pressed. +The default is +.Ic boot . +.It Va loader_menu_frame +Sets the desired box style to draw around the boot menu. +Possible values are: +.Dq Li single +.Pq the default , +.Dq Li double , +and +.Dq Li none . +.It Va loader_menu_timeout_x +Sets the desired column position of the timeout countdown text. +Default is 4. +.It Va loader_menu_timeout_y +Sets the desired row position of the timeout countdown text. +Default is 23. +.It Va loader_menu_title +The text to display above the menu. +Default is +.Dq Li "Welcome to FreeBSD" . +.It Va loader_menu_title_align +Default is to align +.Ic loader_menu_title +centered above the menu. +This can be set to +.Dq Li left +or +.Dq Li right +to instead display the title left-or-right justified +.Pq respectively . +.It Va loader_menu_x +Sets the desired column position of the boot menu. +Default is 5. +.It Va loader_menu_y +Sets the desired row position of the boot menu. +Default is 10. +.It Va menu_caption[x] +The text to be displayed for the numbered menuitem +.Dq Li x . +.It Va menu_command[x] +The command to be executed when the number associated with menuitem +.Dq Li x +is pressed. +See the list of included FICL words below for some ideas. +.It Va menu_keycode[x] +An optional decimal ASCII keycode to be associated with menuitem +.Dq Li x . +When pressed, will cause the execution of +.Va menu_command[x] . +.It Va ansi_caption[x] +If +.Va loader_color +is set +.Pq enabled by default , +use this caption for menuitem +.Dq Li x +instead of +.Va menu_caption[x] . +.It Va toggled_text[x] +For menuitems where +.Va menu_command[x] +is set to +.Dq Li toggle_menuitem +(or a derivative thereof), the text displayed +will toggle between this and +.Va menu_caption[x] . +.It Va toggled_ansi[x] +Like +.Va toggled_text[x] +except used when +.Va loader_color +is enabled +.Pq default . +.It Va menu_caption[x][y] +For menuitems where +.Va menu_command[x] +is set to +.Dq Li cycle_menuitem +(or a derivative thereof), the text displayed will cycle between this and other +.Va menu_caption[x][y] +entries. +.It Va ansi_caption[x][y] +Like +.Va menu_caption[x][y] +except used when +.Va loader_color +is enabled +.Pq default . +.It Va menu_acpi +When set to a number +.Dq Li x +associated with a given menuitem, that menuitem will allow to select +acpi-user-options +.Pq see Xr eeprom 8 . +.It Va menu_options +When set to a number +.Dq Li x , +a single blank-line and an +.Dq Li Options +header are inserted between +.Va menu_caption[x-1] +and +.Va menu_caption[x] +(if configured). +.It Va menu_reboot +If set, adds a built-in +.Dq Li Reboot +menuitem to the end of the last configured menuitem. +If +.Va menu_options +is configured, the +.Dq Li Reboot +menuitem will be inserted before the +.Dq Options +separator. +.El +.Pp +In addition, it provides the following FICL words: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic arch-i386? ( -- BOOL ) +Returns true (-1) on i386 and false (0) otherwise. +.It Ic acpipresent? ( -- BOOL ) +Returns true (-1) if ACPI is present and false (0) otherwise. +.It Ic acpienabled? ( -- BOOL ) +Returns true (-1) if ACPI is enabled and false (0) otherwise. +.It Ic toggle_menuitem ( N -- N ) +Toggles menuitem +.Dq Li N +between +.Va menu_caption[x] +and +.Va toggled_text[x] +(where +.Dq Li N +represents the ASCII decimal value for +.Dq Li x ) . +.It Ic cycle_menuitem ( N -- N ) +Cycles menuitem +.Dq Li N +between +.Va menu_caption[x][y] +entries (where +.Va N +represents the ASCII decimal value for +.Va x ) . +.El +.Pp +For all values of +.Dq Li x +above, use any number between 1 through 9. +Sorry, double-digits are not currently supported. +.Sh FILES +.Bl -tag -width /boot/forth/loader.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/menu.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +A simple boot menu: +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/menu.4th +menu-init +set menu_caption[1]="Boot" +set menu_command[1]="boot" +set menu_options=2 +set menu_caption[2]="Option: NO" +set toggled_text[2]="Option: YES" +set menu_command[2]="toggle_menuitem" +set menu_timeout_command="boot" +set menu_reboot +menu-display +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr beastie.4th 7 , +.Xr loader 7 , +.Xr loader.4th 7 , +.Xr eeprom 8 diff --git a/usr/src/man/man7/menusets.4th.7 b/usr/src/man/man7/menusets.4th.7 new file mode 100644 index 0000000000..bd29efd1f6 --- /dev/null +++ b/usr/src/man/man7/menusets.4th.7 @@ -0,0 +1,359 @@ +.\" Copyright (c) 2012 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt MENUSETS.4TH 7 +.Os +.Sh NAME +.Nm menusets.4th +.Nd loader dynamic submenu boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to add submenu functionality to the dynamic menu +system provided by +.Xr menu.4th 7 . +Submenus are managed through a system of carefully named environment variables. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the examples below for the most common situations, and to +.Xr menu.4th 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include menusets.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu-commands.4th +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width menuset-loadinitial -compact -offset indent +.It Ic menuset-loadsetnum +Takes a single integer on the stack to identify the menuset environment +variables to be activated (see environment variables below). +.It Ic menuset-loadinitial +If $menuset_initial is set, passes the value to menuset-loadsetnum. +The value must be a number. +.It Ic menusets-unset +Unsets the environment variables associated with all menusets. +Increments starting at 1 and stops at the first unconfigured menuset. +A menuset is considered configured if the caption for item 1 is set. +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va menuset_initial +Number to pass to menuset-loadsetnum when menuset-loadinitial is called. +.It Va menuset_nameN +Used to give a name to a menuset. +.El +.Pp +When a menuset is NOT given a name (the default), +menuset N is comprised of the following environment variables: +.Pp +.Bl -tag -width menusetN_caption[x][y] -compact -offset indent +.It Va ansisetN_caption[x] +-> ansi_caption[x] +.It Va ansisetN_caption[x][y] +-> ansi_caption[x][y] +.It Va menusetN_acpi +-> menu_acpi +.It Va menusetN_caption[x] +-> menu_caption[x] +.It Va menusetN_caption[x][y] +-> menu_caption[x][y] +.It Va menusetN_command[x] +-> menu_command[x] +.It Va menusetN_init +-> +.Dq Li evaluated +.It Va menusetN_init[x] +-> menu_init[x] +.It Va menusetN_keycode[x] +-> menu_keycode[x] +.It Va menusetN_options +-> menu_options +.It Va menusetN_optionstext +-> menu_optionstext +.It Va menusetN_reboot +-> menu_reboot +.It Va toggledsetN_ansi[x] +-> toggled_ansi[x] +.It Va toggledsetN_text[x] +-> toggled_text[x] +.El +.Pp +When you choose to give a menuset a name (by setting $menuset_nameN), +menuset N is instead comprised of the following environment variables: +.Pp +.Bl -tag -width NAMEmenu_caption[x][y] -compact -offset indent +.It Va NAMEansi_caption[x] +-> ansi_caption[x] +.It Va NAMEansi_caption[x][y] +-> ansi_caption[x][y] +.It Va NAMEmenu_acpi +-> menu_acpi +.It Va NAMEmenu_caption[x] +-> menu_caption[x] +.It Va NAMEmenu_caption[x][y] +-> menu_caption[x][y] +.It Va NAMEmenu_command[x] +-> menu_command[x] +.It Va NAMEmenu_init +-> +.Dq Li evaluated +.It Va NAMEmenu_init[x] +-> menu_init[x] +.It Va NAMEmenu_keycode[x] +-> menu_keycode[x] +.It Va NAMEmenu_options +-> menu_options +.It Va NAMEmenu_optionstext +-> menu_optionstext +.It Va NAMEmenu_reboot +-> menu_reboot +.It Va NAMEtoggled_ansi[x] +-> toggled_ansi[x] +.It Va NAMEtoggled_text[x] +-> toggled_text[x] +.El +.Pp +where +.Dq Li NAME +is the value of $menuset_nameN. +In the case of $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset), +the value is evaluated as an FICL statement. +This can be used to dynamically adjust the menuset variables right before the +menu is activated. +.Pp +In addition, +.Nm +provides the following FICL words: +.Pp +.Bl -tag -width menuset -compact -offset indent +.It Ic menuset-checksetnum ( N -- ) +Given a single integer on the stack, sets a global variable +.Va menuset_use_name +to a boolean based on whether $menuset_nameN is set (true) or not (false). +Also sets $affix temporary variable (prefix or infix depending on +menuset_use_name). +Automatically called by menuset-loadsetnum and menusets-unset. +.It Ic menuset-loadvar ( -- ) +Used indirectly to shorten syntax and mitigate dictionary size. +Requires the following temporary environment variables: +.Pp +.Bl -tag -width affix -compact -offset indent +.It Va type +should be set to one of: menu toggled ansi +.It Va var +should be set to one of: caption command keycode text ... +.It Va affix +either a prefix (menuset_use_name is true) or infix (menuset_use_name is false) +.El +.Pp +If the global +.Va menuset_use_name +is true, the variable ${type}_${var} is made to +equal the value of the variable ${affix}${type}_${var} +(note: in this case menuset-checksetnum has set $affix to $menuset_nameN). +Otherwise (when +.Va menuset_use_name +is false), the variable ${type}_${var} is made to +equal the value of the variable ${type}set${affix}_${var} +(note: in this case menuset-checksetnum has set $affix to N). +.Pp +Both the global variable +.Va menuset_use_name +and the environment variable $affix are automatically handled by +menuset-checksetnum above (which is automatically called by +menuset-loadsetnum). +.It Ic menuset-unloadvar ( -- ) +Used indirectly to shorten syntax and mitigate dictionary size. +Like menuset-loadvar except it unsets the menuset variable. +If global +.Va menuset_use_name +is true ($affix is $menuset_nameN), +variable ${affix}${type}_${var} is unset. +Otherwise, $affix is N and variable ${type}set${affix}_${var} is unset. +.It Ic menuset-loadmenuvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-loadvar. +.It Ic menuset-unloadmenuvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-unloadvar. +.It Ic menuset-loadxvar ( -- ) +Like menuset-loadvar except it takes an additional temporary variable $x. +If the global +.Va menuset_use_name +is true (making $affix equal $menuset_nameN), +sets variable ${type}_${var}[${x}] to variable ${affix}${type}_${var}[${x}]. +Otherwise ($affix being N), sets the same variable to instead +${type}set{affix}_${var}[${x}]. +.It Ic menuset-unloadxvar ( -- ) +Like menuset-loadxvar except it unsets the menuset variable. +If global +.Va menuset_use_name +is true, unsets ${affix}${type}_${var}[${x}]. +Otherwise, unsets ${type}set${affix}_${var}[${x}]. +.It Ic menuset-loadansixvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-loadxvar +.It Ic menuset-unloadansixvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-unloadxvar +.It Ic menuset-loadmenuxvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-loadxvar +.It Ic menuset-unloadmenuxvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-unloadxvar +.It Ic menuset-loadtoggledxvar ( -- ) +Sets $type to +.Dq toggled +and calls menuset-loadxvar +.It Ic menuset-unloadtoggledxvar ( -- ) +Sets $type to +.Dq toggled +and calls menuset-unloadxvar +.It Ic menuset-loadxyvar ( -- ) +Like menuset-loadxvar except it takes an additional temporary variable $y. +If the global +.Va menuset_use_name +is true ($affix is $menuset_nameN), +sets variable ${type}_${var}[${x}][${y}] to ${affix}${type}_${var}[${x}][${y}]. +Otherwise ($affix is N) sets the same variable to instead +${type}set${affix}_${var}[${x}][${y}]. +.It Ic menuset-unloadxyvar ( -- ) +Like menuset-loadxyvar except it unsets the menuset variable. +If the global +.Va menuset_use_name +is true, unsets ${affix}${type}_${var}[${x}][${y}]. +Otherwise, unsets ${type}set${affix}_${var}[${x}][${y}]. +.It Ic menuset-loadansixyvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-loadxyvar. +.It Ic menuset-unloadansixyvar ( -- ) +Sets $type to +.Dq ansi +and calls menuset-unloadxyvar. +.It Ic menuset-loadmenuxyvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-loadxyvar. +.It Ic menuset-unloadmenuxyvar ( -- ) +Sets $type to +.Dq menu +and calls menuset-unloadxyvar. +.It Ic menuset-setnum-namevar ( N -- C-Addr/U ) +Takes a single integer on the stack and replaces it with a string (in c-addr/u +format) whose value is +.Dq menuset_nameN . +For example, if given 1 returns +.Dq menuset_name1 . +.It Ic menuset-cleanup ( N -- ) +Unsets all the various temporary variables, currently +.Va type , +.Va var , +.Va x , +.Va y , +and +.Va affix . +.El +.Pp +For all values of +.Dq Li x +above, use any number between 1 through 9. Sorry, double-digits are not +currently supported. +For all values of +.Dq Li N +above, use any number between 1 and 65535. +.Sh FILES +.Bl -tag -width /boot/menu-commands.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/menu.4th +Dynamic menu module. +.It Pa /boot/forth/menu-commands.4th +Contains the goto_menu command. +.It Pa /boot/forth/menusets.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +A simple boot menu with a submenu: +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/menu.4th +include /boot/forth/menu-commands.4th +menu-init +set menuset1_caption[1]="Boot" +set menuset1_command[1]="boot" +set menuset1_caption[2]="Submenu..." +set menuset1_command[2]="2 goto_menu" +set menuset2_caption[1]="Back" +set menuset2_command[1]="1 goto_menu" +set menuset_initial=2 +menuset-loadinitial +menu-display +.Ed +.Pp +The same boot menu with named menusets: +.Pp +.Bd -literal -offset indent -compact +include /boot/forth/menu.4th +include /boot/forth/menu-commands.4th +menu-init +set menuset_name1=main +set mainmenu_caption[1]="Boot" +set mainmenu_command[1]="boot" +set mainmenu_caption[2]="Submenu..." +set mainmenu_command[2]="2 goto_menu" +set menuset_name2=sub +set submenu_caption[1]="Back" +set submenu_command[1]="1 goto_menu" +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr beastie.4th 7 , +.Xr loader 7 , +.Xr loader.4th 7 , +.Xr menu.4th 7 diff --git a/usr/src/man/man7/mm.7 b/usr/src/man/man7/mm.7 new file mode 100644 index 0000000000..c78fad3d94 --- /dev/null +++ b/usr/src/man/man7/mm.7 @@ -0,0 +1,446 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, 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 MM 7 "Jan 1, 1997" +.SH NAME +mm \- text formatting (memorandum) macros +.SH SYNOPSIS +.LP +.nf +\fBnroff\fR \fB-mm\fR [\fIoptions\fR] \fIfilename\fR... +.fi + +.LP +.nf +\fBtroff\fR \fB-mm\fR [\fIoptions\fR] \fIfilename\fR... +.fi + +.SH DESCRIPTION +.sp +.LP +This package of \fBnroff\fR(1) and \fBtroff\fR(1) macro definitions provides a +formatting facility for various styles of articles, theses, and books. When +producing 2-column output on a terminal or lineprinter, or when reverse line +motions are needed, filter the output through \fBcol\fR(1). All external +\fB-mm\fR macros are defined below. +.sp +.LP +Note: this \fB-mm\fR macro package is an extended version written at Berkeley +and is a superset of the standard \fB-mm\fR macro packages as supplied by Bell +Labs. Some of the Bell Labs macros have been removed; for instance, it is +assumed that the user has little interest in producing headers stating that the +memo was generated at Whippany Labs. +.sp +.LP +Many \fBnroff\fR and \fBtroff\fR requests are unsafe in conjunction with this +package. However, the first four requests below may be used with impunity after +initialization, and the last two may be used even before initialization: +.sp +.ne 2 +.na +\fB\fB\&.bp\fR\fR +.ad +.RS 11n +begin new page +.RE + +.sp +.ne 2 +.na +\fB\fB\&.br\fR \fR +.ad +.RS 11n +break output line +.RE + +.sp +.ne 2 +.na +\fB\fB\&.sp\fR\fIn\fR \fR +.ad +.RS 11n +insert n spacing lines +.RE + +.sp +.ne 2 +.na +\fB\fB\&.ce\fR\fIn\fR \fR +.ad +.RS 11n +center next n lines +.RE + +.sp +.ne 2 +.na +\fB\fB\&.ls\fR\fIn\fR \fR +.ad +.RS 11n +line spacing: \fIn\fR\fB=1\fR single, \fIn\fR\fB=2\fR double space +.RE + +.sp +.ne 2 +.na +\fB\fB\&.na\fR \fR +.ad +.RS 11n +no alignment of right margin +.RE + +.sp +.LP +Font and point size changes with \fB\ef\fR and \fB\es\fR are also allowed; for +example, \fB\efIword\efR\fR will italicize \fIword\fR. Output of the +\fBtbl\fR(1), \fBeqn\fR(1) and \fBrefer\fR(1) preprocessors for equations, +tables, and references is acceptable as input. +.SH REQUESTS +.sp +.LP +Here is a table of macros. +.sp + +.sp +.TS +c | c | c | c +l | l | l | l . +Macro Name Initial Value Break? Reset? Explanation +_ +\fB\&.1C\fR on y,y one column format on a new page +_ +\fB\&.2C\fR [ \fIl\fR ] - y,y two column format \fIl\fR=line length +_ +\fB\&.AE\fR - y end abstract +_ +\fB\&.AL\fR [ \fIt\fR ] [ \fIi\fR ] [ \fIs\fR ] \fIt\fR=\fB1\fR;\fIi\fR=\fB\&.Li\fR;\fIs\fR=\fB0\fR y T{ +Start automatic list type \fIt\fR=[\fB1\fR,\fBA\fR,\fBa\fR,\fBI\fR,\fBi\fR] \fB1\fR=arabic numbers; \fBA\fR=uppercase letters \fBa\fR=lowercase letters; \fBI\fR=uppercase Roman numerals; \fBi\fR=lowercase Roman numerals indentation \fIi\fR; separation \fIs\fR +T} +_ +\fB\&.AS\fR \fIm\fR [ \fIn\fR ] \fIn\fR=\fB0\fR y begin abstract +_ +\fB\&.AU\fR - y author's name +_ +\fB\&.AV\fR \fIx\fR - y signature and date line of verifier \fIx\fR +_ +\fB\&.B\fR \fIx\fR - n embolden \fIx\fR; if no \fIx\fR, switch to boldface +_ +\fB\&.BE\fR - y end block text +_ +\fB\&.BI\fR \fIx\fR \fIy\fR - n embolden \fIx\fR and underline \fIy\fR +_ +\fB\&.BL\fR - y bullet list +_ +\fB\&.BR\fR \fIx\fR \fIy\fR - n embolden \fIx\fR and use Roman font for \fIy\fR +_ +\fB\&.BS\fR - n start block text +_ +\fB\&.CN\fR - y same as \fB\&.DE\fR (\fBnroff\fR) +_ +\fB\&.CS\fR - y cover sheet +_ +\fB\&.CW\fR - n same as \fB\&.DS I\fR (\fBnroff\fR) +_ +\fB\&.DE\fR - y end display +_ +\fB\&.DF\fR [ \fIp\fR ] [ \fIf\fR ] [ \fIrp\fR ] \fIp\fR=\fBL\fR;\fIf\fR=\fBN\fR y T{ +start floating display; position \fIp\fR=[\fBL\fR,\fBC\fR,\fBCB\fR] \fBL\fR=left; \fBI\fR=indent; \fBC\fR=center; \fBCB\fR=center block fill \fIf\fR=[\fBN\fR,\fBY\fR]; right position \fIrp\fR (fill only) +T} +_ +\fB\&.DL\fR [ \fIi\fR ] [ \fIs\fR ] - y start dash list +_ +\fB\&.DS\fR [ \fIp\fR ] [ \fIf\fR ] [ \fIrp\fR ] \fIp\fR=\fBL\fR;\fIf\fR=\fBN\fR y T{ +begin static display (see \fB\&.DF\fR for argument descriptions) +T} +_ +\fB\&.EC\fR \fIx\fR [ \fIn\fR ] \fIn\fR=\fB1\fR y equation title; equation \fIx\fR; number \fIn\fR +_ +\fB\&.EF\fR \fIx\fR - n T{ +even footer appears at the bottom of even-numbered pages; \fIx\fR="\fIl\fR\fB\&'\fR\fIc\fR\fB\&'\fR\fIr\fR" \fIl\fR=left; \fIc\fR=center; \fIr\fR=right +T} +_ +\fB\&.EH\fR \fIx\fR - n T{ +even header appears at the top of even-numbered pages; \fIx\fR="\fIl\fR\fB\&'\fR\fIc\fR\fB\&'\fR\fIr\fR" \fIl\fR=left; \fIc\fR=center; \fIr\fR=right +T} +_ +\fB\&.EN\fR - y end displayed equation produced by \fBeqn\fR +_ +\fB\&.EQ\fR - y break out equation produced by \fBeqn\fR +_ +\fB\&.EX\fR \fIx\fR [ \fIn\fR ] \fIn\fR=\fB1\fR y exhibit title; exhibit \fIx\fR +_ + number \fIn\fR +_ +\fB\&.FD\fR [ \fIf\fR ] [ \fIr\fR ] \fIf\fR=\fB10\fR;\fIr\fR=\fB1\fR n T{ +set footnote style format \fIf\fR=[\fB0-11\fR]; renumber \fIr\fR=[\fB0\fR,\fB1\fR] +T} +_ +\fB\&.FE\fR - y end footnote +_ +\fB\&.FG\fR \fIx\fR [ \fIn\fR ] \fIn\fR=\fB1\fR y figure title; figure \fIx\fR; number \fIn\fR +_ +\fB\&.FS\fR - n start footnote +_ +\fB\&.H\fR \fIl\fR [ \fIt\fR ] - y T{ +produce numbered heading level \fIl\fR=[\fB1-7\fR]; title \fIt\fR +T} +_ +\fB\&.HU\fR \fIt\fR - y produce unnumbered heading; title \fIt\fR +_ +\fB\&.I\fR \fIx\fR - n underline \fIx\fR +_ +\fB\&.IB\fR \fIx\fR \fIy\fR - n underline \fIx\fR and embolden \fIy\fR +_ +\fB\&.IR\fR \fIx\fR \fIy\fR - n underline \fIx\fR and use Roman font on \fIy\fR +_ +\fB\&.LE\fR [ \fIs\fR ] \fIs\fR=\fB0\fR y end list; separation \fIs\fR +_ +\fB\&.LI\fR [ \fIm\fR ] [ \fIp\fR ] - y start new list item; mark \fIm\fR +_ + prefix \fIp\fR (mark only) +_ +\fB\&.ML\fR \fIm\fR [ \fIi\fR ] [ \fIs\fR ] \fIs\fR=\fB0\fR y T{ +start marked list; mark \fIm\fR indentation \fIi\fR; separation \fIs\fR=[\fB0\fR,\fB1\fR] +T} +_ +\fB\&.MT\fR \fIx\fR y memo title; title \fIx\fR +_ +\fB\&.ND\fR \fIx\fR n T{ +no date in page footer; \fIx\fR is date on cover +T} +_ +\fB\&.NE\fR - y end block text +_ +\fB\&.NS\fR - y start block text +_ +\fB\&.OF\fR \fIx\fR - n T{ +odd footer appears at the bottom of odd-numbered pages; \fIx\fR="\fIl\fR\fB\&'\fR\fIc\fR\fB\&'\fR\fIr\fR" \fIl\fR=left; \fIc\fR=center; \fIr\fR=right +T} +_ +\fB\&.OF\fR \fIx\fR - n T{ +odd header appears at the top of odd-numbered pages; \fIx\fR="\fIl\fR\fB\&'\fR\fIc\fR\fB\&'\fR\fIr\fR" \fIl\fR=left; \fIc\fR=center; \fIr\fR=right +T} +_ +\fB\&.OP\fR - y skip to the top of an odd-number page +_ +\fB\&.P\fR [ \fIt\fR ] \fIt\fR=\fB0\fR y,y T{ +begin paragraph; \fIt\fR=[\fB0\fR,\fB1\fR] \fB0\fR=justified; \fB1\fR=indented +T} +_ +\fB\&.PF\fR \fIx\fR - n T{ +page footer appears at the bottom of every page; \fIx\fR="\fIl\fR\fB\&'\fR\fIc\fR\fB\&'\fR\fIr\fR" \fIl\fR=left; \fIc\fR=center; \fIr\fR=right +T} +_ +\fB\&.PH\fR \fIx\fR - n T{ +page header appears at the top of every page; \fIx\fR="\fIl\fR\fB\&'\fR\fIc\fR\fB\&'\fR\fIr\fR" \fIl\fR=left; \fIc\fR=center; \fIr\fR=right +T} +_ +\fB\&.R\fR on n return to Roman font +_ +\fB\&.RB\fR \fIx\fR \fIy\fR - n use Roman on \fIx\fR and embolden \fIy\fR +_ +\fB\&.RI\fR \fIx\fR \fIy\fR - n use Roman on \fIx\fR and underline \fIy\fR +_ +\fB\&.RP\fR \fIx\fR - y,y T{ +released paper format ? \fIx\fR=no stops title on first +T} +_ +\fB\&.RS\fR 5n y,y T{ +right shift: start level of relative indentation +T} +_ +\fB\&.S\fR \fIm\fR \fIn\fR - n T{ +set character point size & vertical space character point size \fIm\fR; vertical space \fIn\fR +T} +_ +\fB\&.SA\fR \fIx\fR \fIx\fR=\fB1\fR n justification; \fIx\fR=[\fB0\fR,\fB1\fR] +_ +\fB\&.SK\fR \fIx\fR - y skip \fIx\fR pages +_ +\fB\&.SM\fR - n smaller; decrease point size by 2 +_ +\fB\&.SP\fR [ \fIx\fR ] - y leave \fIx\fR blank lines +_ +\fB\&.TB\fR \fIx\fR [ \fIn\fR ] \fIn\fR=\fB1\fR y table title; table \fIx\fR; number \fIn\fR +_ +\fB\&.TC\fR - y T{ +print table of contents (put at end of input file) +T} +_ +_ +\fB\&.TH\fR - Y "multi-page end, header" +_ +\fB\&.TL\fR - n title in boldface and two points larger +_ +\fB\&.TM\fR - n UC Berkeley thesis mode +_ +\fB\&.TP\fR \fIi\fR y y T{ +\fIi\fR=p.i. Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to \fIi\fR. +T} +_ +\fB\&.TE\fR - y end of table processed by tbl +\fB\&.TS\fR \fIx\fR - y,y T{ +begin table; if \fIx\fR=\fBH\fR table has multi-page header +T} +_ +\fB\&.TY\fR - y display centered title \fBCONTENTS\fR +_ +\fB\&.VL\fR \fIi\fR [ \fIm\fR ] [ \fIs\fR ] \fIm\fR=\fB0\fR;\fIs\fR=\fB0\fR y T{ +start variable-item list; indentation \fIi\fR mark-indentation \fIm\fR; separation \fIs\fR +T} +.TE + +.SH REGISTERS +.sp +.LP +Formatting distances can be controlled in \fB-mm\fR by means of built-in number +registers. For example, this sets the line length to 6.5 inches: +.sp +.in +2 +.nf +\&.nr LL 6.5i +.fi +.in -2 + +.sp +.LP +Here is a table of number registers and their default values: +.sp + +.sp +.TS +c | c | c | c +l | l | l | l . +Name Register Controls Takes Effect Default +_ +\fBCl\fR contents level table of contents 2 +_ +\fBDe\fR display eject display 0 +_ +\fBDf\fR display floating display 5 +_ +\fBDs\fR display spacing display 1v +_ +\fBHb\fR heading break heading 2 +_ +\fBHc\fR heading centering heading 0 +_ +\fBHi\fR heading indent heading 1 +_ +\fBHi\fR heading spacing heading 1 +_ +\fBHu\fR heading unnumbered heading 2 +_ +\fBLi\fR list indentation list \fB6 (\fR\fBnroff\fR\fB) 5 (\fR\fBtroff\fR\fB)\fR +_ +\fBLs\fR list spacing list 6 +_ +\fBPi\fR paragraph indent paragraph 5 +_ +\fBPt\fR paragraph type paragraph 1 +_ +\fBSi\fR static indent display \fB5 (\fR\fBnroff\fR\fB) 3 (\fR\fBtroff\fR\fB)\fR +.TE + +.sp +.LP +When resetting these values, make sure to specify the appropriate units. +Setting the line length to 7, for example, will result in output with one +character per line. Setting \fBPi\fR to 0 suppresses paragraph indentation +.sp +.LP +Here is a list of string registers available in \fB-mm\fR; they may be used +anywhere in the text: +.sp + +.sp +.TS +c | c +l | l . +Name String's Function +_ +\fB\e*Q\fR quote (\fB"\fR in \fBnroff,\fR\| \fB``\fR in \fBtroff\fR ) +_ +\fB\e*U\fR unquote (\fB"\fR in \fBnroff,\fR\| \fB\&''\fR in \fBtroff\fR ) +_ +\fB\e*-\fR dash (\fB--\fR in \fBnroff,\fR \(em in \fBtroff\fR ) +_ +\fB\e*(MO\fR month (month of the year) +_ +\fB\e*(DY\fR day (current date) +_ +\fB\e**\fR automatically numbered footnote +_ +\fB\e*'\fR acute accent (before letter) +_ +\fB\e*`\fR grave accent (before letter) +_ +\fB\e*^\fR circumflex (before letter) +_ +\fB\e*,\fR cedilla (before letter) +_ +\fB\e*:\fR umlaut (before letter) +_ +\fB\e*~\fR tilde (before letter) +_ +\fB\e(BU\fR bullet item +_ +\fB\e(DT\fR date (\fImonth day\fR, \fIyr\fR) +_ +\fB\e(EM\fR em dash +_ +\fB\e(Lf\fR \fBLIST OF FIGURES\fR title +_ +\fB\e(Lt\fR \fBLIST OF TABLES\fR title +_ +\fB\e(Lx\fR \fBLIST OF EXHIBITS\fR title +_ +\fB\e(Le\fR \fBLIST OF EQUATIONS\fR title +_ +\fB\e(Rp\fR \fBREFERENCES\fR title +_ +\fB\e(Tm\fR trademark character (TM) +.TE + +.sp +.LP +When using the extended accent mark definitions available with \fB\&.AM\fR, +these strings should come after, rather than before, the letter to be accented. +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/m\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/mm.[nt]\fR\fR +.ad +.sp .6 +.RS 4n +\fBnroff\fR and \fBtroff\fR definitions of \fBmm\fR. +.RE + +.SH SEE ALSO +.sp +.LP +.BR col (1), +.BR eqn (1), +.BR nroff (1), +.BR refer (1), +.BR tbl (1), +.BR troff (1), +.BR attributes (7) +.SH BUGS +.sp +.LP +Floating keeps and regular keeps are diverted to the same space, so they cannot +be mixed together with predictable results. diff --git a/usr/src/man/man7/ms.7 b/usr/src/man/man7/ms.7 new file mode 100644 index 0000000000..875e34aaad --- /dev/null +++ b/usr/src/man/man7/ms.7 @@ -0,0 +1,436 @@ +'\" te +.\" Copyright (c) 1992, Sun Microsystems, 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 MS 7 "Feb 25, 1992" +.SH NAME +ms \- text formatting macros +.SH SYNOPSIS +.LP +.nf +\fBnroff\fR \fB-ms\fR [\fIoptions\fR] \fIfilename\fR... +.fi + +.LP +.nf +\fBtroff\fR \fB-ms\fR [\fIoptions\fR] \fIfilename\fR... +.fi + +.SH DESCRIPTION +.sp +.LP +This package of \fBnroff\fR(1) and \fBtroff\fR(1) macro definitions provides a +formatting facility for various styles of articles, theses, and books. When +producing 2-column output on a terminal or lineprinter, or when reverse line +motions are needed, filter the output through \fBcol\fR(1). All external +\fB-ms\fR macros are defined below. +.sp +.LP +Note: this \fB-ms\fR macro package is an extended version written at Berkeley +and is a superset of the standard \fB-ms\fR macro packages as supplied by Bell +Labs. Some of the Bell Labs macros have been removed; for instance, it is +assumed that the user has little interest in producing headers stating that the +memo was generated at Whippany Labs. +.sp +.LP +Many \fBnroff\fR and \fBtroff\fR requests are unsafe in conjunction with this +package. However, the first four requests below may be used with impunity after +initialization, and the last two may be used even before initialization: +.sp +.ne 2 +.na +\fB\fB\&.bp\fR\fR +.ad +.RS 11n +begin new page +.RE + +.sp +.ne 2 +.na +\fB\fB\&.br\fR\fR +.ad +.RS 11n +break output line +.RE + +.sp +.ne 2 +.na +\fB\fB\&.sp\fR\fI n\fR\fR +.ad +.RS 11n +insert n spacing lines +.RE + +.sp +.ne 2 +.na +\fB\fB\&.ce\fR\fI n\fR\fR +.ad +.RS 11n +center next n lines +.RE + +.sp +.ne 2 +.na +\fB\fB\&.ls\fR\fI n\fR\fR +.ad +.RS 11n +line spacing: \fIn\fR\fB=1\fR single, \fIn\fR\fB=2\fR double space +.RE + +.sp +.ne 2 +.na +\fB\fB\&.na\fR\fR +.ad +.RS 11n +no alignment of right margin +.RE + +.sp +.LP +Font and point size changes with \fB\ef\fR and \fB\es\fR are also allowed; for +example, \fB\efIword\efR\fR will italicize \fIword\fR. Output of the +\fBtbl\fR(1), \fBeqn\fR(1) and \fBrefer\fR(1) preprocessors for equations, +tables, and references is acceptable as input. +.SH REQUESTS +.sp + +.sp +.TS +c | c | c | c +l | l | l | l . +Macro Name Initial Value Break? Reset? Explanation +_ +\fB\&.AB\fR \fIx\fR - y T{ +begin abstract; if \fIx\fR=no do not label abstract +T} +_ +\fB\&.AE\fR - y end abstract +_ +\fB\&.AI\fR - y author's institution +_ +\fB\&.AM\fR - n better accent mark definitions +_ +\fB\&.AU\fR - y author's name +_ +\fB\&.B\fR \fIx\fR - n embolden \fIx\fR; if no \fIx\fR, switch to boldface +_ +\fB\&.B1\fR - y begin text to be enclosed in a box +_ +\fB\&.B2\fR - y end boxed text and print it +_ +\fB\&.BT\fR date n bottom title, printed at foot of page +_ +\fB\&.BX\fR \fIx\fR - n print word \fIx\fR in a box +_ +\fB\&.CM\fR if t n cut mark between pages +_ +\fB\&.CT\fR - y,y T{ +chapter title: page number moved to CF (TM only) +T} +_ +\fB\&.DA\fR \fIx\fR if n n T{ +force date \fIx\fR at bottom of page; today if no \fIx\fR +T} +_ +\fB\&.DE\fR - y end display (unfilled text) of any kind +_ +\fB\&.DS\fR \fIx y\fR I y T{ +begin display with keep; \fIx\fR=I,\|L,\|C,\|B; \fIy\fR=indent +T} +_ +\fB\&.ID\fR\fI y\fR 8n,.5i y indented display with no keep; \fIy\fR=indent +_ +\fB\&.LD\fR - y left display with no keep +_ +\fB\&.CD\fR - y centered display with no keep +_ +\fB\&.BD\fR - y block display; center entire block +_ +\fB\&.EF\fR \fIx\fR - n even page footer \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.EH\fR \fIx\fR - n even page header \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.EN\fR - y end displayed equation produced by \fBeqn\fR +_ +\fB\&.EQ\fR \fIx y\fR - y T{ +break out equation; \fIx\fR=L,I,C; \fIy\fR=equation number +T} +_ +\fB\&.FE\fR - n T{ +end footnote to be placed at bottom of page +T} +_ +\fB\&.FP\fR - n T{ +numbered footnote paragraph; may be redefined +T} +_ +\fB\&.FS\fR \fIx\fR - n T{ +start footnote; \fIx\fR is optional footnote label +T} +_ +\fB\&.HD\fR undef n optional page header below header margin +_ +\fB\&.I\fR \fIx\fR - n italicize \fIx\fR; if no \fIx\fR, switch to italics +_ +\fB\&.IP\fR \fIx y\fR - y,y T{ +indented paragraph, with hanging tag \fIx\fR; \fIy\fR=indent +T} +_ +\fB\&.IX\fR \fIx y\fR - y T{ +index words \fIx\fR \fIy\fR and so on (up to 5 levels) +T} +_ +\fB\&.KE\fR - n end keep of any kind +_ +\fB\&.KF\fR - n T{ +begin floating keep; text fills remainder of page +T} +_ +\fB\&.KS\fR - y T{ +begin keep; unit kept together on a single page +T} +_ +\fB\&.LG\fR - n larger; increase point size by 2 +_ +\fB\&.LP\fR - y,y left (block) paragraph. +_ +\fB\&.MC\fR \fIx\fR - y,y multiple columns; \fIx\fR=column width +_ +\fB\&.ND\fR \fIx\fR if t n T{ +no date in page footer; \fIx\fR is date on cover +T} +_ +\fB\&.NH\fR \fIx y\fR - y,y T{ +numbered header; \fIx\fR=level, \fIx\fR=0 resets, \fIx\fR=S sets to \fIy\fR +T} +_ +\fB\&.NL\fR 10p n set point size back to normal +_ +\fB\&.OF\fR \fIx\fR - n odd page footer \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.OH\fR \fIx\fR - n odd page header \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.P1\fR if TM n print header on first page +_ +\fB\&.PP\fR - y,y paragraph with first line indented +_ +\fB\&.PT\fR - % - n page title, printed at head of page +_ +\fB\&.PX\fR \fIx\fR - y T{ +print index (table of contents); \fIx\fR=no suppresses title +T} +_ +\fB\&.QP\fR - y,y quote paragraph (indented and shorter) +_ +\fB\&.R\fR on n return to Roman font +_ +\fB\&.RE\fR 5n y,y T{ +retreat: end level of relative indentation +T} +_ +\fB\&.RP\fR \fIx\fR - n T{ +released paper format; \fIx\fR=no stops title on first page +T} +_ +\fB\&.RS\fR 5n y,y T{ +right shift: start level of relative indentation +T} +_ +\fB\&.SH\fR - y,y section header, in boldface +_ +\fB\&.SM\fR - n smaller; decrease point size by 2 +_ +\fB\&.TA\fR 8n,5n n T{ +set TAB characters to 8n 16n .\|.\|. (\fBnroff\fR) or 5n 10n .\|.\|. (\fBtroff\fR) +T} +_ +\fB\&.TC\fR \fIx\fR - y T{ +print table of contents at end; \fIx\fR=no suppresses title +T} +_ +_ +\fB\&.TH\fR - Y "multi-page end, header" +_ +\fB\&.TL\fR - y title in boldface and two points larger +_ +\fB\&.TM\fR off n UC Berkeley thesis mode +_ +\fB\&.TE\fR - y end of table processed by \fBtbl\fR +\fB\&.TS\fR \fIx\fR - y,y T{ +begin table; if \fIx\fR=H table has multi-page header +T} +_ +\fB\&.UL\fR \fIx\fR - n underline \fIx\fR, even in \fBtroff\fR +_ +\fB\&.UX\fR \fIx\fR - n T{ +UNIX; trademark message first time; \fIx\fR appended +T} +_ +\fB\&.XA\fR \fIx y\fR - y T{ +another index entry; \fIx\fR=page or no for none; y=indent +T} +_ +\fB\&.XE\fR - y T{ +end index entry (or series of \fB\&.IX\fR entries) +T} +_ +\fB\&.XP\fR - y,y T{ +paragraph with first line indented, others indented +T} +_ +\fB\&.XS\fR \fIx y\fR - y T{ +begin index entry; \fIx\fR=page or no for none; \fIy\fR=indent +T} +_ +\fB\&.1C\fR on y,y one column format, on a new page +_ +\fB\&.2C\fR - y,y begin two column format +_ +\fB\&.]\|-\fR - n beginning of \fBrefer\fR reference +_ +\fB\&.[\|0\fR - n end of unclassifiable type of reference +_ +\fB\&.[\|N\fR - n T{ +N= 1:journal-article, 2:book, 3:book-article, 4:report +T} +.TE + +.SH REGISTERS +.sp +.LP +Formatting distances can be controlled in \fB-ms\fR by means of built-in number +registers. For example, this sets the line length to 6.5 inches: +.sp +.in +2 +.nf +\&.nr LL 6.5i +.fi +.in -2 + +.sp +.LP +Here is a table of number registers and their default values: +.sp + +.sp +.TS +c | c | c | c +l | l | l | l . +Name Register Controls Takes Effect Default +_ +\fBPS\fR point size paragraph 10 +_ +\fBVS\fR vertical spacing paragraph 12 +_ +\fBLL\fR line length paragraph 6i +_ +\fBLT\fR title length next page same as \fBLL\fR +_ +\fBFL\fR footnote length next \fB\&.FS\fR 5.5i +_ +\fBPD\fR paragraph distance paragraph 1v (if n), .3v (if t) +_ +\fBDD\fR display distance displays 1v (if n), .5v (if t) +_ +\fBPI\fR paragraph indent paragraph 5n +_ +\fBQI\fR quote indent next \fB\&.QP\fR 5n +_ +\fBFI\fR footnote indent next \fB\&.FS\fR 2n +_ +\fBPO\fR page offset next page 0 (if n), \(ap1i (if t) +_ +\fBHM\fR header margin next page 1i +_ +\fBFM\fR footer margin next page 1i +_ +\fBFF\fR footnote format next \fB\&.FS\fR 0 (1, 2, 3 available) +.TE + +.sp +.LP +When resetting these values, make sure to specify the appropriate units. +Setting the line length to 7, for example, will result in output with one +character per line. Setting \fBFF\fR to 1 suppresses footnote superscripting; +setting it to 2 also suppresses indentation of the first line; and setting it +to 3 produces an \fB\&.IP\fR-like footnote paragraph. +.sp +.LP +Here is a list of string registers available in \fB-ms\fR; they may be used +anywhere in the text: +.sp + +.sp +.TS +c | c +l | l . +Name String's Function +_ +\fB\e*Q\fR quote (\fB"\fR in \fBnroff,\fR\| \fB"\fR in \fBtroff\fR ) +_ +\fB\e*U\fR unquote (\fB"\fR in \fBnroff,\fR\| \fB"\fR in \fBtroff\fR ) +_ +\fB\e*-\fR dash (\fB--\fR in \fBnroff,\fR \fB\(em\fR in \fBtroff\fR ) +_ +\fB\e*(MO\fR month (month of the year) +_ +\fB\e*(DY\fR day (current date) +_ +\fB\e**\fR automatically numbered footnote +_ +\fB\e*'\fR acute accent (before letter) +_ +\fB\e*`\fR grave accent (before letter) +_ +\fB\e*^\fR circumflex (before letter) +_ +\fB\e*,\fR cedilla (before letter) +_ +\fB\e*:\fR umlaut (before letter) +_ +\fB\e*~\fR tilde (before letter) +.TE + +.sp +.LP +When using the extended accent mark definitions available with \fB\&.AM\fR, +these strings should come after, rather than before, the letter to be accented. +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/s\fR\fR +.ad +.RS 30n + +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/tmac/ms.???\fR\fR +.ad +.RS 30n + +.RE + +.SH SEE ALSO +.sp +.LP +.BR col (1), +.BR eqn (1), +.BR nroff (1), +.BR refer (1), +.BR tbl (1), +.BR troff (1) +.SH BUGS +.sp +.LP +Floating keeps and regular keeps are diverted to the same space, so they cannot +be mixed together with predictable results. diff --git a/usr/src/man/man7/mutex.7 b/usr/src/man/man7/mutex.7 new file mode 100644 index 0000000000..51a99249bc --- /dev/null +++ b/usr/src/man/man7/mutex.7 @@ -0,0 +1,187 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved. +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. +.\" +.TH MUTEX 7 "Jun 5, 2007" +.SH NAME +mutex \- concepts relating to mutual exclusion locks +.SH DESCRIPTION +.sp +.LP +Mutual exclusion locks (mutexes) prevent multiple threads from simultaneously +executing critical sections of code which access shared data (that is, mutexes +are used to serialize the execution of threads). All mutexes must be global. A +successful call to acquire a mutex will cause another thread that is also +trying to lock the same mutex to block until the owner thread unlocks the +mutex. +.sp +.LP +Mutexes can synchronize threads within the same process or in other processes. +Mutexes can be used to synchronize threads between processes if the mutexes are +allocated in writable memory and shared among the cooperating processes (see +\fBmmap\fR(2)), and have been initialized for this task. +.sp +.LP +The following table lists mutex functions and the actions they perform. +.sp + +.sp +.TS +box; +c | c +l | l . +FUNCTION ACTION +_ +\fBmutex_init\fR Initialize a mutex. +\fBmutex_destroy\fR Destroy a mutex. +\fBmutex_lock\fR Lock a mutex. +\fBmutex_trylock\fR Attempt to lock a mutex. +\fBmutex_unlock\fR Unlock a mutex. +\fBpthread_mutex_init\fR Initialize a mutex. +\fBpthread_mutex_destroy\fR Destroy a mutex. +\fBpthread_mutex_lock\fR Lock a mutex. +\fBpthread_mutex_trylock\fR Attempt to lock a mutex. +\fBpthread_mutex_unlock\fR Unlock a mutex. +.TE + +.SS "Initialization" +.sp +.LP +Mutexes are either intra-process or inter-process, depending upon the argument +passed implicitly or explicitly to the initialization of that mutex. A +statically allocated mutex does not need to be explicitly initialized; by +default, a statically allocated mutex is initialized with all zeros and its +scope is set to be within the calling process. +.sp +.LP +For inter-process synchronization, a mutex needs to be allocated in memory +shared between these processes. Since the memory for such a mutex must be +allocated dynamically, the mutex needs to be explicitly initialized with the +appropriate attribute that indicates inter-process use. +.SS "Locking and Unlocking" +.sp +.LP +A critical section of code is enclosed by a call to lock the mutex and the call +to unlock the mutex to protect it from simultaneous access by multiple threads. +Only one thread at a time may possess mutually exclusive access to the critical +section of code that is enclosed by the mutex-locking call and the +mutex-unlocking call, whether the mutex's scope is intra-process or +inter-process. A thread calling to lock the mutex either gets exclusive access +to the code starting from the successful locking until its call to unlock the +mutex, or it waits until the mutex is unlocked by the thread that locked it. +.sp +.LP +Mutexes have ownership, unlike semaphores. Only the thread that locked a mutex, +(that is, the owner of the mutex), should unlock it. +.sp +.LP +If a thread waiting for a mutex receives a signal, upon return from the signal +handler, the thread resumes waiting for the mutex as if there was no interrupt. +.SS "Caveats" +.sp +.LP +Mutexes are almost like data - they can be embedded in data structures, files, +dynamic or static memory, and so forth. Hence, they are easy to introduce into +a program. However, too many mutexes can degrade performance and scalability of +the application. Because too few mutexes can hinder the concurrency of the +application, they should be introduced with care. Also, incorrect usage (such +as recursive calls, or violation of locking order, and so forth) can lead to +deadlocks, or worse, data inconsistencies. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +.BR mmap (2), +.BR shmop (2), +.BR mutex_destroy (3C), +.BR mutex_init (3C), +.BR mutex_lock (3C), +.BR mutex_trylock (3C), +.BR mutex_unlock (3C), +.BR pthread_create (3C), +.BR pthread_mutex_destroy (3C), +.BR pthread_mutex_init (3C), +.BR pthread_mutex_lock (3C), +.BR pthread_mutex_trylock (3C), +.BR pthread_mutex_unlock (3C), +.BR pthread_mutexattr_init (3C), +.BR attributes (7), +.BR standards (7) +.SH NOTES +.sp +.LP +In the current implementation of threads, \fBpthread_mutex_lock()\fR, +\fBpthread_mutex_unlock()\fR, \fBmutex_lock()\fR \fBmutex_unlock()\fR, +\fBpthread_mutex_trylock()\fR, and \fBmutex_trylock()\fR do not validate the +mutex type. Therefore, an uninitialized mutex or a mutex with an invalid type +does not return \fBEINVAL\fR. Interfaces for mutexes with an invalid type have +unspecified behavior. +.sp +.LP +By default, if multiple threads are waiting for a mutex, the order of +acquisition is undefined. +.sp +.LP +The system does not support multiple mappings to the same logical synch object +if it is initialized as process-private (\fBUSYNC_THREAD\fR for Solaris, +\fBPTHREAD_PROCESS_PRIVATE\fR for POSIX). If you need to \fBmmap\fR(2)a synch +object to different locations within the same address space, then the synch +object should be initialized as a shared object (\fBUSYNC_PROCESS\fR for +Solaris, \fBPTHREAD_PROCESS_SHARED\fR for POSIX). diff --git a/usr/src/man/man7/nfssec.7 b/usr/src/man/man7/nfssec.7 new file mode 100644 index 0000000000..3e76479194 --- /dev/null +++ b/usr/src/man/man7/nfssec.7 @@ -0,0 +1,147 @@ +'\" te +.\" Copyright 2014 Nexenta Systems, Inc. All rights reserved. +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH NFSSEC 7 "Nov 20, 2014" +.SH NAME +nfssec \- overview of NFS security modes +.SH DESCRIPTION +.LP +The \fBmount_nfs\fR(8) and \fBshare_nfs\fR(8) commands each provide a way to +specify the security mode to be used on an \fBNFS\fR file system through the +\fBsec=\fR\fImode\fR option. \fImode\fR can be \fBsys\fR, \fBdh\fR, \fBkrb5\fR, +\fBkrb5i\fR, \fBkrb5p\fR, or \fBnone\fR. These security modes can also be added +to the automount maps. Note that \fBmount_nfs\fR(8) and \fBautomount\fR(8) do +not support \fBsec=none\fR at this time. \fBmount_nfs\fR(8) allows you to +specify a single security mode; \fBshare_nfs\fR(8) allows you to specify +multiple modes (or \fBnone\fR). With multiple modes, an NFS client can choose +any of the modes in the list. +.sp +.LP +The \fBsec=\fR\fImode\fR option on the \fBshare_nfs\fR(8) command line +establishes the security mode of \fBNFS\fR servers. If the \fBNFS\fR connection +uses the \fBNFS\fR Version 3 protocol, the \fBNFS\fR clients must query the +server for the appropriate \fImode\fR to use. If the \fBNFS\fR connection uses +the \fBNFS\fR Version 2 protocol, then the \fBNFS\fR client uses the default +security mode, which is currently \fBsys\fR. \fBNFS\fR clients may force the +use of a specific security mode by specifying the \fBsec=\fR\fImode\fR option +on the command line. However, if the file system on the server is not shared +with that security mode, the client may be denied access. +.sp +.LP +If the \fBNFS\fR client wants to authenticate the \fBNFS\fR server using a +particular (stronger) security mode, the client wants to specify the security +mode to be used, even if the connection uses the \fBNFS\fR Version 3 protocol. +This guarantees that an attacker masquerading as the server does not compromise +the client. +.sp +.LP +The \fBNFS\fR security modes are described below. Of these, the \fBkrb5\fR, +\fBkrb5i\fR, \fBkrb5p\fR modes use the Kerberos V5 protocol for authenticating +and protecting the shared filesystems. Before these can be used, the system +must be configured to be part of a Kerberos realm. See \fBkerberos\fR(7). +.sp +.ne 2 +.na +\fB\fBsys\fR\fR +.ad +.RS 9n +Use \fBAUTH_SYS\fR authentication. The user's UNIX user-id and group-ids are +passed in the clear on the network, unauthenticated by the \fBNFS\fR server. +This is the simplest security method and requires no additional administration. +It is the default used by Solaris \fBNFS\fR Version 2 clients and Solaris +\fBNFS\fR servers. +.sp +According to the ONC RPC specification (RFC 5531), \fBAUTH_SYS\fR +authentication supports up to 16 groups for a user only. To workaround this +limitation, in the case where the \fBNFS\fR client supplied 16 groups in +\fBAUTH_SYS\fR and \fBNGROUPS_MAX\fR is more than 16, the \fBNFS\fR server +will lookup the user's groups on the server instead of relying on the list of +groups provided by the \fBNFS\fR client via \fBAUTH_SYS\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBdh\fR\fR +.ad +.RS 9n +Use a Diffie-Hellman public key system (\fBAUTH_DES\fR, which is referred to as +\fBAUTH_DH\fR in the forthcoming Internet \fBRFC).\fR +.RE + +.sp +.ne 2 +.na +\fB\fBkrb5\fR\fR +.ad +.RS 9n +Use Kerberos V5 protocol to authenticate users before granting access to the +shared filesystem. +.RE + +.sp +.ne 2 +.na +\fB\fBkrb5i\fR\fR +.ad +.RS 9n +Use Kerberos V5 authentication with integrity checking (checksums) to verify +that the data has not been tampered with. +.RE + +.sp +.ne 2 +.na +\fB\fBkrb5p\fR\fR +.ad +.RS 9n +User Kerberos V5 authentication, integrity checksums, and privacy protection +(encryption) on the shared filesystem. This provides the most secure filesystem +sharing, as all traffic is encrypted. It should be noted that performance might +suffer on some systems when using \fBkrb5p\fR, depending on the computational +intensity of the encryption algorithm and the amount of data being transferred. +.RE + +.sp +.ne 2 +.na +\fB\fBnone\fR\fR +.ad +.RS 9n +Use null authentication (\fBAUTH_NONE\fR). \fBNFS\fR clients using +\fBAUTH_NONE\fR have no identity and are mapped to the anonymous user +\fBnobody\fR by \fBNFS\fR servers. A client using a security mode other than +the one with which a Solaris \fBNFS\fR server shares the file system has its +security mode mapped to \fBAUTH_NONE.\fR In this case, if the file system is +shared with \fBsec=none,\fR users from the client are mapped to the +anonymous user. The \fBNFS\fR security mode \fBnone\fR is supported by +\fBshare_nfs\fR(8), but not by \fBmount_nfs\fR(8) or \fBautomount\fR(8). +.RE + +.SH FILES +.ne 2 +.na +\fB\fB/etc/nfssec.conf\fR\fR +.ad +.RS 20n +\fBNFS\fR security service configuration file +.RE + +.SH SEE ALSO +.LP +.BR rpc_clnt_auth (3NSL), +.BR secure_rpc (3NSL), +.BR nfssec.conf (5), +.BR attributes (7), +.BR kerberos (7), +.BR automount (8), +.BR kclient (8), +.BR mount_nfs (8), +.BR share_nfs (8) +.SH NOTES +.LP +\fB/etc/nfssec.conf\fR lists the \fBNFS\fR security services. Do not edit this +file. It is not intended to be user-configurable. See \fBkclient\fR(8). diff --git a/usr/src/man/man7/overlay.7 b/usr/src/man/man7/overlay.7 new file mode 100644 index 0000000000..708281aeda --- /dev/null +++ b/usr/src/man/man7/overlay.7 @@ -0,0 +1,521 @@ +.\" +.\" 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 7 +.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 8 . +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 8 +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 8 +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 4P . +.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 version 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 5 . +.Ed +.El +.El +.Ss General Properties +Each overlay 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 +pseudo-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 vxlan 4P , +.Xr overlay_files 5 , +.Xr dladm 8 diff --git a/usr/src/man/man7/pam_allow.7 b/usr/src/man/man7/pam_allow.7 new file mode 100644 index 0000000000..bb4ca27ae0 --- /dev/null +++ b/usr/src/man/man7/pam_allow.7 @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_ALLOW 7 "Aug 25, 2005" +.SH NAME +pam_allow \- PAM authentication, account, session and password management PAM +module to allow operations +.SH SYNOPSIS +.LP +.nf +\fBpam_allow.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_allow\fR module implements all the PAM service module functions and +returns \fBPAM_SUCCESS\fR for all calls. Opposite functionality is available in +the \fBpam_deny\fR(7) module. +.sp +.LP +Proper Solaris authentication operation requires \fBpam_unix_cred\fR(7) be +stacked above \fBpam_allow\fR. +.sp +.LP +The following options are interpreted: +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 9n +Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_AUTH | +LOG_DEBUG\fR level. +.RE + +.SH ERRORS +.sp +.LP +\fBPAM_SUCCESS\fR is always returned. +.SH EXAMPLES +.LP +\fBExample 1 \fRAllowing \fBssh none\fR +.sp +.LP +The following example is a \fBpam.conf\fR fragment that illustrates a sample +for allowing \fBssh none\fR authentication: + +.sp +.in +2 +.nf +sshd-none auth required pam_unix_cred.so.1 +sshd-none auth sufficient pam_allow.so.1 +sshd-none account sufficient pam_allow.so.1 +sshd-none session sufficient pam_allow.so.1 +sshd-none password sufficient pam_allow.so.1 +.fi +.in -2 + +.LP +\fBExample 2 \fRAllowing Kiosk Automatic Login Service +.sp +.LP +The following is example is a \fBpam.conf\fR fragment that illustrates a sample +for allowing \fBgdm\fR kiosk auto login: + +.sp +.in +2 +.nf +gdm-autologin auth required pam_unix_cred.so.1 +gdm-autologin auth sufficient pam_allow.so.1 +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Stable +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_sm (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_deny (7), +.BR pam_unix_cred (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +This module is intended to be used to either allow access to specific services +names, or to all service names not specified (by specifying it as the default +service stack). diff --git a/usr/src/man/man7/pam_authtok_check.7 b/usr/src/man/man7/pam_authtok_check.7 new file mode 100644 index 0000000000..65dd922781 --- /dev/null +++ b/usr/src/man/man7/pam_authtok_check.7 @@ -0,0 +1,202 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_AUTHTOK_CHECK 7 "Mar 1, 2005" +.SH NAME +pam_authtok_check \- authentication and password management module +.SH SYNOPSIS +.LP +.nf +\fBpam_authtok_check.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +\fBpam_authtok_check\fR provides functionality to the Password Management +stack. The implementation of \fBpam_sm_chauthtok()\fR performs a number of +checks on the construction of the newly entered password. +\fBpam_sm_chauthtok()\fR is invoked twice by the PAM framework, once with flags +set to \fBPAM_PRELIM_CHECK\fR, and once with flags set to +\fBPAM_UPDATE_AUTHTOK\fR. This module only performs its checks during the first +invocation. This module expects the current authentication token in the +\fBPAM_OLDAUTHTOK\fR item, the new (to be checked) password in the +\fBPAM_AUTHTOK\fR item, and the login name in the \fBPAM_USER\fR item. The +checks performed by this module are: +.sp +.ne 2 +.na +\fBlength\fR +.ad +.RS 20n +The password length should not be less that the minimum specified in +\fB/etc/default/passwd\fR. +.RE + +.sp +.ne 2 +.na +\fBcircular shift\fR +.ad +.RS 20n +The password should not be a circular shift of the login name. This check may +be disabled in \fB/etc/default/passwd\fR. +.RE + +.sp +.ne 2 +.na +\fBcomplexity\fR +.ad +.RS 20n +The password should contain at least the minimum number of characters described +by the parameters \fBMINALPHA\fR, \fBMINNONALPHA\fR, \fBMINDIGIT\fR, and +\fBMINSPECIAL\fR. Note that \fBMINNONALPHA\fR describes the same character +classes as \fBMINDIGIT\fR and \fBMINSPECIAL\fR combined; therefore the user +cannot specify both \fBMINNONALPHA\fR and \fBMINSPECIAL\fR (or \fBMINDIGIT\fR). +The user must choose which of the two options to use. Furthermore, the +\fBWHITESPACE\fR parameter determines whether whitespace characters are +allowed. If unspecified \fBMINALPHA\fR is 2, \fBMINNONALPHA\fR is 1 and +\fBWHITESPACE\fR is yes +.RE + +.sp +.ne 2 +.na +\fBvariation\fR +.ad +.RS 20n +The old and new passwords must differ by at least the \fBMINDIFF\fR value +specified in \fB/etc/default/passwd\fR. If unspecified, the default is 3. For +accounts in name services which support password history checking, if prior +history is defined, the new password must not match the prior passwords. +.RE + +.sp +.ne 2 +.na +\fBdictionary check\fR +.ad +.RS 20n +The password must not be based on a dictionary word. The list of words to be +used for the site's dictionary can be specified with \fBDICTIONLIST\fR. It +should contain a comma-separated list of filenames, one word per line. The +database that is created from these files is stored in the directory named by +\fBDICTIONDBDIR\fR (defaults to \fB/var/passwd\fR). See \fBmkpwdict\fR(8) for +information on pre-generating the database. If neither \fBDICTIONLIST\fR nor +\fBDICTIONDBDIR\fR is specified, no dictionary check is made. +.RE + +.sp +.ne 2 +.na +\fBupper/lower case\fR +.ad +.RS 20n +The password must contain at least the minimum of upper- and lower-case letters +specified by the \fBMINUPPER\fR and \fBMINLOWER\fR values in +\fB/etc/default/passwd\fR. If unspecified, the defaults are 0. +.RE + +.sp +.ne 2 +.na +\fBmaximum repeats\fR +.ad +.RS 20n +The password must not contain more consecutively repeating characters than +specified by the \fBMAXREPEATS\fR value in \fB/etc/default/passwd\fR. If +unspecified, no repeat character check is made. +.RE + +.sp +.LP +The following option may be passed to the module: +.sp +.ne 2 +.na +\fBforce_check\fR +.ad +.RS 15n +If the \fBPAM_NO_AUTHTOK_CHECK\fR flag set, \fBforce_check\fR ignores this +flag. The \fBPAM_NO_AUTHTOK_CHECK\fR flag can be set to bypass password checks +(see \fBpam_chauthtok\fR(3PAM)). +.RE + +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 15n +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.SH RETURN VALUES +.sp +.LP +If the password in \fBPAM_AUTHTOK\fR passes all tests, \fBPAM_SUCCESS\fR is +returned. If any of the tests fail, \fBPAM_AUTHTOK_ERR\fR is returned. +.SH FILES +.sp +.ne 2 +.na +\fB/etc/default/passwd\fR +.ad +.RS 23n +See \fBpasswd\fR(1) for a description of the contents. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_chauthtok (3PAM), +.BR pam.conf (5), +.BR passwd (5), +.BR shadow (5), +.BR attributes (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7), +.BR mkpwdict (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). diff --git a/usr/src/man/man7/pam_authtok_get.7 b/usr/src/man/man7/pam_authtok_get.7 new file mode 100644 index 0000000000..4c82c0e9fa --- /dev/null +++ b/usr/src/man/man7/pam_authtok_get.7 @@ -0,0 +1,143 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_AUTHTOK_GET 7 "April 9, 2016" +.SH NAME +pam_authtok_get \- authentication and password management module +.SH SYNOPSIS +.LP +.nf +\fBpam_authtok_get.so.1\fR +.fi + +.SH DESCRIPTION +.LP +The \fBpam_authtok_get\fR service module provides password prompting +functionality to the PAM stack. It implements \fBpam_sm_authenticate()\fR and +\fBpam_sm_chauthtok()\fR, providing functionality to both the Authentication +Stack and the Password Management Stack. +.SS "Authentication Service" +.LP +The implementation of \fBpam_sm_authenticate\fR(3PAM) prompts the user name if +not set and then tries to get the authentication token from the pam handle. If +the token is not set, it then prompts the user for a password and stores it in +the \fBPAM\fR item \fBPAM_AUTHTOK\fR. This module is meant to be the first +module on an authentication stack where users are to authenticate using a +keyboard. +.SS "Password Management Service" +.LP +Due to the nature of the PAM Password Management stack traversal mechanism, the +\fBpam_sm_chauthtok\fR(3PAM) function is called twice. Once with the +\fBPAM_PRELIM_CHECK\fR flag, and one with the \fBPAM_UPDATE_AUTHTOK\fR flag. +.sp +.LP +In the first (\fBPRELIM\fR) invocation, the implementation of +\fBpam_sm_chauthtok\fR(3PAM) moves the contents of the \fBPAM_AUTHTOK\fR +(current authentication token) to \fBPAM_OLDAUTHTOK\fR, and subsequently +prompts the user for a new password. This new password is stored in +\fBPAM_AUTHTOK\fR. +.sp +.LP +If a previous module has set \fBPAM_OLDAUTHTOK\fR prior to the invocation of +pam_authtok_get, this module turns into a \fBNO-OP\fR and immediately returns +\fBPAM_SUCCESS\fR. +.sp +.LP +In the second (\fBUPDATE\fR) invocation, the user is prompted to Re-enter his +password. The pam_sm_chauthtok implementation verifies this reentered password +with the password stored in \fBPAM_AUTHTOK\fR. If the passwords match, the +module returns \fBPAM_SUCCESS\fR. +.sp +.LP +The following option can be passed to the module: +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 9n +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.SH ERRORS +.LP +The authentication service returns the following error codes: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +Fails to retrieve username, username is \fBNULL\fR or empty +.RE + +.sp +.LP +The password management service returns the following error codes: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 19n +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.RS 19n +Authentication token manipulation error +.RE + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C), +\fBlibpam\fR(3LIB), \fBpam.conf\fR(5), \fBattributes\fR(7), +\fBpam_authtok_check\fR(7), pam_authtok_get(7), \fBpam_authtok_store\fR(7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7) +.SH NOTES +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). diff --git a/usr/src/man/man7/pam_authtok_store.7 b/usr/src/man/man7/pam_authtok_store.7 new file mode 100644 index 0000000000..d20ca83d44 --- /dev/null +++ b/usr/src/man/man7/pam_authtok_store.7 @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_AUTHTOK_STORE 7 "Jan 26, 2004" +.SH NAME +pam_authtok_store \- password management module +.SH SYNOPSIS +.LP +.nf +\fBpam_authtok_store.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +\fBpam_authtok_store\fR provides functionality to the PAM password management +stack. It provides one function: \fBpam_sm_chauthtok()\fR. +.sp +.LP +When invoked with flags set to \fBPAM_UPDATE_AUTHTOK\fR, this module updates +the authentication token for the user specified by \fBPAM_USER\fR. +.sp +.LP +The authentication token \fBPAM_OLDAUTHTOK\fR can be used to authenticate the +user against repositories that need updating (\fBNIS\fR, \fBLDAP\fR). After +successful updates, the new authentication token stored in \fBPAM_AUTHTOK\fR is +the user's valid password. +.sp +.LP +This module honors the \fBPAM_REPOSITORY\fR item, which, if set, specifies +which repository is to be updated. If \fBPAM_REPOSITORY\fR is unset, it follows +the \fBnsswitch.conf\fR(5). +.sp +.LP +The following option can be passed to the module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 17n +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.na +\fB\fBserver_policy\fR\fR +.ad +.RS 17n +If the account authority for the user, as specified by \fBPAM_USER\fR, is a +server, do not encrypt the authentication token before updating. +.RE + +.SH ERRORS +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +Fails to get username, service name, old password or new password, user name +null or empty, or password null. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_chauthtok (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). +.sp +.LP +If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does +not recognize the type, the service module does not process any information, +and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is +not set, a service module performs its default action. diff --git a/usr/src/man/man7/pam_deny.7 b/usr/src/man/man7/pam_deny.7 new file mode 100644 index 0000000000..3910787eb0 --- /dev/null +++ b/usr/src/man/man7/pam_deny.7 @@ -0,0 +1,157 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_DENY 7 "Jun 16, 2005" +.SH NAME +pam_deny \- PAM authentication, account, session and password management PAM +module to deny operations +.SH SYNOPSIS +.LP +.nf +\fBpam_deny.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_deny\fR module implements all the PAM service module functions and +returns the module type default failure return code for all calls. +.sp +.LP +The following options are interpreted: +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 9n +\fBsyslog\fR(3C) debugging information at the \fBLOG_AUTH\fR|\fBLOG_DEBUG\fR +levels +.RE + +.SH ERRORS +.sp +.LP +The following error codes are returned: +.sp +.ne 2 +.na +\fB\fBPAM_ACCT_EXPIRED\fR\fR +.ad +.RS 20n +If \fBpam_sm_acct_mgmt\fR is called. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +If \fBpam_sm_authenticate\fR is called. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTHOK_ERR\fR\fR +.ad +.RS 20n +If \fBpam_sm_chauthtok\fR is called. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_CRED_ERR\fR\fR +.ad +.RS 20n +If \fBpam_sm_setcred\fR is called. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SESSION_ERR\fR\fR +.ad +.RS 20n +If \fBpam_sm_open_session\fR or \fBpam_sm_close_session\fR is called. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRDisallowing ssh none authentication +.sp +.in +2 +.nf + sshd-none auth requisite pam_deny.so.1 + sshd-none account requisite pam_deny.so.1 + sshd-none session requisite pam_deny.so.1 + sshd-none password requisite pam_deny.so.1 +.fi +.in -2 +.sp + +.LP +\fBExample 2 \fRDisallowing any service not explicitly defined +.sp +.in +2 +.nf + other auth requisite pam_deny.so.1 + other account requisite pam_deny.so.1 + other session requisite pam_deny.so.1 + other password requisite pam_deny.so.1 +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR nsswitch.conf (5), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7), +.BR privileges (7), +.BR su (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +The \fBpam_deny\fR module is intended to deny access to a specified service. +The \fBother\fR service name may be used to deny access to services not +explicitly specified. diff --git a/usr/src/man/man7/pam_dhkeys.7 b/usr/src/man/man7/pam_dhkeys.7 new file mode 100644 index 0000000000..2f403c9d12 --- /dev/null +++ b/usr/src/man/man7/pam_dhkeys.7 @@ -0,0 +1,217 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_DHKEYS 7 "Feb 25, 2017" +.SH NAME +pam_dhkeys \- authentication Diffie-Hellman keys management module +.SH SYNOPSIS +.LP +.nf +\fBpam_dhkeys.so.1\fR +.fi + +.SH DESCRIPTION +.LP +The \fBpam_dhkeys.so.1\fR service module provides functionality to two +\fBPAM\fR services: Secure \fBRPC\fR authentication and Secure \fBRPC\fR +authentication token management. +.sp +.LP +Secure RPC authentication differs from regular unix authentication because +some \fBONC RPC\fRs use Secure RPC as the underlying security mechanism. +.sp +.LP +The following options may be passed to the module: +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 10n +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.na +\fBnowarn\fR +.ad +.RS 10n +Turn off warning messages +.RE + +.SS "Authentication Services" +.LP +If the user has Diffie-Hellman keys, \fBpam_sm_authenticate()\fR establishes +secret keys for the user specified by the \fBPAM_USER\fR (equivalent to running +\fBkeylogin\fR(1)), using the authentication token found in the +\fBPAM_AUTHTOK\fR item. If \fBpam_sm_setcred()\fR is called with +\fBPAM_ESTABLISH_CRED\fR and the user's secure \fBRPC\fR credentials need to be +established, these credentials are set. This is equivalent to running +\fBkeylogin\fR(1). +.sp +.LP +If the credentials could not be set and \fBPAM_SILENT\fR is not specified, a +diagnostic message is displayed. If \fBpam_setcred()\fR is called with +\fBPAM_DELETE_CRED\fR, the user's secure \fBRPC\fR credentials are unset. This +is equivalent to running \fBkeylogout\fR(1). +.sp +.LP +\fBPAM_REINITIALIZE_CRED\fR and \fBPAM_REFRESH_CRED\fR are not supported and +return \fBPAM_IGNORE\fR. +.SS "Authentication Token Management" +.LP +The \fBpam_sm_chauthtok()\fR implementation checks whether the old login +password decrypts the users secret keys. If it doesn't this module prompts the +user for an old Secure \fBRPC\fR password and stores it in a pam data item +called \fBSUNW_OLDRPCPASS\fR. This data item can be used by the store module to +effectively update the users secret keys. +.SH ERRORS +.LP +The authentication service returns the following error codes: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +Credentials set successfully. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +Credentials not needed to access the password repository. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +\fBPAM_USER\fR is not set, or the user is unknown. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +No secret keys were set. \fBPAM_AUTHTOK\fR is not set, no credentials are +present or there is a wrong password. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +Module ran out of memory. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +Credentials could not be stored, or netname could not be created. +.RE + +.sp +.LP +The authentication token management returns the following error codes: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS \fR\fR +.ad +.RS 20n +Old \fBrpc\fR password is set in \fBSUNW_OLDRPCPASS\fR +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +User in \fBPAM_USER\fR is unknown. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.RS 20n +User did not provide a password that decrypts the secret keys. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +Module ran out of memory. +.RE + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.LP +.BR keylogin (1), +.BR keylogout (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_chauthtok (3PAM), +.BR pam_get_data (3PAM), +.BR pam_get_item (3PAM), +.BR pam_set_data (3PAM), +.BR pam_setcred (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7) +.SH NOTES +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). diff --git a/usr/src/man/man7/pam_dial_auth.7 b/usr/src/man/man7/pam_dial_auth.7 new file mode 100644 index 0000000000..ad7218f983 --- /dev/null +++ b/usr/src/man/man7/pam_dial_auth.7 @@ -0,0 +1,133 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_DIAL_AUTH 7 "Sep 9, 2004" +.SH NAME +pam_dial_auth \- authentication management PAM module for dialups +.SH SYNOPSIS +.LP +.nf +\fBpam_dial_auth.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_dial_auth\fR module implements \fBpam_sm_authenticate\fR(3PAM) which +authenticates the user according to the \fBdialups\fR(5) and \fBd_passwd\fR(5) +files configuration. +.sp +.LP +Authentication service modules must implement both \fBpam_sm_authenticate()\fR +and \fBpam_sm_setcred()\fR. \fBpam_sm_setcred()\fR in this module always +returns \fBPAM_IGNORE\fR. +.sp +.LP +The value of the \fBPAM_TTY\fR item is checked against entries in +\fBdialups\fR(5). If there is a match, the user's shell is compared against +entries in \fBd_passwd\fR(5). If there is a matching entry, the user is +prompted for a password which is validated against the entry found. +.sp +.LP +The following option may be passed in to this service module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 9n +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.SH ERRORS +.sp +.LP +If \fBdialups\fR(5) is not present, \fBPAM_IGNORE\fR is returned. Upon +successful completion of \fBpam_sm_authenticate()\fR, \fBPAM_SUCCESS\fR is +returned. The following error codes are returned upon error: +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +Authentication failure. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 20n +Error in the calling service, \fBPAM_TTY\fR is not set. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +System error (\fBd_passwd\fR(5) is not present). +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +No account is present for \fIuser\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR d_passwd (5), +.BR dialups (5), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). diff --git a/usr/src/man/man7/pam_krb5.7 b/usr/src/man/man7/pam_krb5.7 new file mode 100644 index 0000000000..b749852758 --- /dev/null +++ b/usr/src/man/man7/pam_krb5.7 @@ -0,0 +1,714 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_KRB5 7 "Apr 8, 2008" +.SH NAME +pam_krb5 \- authentication, account, session, and password management PAM +modules for Kerberos V5 +.SH SYNOPSIS +.LP +.nf +/usr/lib/security/pam_krb5.so.1 +.fi + +.SH DESCRIPTION +.sp +.LP +The Kerberos V5 service module for \fBPAM\fR provides functionality for all +four \fBPAM\fR modules: authentication, account management, session management, +and password management. The service module is a shared object that can be +dynamically loaded to provide the necessary functionality upon demand. Its path +is specified in the \fBPAM\fR configuration file. +.SS "Kerberos Authentication Module" +.sp +.LP +The Kerberos V5 authentication component provides functions to verify the +identity of a user, \fBpam_sm_authenticate()\fR, and to manage the Kerberos +credentials cache, \fBpam_sm_setcred()\fR. +.sp +.LP +\fBpam_sm_authenticate()\fR authenticates a user principal through the Kerberos +authentication service. If the authentication request is successful, the +authentication service sends a ticket-granting ticket (\fBTGT\fR) back to the +service module, which then verifies that the \fBTGT\fR came from a valid Key +Distribution Center (\fBKDC\fR) by attempting to get a service ticket for the +local host service. For this to succeed, the local host's keytab file +(\fB/etc/krb5/krb5.keytab\fR) must contain the entry for the local host +service. For example, in the file \fBhost/\fIhostname.com\fR@\fIREALM\fR\fR, +\fIhostname.com\fR is the fully qualified local hostname and \fIREALM\fR is the +default realm of the local host as defined in \fB/etc/krb5/krb5.conf\fR. If the +host entry is not found in the keytab file, the authentication fails. +Administrators may optionally disable this "strict" verification by setting +"\fBverify_ap_req_nofail = false\fR" in \fB/etc/krb5/krb5.conf\fR. See +\fBkrb5.conf\fR(5) for more details on this option. This allows \fBTGT\fR +verification to succeed in the absence of a keytab host principal entry. +.sp +.LP +\fBpam_sm_authenticate\fR(3PAM) may be passed the following flag: +.sp +.ne 2 +.na +\fB\fBPAM_DISALLOW_NULL_AUTHTOK\fR\fR +.ad +.sp .6 +.RS 4n +This flag is ignored. The Kerberos authentication mechanism will not allow an +empty password string by default. +.RE + +.sp +.LP +\fBpam_sm_setcred()\fR creates and modifies the user's credential cache. This +function initializes the user's credential cache, if it does not already exist, +and stores the initial credentials for later use by Kerberized network +applications. The following flags may be set in the flags field. They are best +described by their effect on the user's credential cache. +.sp +.ne 2 +.na +\fB\fBPAM_ESTABLISH_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Stores the initial credentials in the user's credential cache so that the user +may access Kerberos network services. If a successful authentication pass was +made, the new credentials are stored in the credential cache, overwriting any +existing credentials that were previously stored. If an unsuccessful +authentication pass was made, PAM_CRED_UNAVAIL is returned. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_DELETE_CRED\fR\fR +.ad +.sp .6 +.RS 4n +This flag has no effect on the credential cache and always returns +\fBPAM_SUCCESS\fR. The credential cache is not deleted because there is no +accurate method to determine if the credentials are needed by another process. +The credential cache may be deleted with the \fBkdestroy\fR(1) command. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_REINITIALIZE_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Deletes the user's existing credential cache, if it exists, and creates a new +credential cache. The new credentials are stored in the new cache and the +user's ticket lifetime and renewable life time values are reset. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_REFRESH_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Does not require a previous authentication pass, but if a successful one is +made, the new credentials are stored in the credential cache. If a previous +authentication pass was not made or was unsuccessful, an attempt to renew the +existing credentials is made. Note that this function fails if the user's +renewable ticket lifetime is expired. +.RE + +.sp +.LP +The following options can be passed to the Kerberos V5 authentication module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +Turns off warning messages. +.RE + +.SS "Kerberos V5 Account Management Module" +.sp +.LP +The Kerberos account management component provides a function to perform +account management, \fBpam_sm_acct_mgmt()\fR. This function checks to see if +the \fBpam_krb5\fR authentication module has noted that the user's password has +not expired. The following options may be passed in to the Kerberos V5 account +management module: +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 10n +Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.na +\fBnowarn\fR +.ad +.RS 10n +Turns off warning messages. Also, does not query KDC for impending password +expiration information used to warn the user. +.RE + +.SS "Kerberos V5 Session Management Module" +.sp +.LP +The Kerberos V5 session management component provides functions to initiate +\fBpam_sm_open_session()\fR and terminate \fBpam_sm_close_session()\fR Kerberos +sessions. For Kerberos V5, both \fBpam_sm_open_session\fR and +\fBpam_sm_close_session()\fR are null functions, returning \fBPAM_IGNORE\fR. +.SS "Kerberos V5 Password Management Module" +.sp +.LP +The Kerberos V5 password management component provides a function to change +passwords, \fBpam_sm_chauthtok()\fR, in the Key Distribution Center (\fBKDC\fR) +database. The following flags may be passed to \fBpam_sm_chauthtok\fR(3PAM): +.sp +.ne 2 +.na +\fB\fBPAM_CHANGE_EXPIRED_AUTHTOK\fR\fR +.ad +.sp .6 +.RS 4n +The password service should only update the user's Kerberos password if it is +expired. Otherwise, this function returns \fBPAM_IGNORE\fR. The default +behaviour is to always change the user's Kerberos password. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PRELIM_CHECK\fR\fR +.ad +.sp .6 +.RS 4n +This is a null function that always returns \fBPAM_IGNORE\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_UPDATE_AUTHTOK\fR\fR +.ad +.sp .6 +.RS 4n +This flag is necessary to change the user's Kerberos password. If this flag is +not set, \fBpam_krb5\fR returns \fBPAM_SYSTEM_ERR\fR. +.RE + +.sp +.LP +The following option can be passed to the Kerberos V5 password module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 9n +Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.SH ERRORS +.sp +.LP +The following error codes are returned for \fBpam_sm_authenticate()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +Authentication failure +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +Memory buffer error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +The user is "\fBroot\fR" and the root key exists in the default keytab. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +Successfully obtained Kerberos credentials . +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +System error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +An unknown Kerberos principal was requested. +.RE + +.sp +.LP +The following error codes are returned for \fBpam_sm_setcred()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 18n +Authentication failure. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 18n +Memory buffer error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 18n +The user is "\fBroot\fR" and the root key exists in the default keytab. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +System error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +Successfully modified the Kerberos credential cache. +.RE + +.sp +.LP +The following error codes are returned for \fBpam_sm_acct_mgmt()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 24n +Authentication failure. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 24n +Kerberos service module \fBpam_sm_authenticate()\fR was never called, or the +user is "\fBroot\fR" and the root key exists in the default keytab. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +Obtain new authentication token from the user. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 24n +Error in underlying service module. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +Kerberos principal account is valid. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 24n +System error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +An unknown Kerberos principal was requested. +.RE + +.sp +.LP +The following error code is returned for \fBpam_sm_open_session()\fR and +\fBpam_sm_close_session()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 14n +These two functions are null functions in \fBpam_krb5\fR: +.RE + +.sp +.LP +The following error codes are returned for \fBpam_sm_chauthtok()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 24n +Authentication failure. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 24n +The user has not been authenticated by Kerberos service module +\fBpam_sm_authenticate()\fR, or the user is "\fBroot\fR" and the root key +exists in the default keytab. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +User's Kerberos password has expired. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 24n +Error in module. At least one input parameter is missing. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 24n +System error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +An unknown Kerberos principal was requested. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +Successfully changed the user's Kerberos password. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRAuthenticate Users Through Kerberos as First Choice +.sp +.LP +The following is an excerpt of a sample \fBpam.conf\fR configuration file that +authenticates users through the Kerberos authentication service and +authenticates through the Unix login only if the Kerberos authentication fails. +This arrangement is helpful when a majority of the users are networked by means +of Kerberos and when there are only a few non-Kerberos type user accounts, such +as root. The service illustrated below is for \fBdtlogin\fR. + +.sp +.in +2 +.nf +dtlogin auth requisite pam_smartcard.so.1 +dtlogin auth requisite pam_authtok_get.so.1 +dtlogin auth required pam_dhkeys.so.1 +dtlogin auth required pam_unix_cred.so.1 +dtlogin auth sufficient pam_krb5.so.1 +dtlogin auth required pam_unix_auth.so.1 +.fi +.in -2 + +.sp +.LP +Note that these changes should not be made to the existing \fBkrlogin\fR, +\fBkrsh\fR, and \fBktelnet\fR service entries. Those services require Kerberos +authentication, so using a seemingly sufficient control flag would not provide +the necessary functionality for privacy and integrity. There should be no need +to change those entries. + +.sp +.LP +The following entries check for password expiration when dealing with Kerberos +and Unix password aging policies: + +.sp +.in +2 +.nf +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +other account required pam_krb5.so.1 +.fi +.in -2 + +.sp +.LP +The following entries would change the Kerberos password of the user and +continue to change the Unix login password only if the Kerberos password change +had failed: + +.sp +.in +2 +.nf +other password required pam_dhkeys.so.1 +other password requisite pam_authtok_get.so.1 +other password requisite pam_authtok_check.so.1 +other password sufficient pam_krb5.so.1 +other password required pam_authtok_store.so.1 +.fi +.in -2 + +.sp +.LP +When changing Kerberos based user's password, use \fBkpasswd\fR(1). When +changing a non-Kerberos user's password, it is recommended that the repository +is specified (\fB-r\fR) with the \fBpasswd\fR(1) command. + +.LP +\fBExample 2 \fRAuthenticate Users Through Kerberos Only +.sp +.LP +The following example allows authentication only to users that have +Kerberos-based accounts. + +.sp +.in +2 +.nf +dtlogin auth requisite pam_smartcard.so.1 +dtlogin auth requisite pam_authtok_get.so.1 +dtlogin auth required pam_dhkeys.so.1 +dtlogin auth required pam_unix_cred.so.1 +dtlogin auth binding pam_krb5.so.1 +dtlogin auth required pam_unix_auth.so.1 +.fi +.in -2 + +.sp +.LP +Typically, you would have another service specified in the \fBpam.conf\fR file +that would allow local users, such as database, web server, system +administrator accounts, to log in to the host machine. For example, the service +name "login" could be used for these users. Note that these users should not +belong to any roles. + +.sp +.LP +The rest of the module types look similar to that shown in the previous +example: + +.sp +.in +2 +.nf +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +other account required pam_krb5.so.1 +.fi +.in -2 + +.sp +.LP +With binding specified in the following, it is important that non-Kerberos +users specify the repository in which they reside using the \fB-r\fR option +with the \fBpasswd\fR(1) command. This configuration is also based on the +assumptions that: + +.RS +4 +.TP +.ie t \(bu +.el o +Kerberos users maintain only their Kerberos passwords; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +changing their Unix password is not necessary, given that they are +authenticated only through their Kerberos passwords when logging in. +.RE +.sp +.in +2 +.nf +other password required pam_dhkeys.so.1 +other password requisite pam_authtok_get.so.1 +other password requisite pam_authtok_check.so.1 +other password binding pam_krb5.so.1 +other password required pam_authtok_store.so.1 +.fi +.in -2 + +.LP +\fBExample 3 \fRAuthenticate Through Kerberos Optionally +.sp +.LP +This configuration is helpful when the majority of users are non-Kerberos users +and would like to authenticate through Kerberos if they happened to exist in +the Kerberos database. The effect of this is similar to users voluntarily +executing \fBkinit\fR(1) after they have successfully logged in: + +.sp +.in +2 +.nf +dtlogin auth requisite pam_smartcard.so.1 +dtlogin auth requisite pam_authtok_get.so.1 +dtlogin auth required pam_dhkeys.so.1 +dtlogin auth required pam_unix_cred.so.1 +dtlogin auth required pam_unix_auth.so.1 +dtlogin auth optional pam_krb5.so.1 +.fi +.in -2 + +.sp +.LP +The rest of the configuration is as follows: + +.sp +.in +2 +.nf +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +other account required pam_krb5.so.1 + +other password required pam_dhkeys.so.1 +other password requisite pam_authtok_get.so.1 +other password requisite pam_authtok_check.so.1 +other password required pam_authtok_store.so.1 +other password optional pam_krb5.so.1 +.fi +.in -2 + +.sp +.LP +Non-Kerberos users should specify their respective repositories by using the +\fB-r\fR option when changing their password with the \fBpasswd\fR(1) command. + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) 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 +.BR kdestroy (1), +.BR kinit (1), +.BR kpasswd (1), +.BR passwd (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_sm (3PAM), +.BR pam_sm_acct_mgmt (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR pam_sm_chauthtok (3PAM), +.BR pam_sm_close_session (3PAM), +.BR pam_sm_open_session (3PAM), +.BR pam_sm_setcred (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR kerberos (7), +.BR krb5envvar (7), +.BR ktkt_warnd (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +On successful acquisition of initial credentials (ticket-granting ticket), +\fBktkt_warnd\fR(8) will be notified, to alert the user when the initial +credentials are about to expire. diff --git a/usr/src/man/man7/pam_krb5_migrate.7 b/usr/src/man/man7/pam_krb5_migrate.7 new file mode 100644 index 0000000000..fbdb2be4f8 --- /dev/null +++ b/usr/src/man/man7/pam_krb5_migrate.7 @@ -0,0 +1,200 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_KRB5_MIGRATE 7 "November 22, 2021" +.SH NAME +pam_krb5_migrate \- authentication PAM module for the KerberosV5 auto-migration +of users feature +.SH SYNOPSIS +.nf +\fB/usr/lib/security/pam_krb5_migrate.so.1\fR +.fi + +.SH DESCRIPTION +The KerberosV5 auto-migrate service module for PAM provides functionality for +the PAM authentication component. The service module helps in the automatic +migration of \fBPAM_USER\fR to the client's local Kerberos realm, using +\fBPAM_AUTHTOK\fR (the PAM authentication token associated with \fBPAM_USER\fR) +as the new Kerberos principal's password. +.SS "KerberosV5 Auto-migrate Authentication Module" +The KerberosV5 auto-migrate authentication component provides the +\fBpam_sm_authenticate\fR(3PAM) function to migrate a user who does not have a +corresponding \fBkrb5\fR principal account to the default Kerberos realm of the +client. +.sp +.LP +\fBpam_sm_authenticate\fR(3PAM) uses a host-based client service principal, +present in the local \fBkeytab\fR (\fB/etc/krb5/krb5.keytab\fR) to authenticate +to \fBkadmind\fR(8) (defaults to the \fBhost/nodename.fqdn\fR service +principal), for the principal creation operation. Also, for successful creation +of the \fBkrb5\fR user principal account, the host-based client service +principal being used needs to be assigned the appropriate privilege on the +master KDC's \fBkadm5.acl\fR(5) file. \fBkadmind\fR(8) checks for the +appropriate privilege and validates the user password using PAM by calling +\fBpam_authenticate\fR(3PAM) and \fBpam_acct_mgmt\fR(3PAM) for the +\fBk5migrate\fR service. +.sp +.LP +If migration of the user to the KerberosV5 infrastructure is successful, the +module will inform users about it by means of a \fBPAM_TEXT_INFO\fR message, +unless instructed otherwise by the presence of the \fBquiet\fR option. +.sp +.LP +The authentication component always returns \fBPAM_IGNORE\fR and is meant to be +stacked in \fBpam.conf\fR with a requirement that it be listed below +pam_authtok_get(7) in the authentication stack. Also, if \fBpam_krb5_migrate\fR +is used in the authentication stack of a particular service, it is mandatory +that \fBpam_krb5\fR(7) be listed in the PAM account stack of that service for +proper operation (see EXAMPLES). +.SH OPTIONS +The following options can be passed to the KerberosV5 auto-migrate +authentication module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.sp .6 +.RS 4n +Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBclient_service=\fR\fI<service name>\fR\fR +.ad +.sp .6 +.RS 4n +Name of the service used to authenticate to \fBkadmind\fR(8) defaults to +\fBhost\fR. This means that the module uses \fBhost/\fR\fI<nodename.fqdn>\fR as +its client service principal name, KerberosV5 user principal creation operation +or \fI<service>\fR/\fI<nodename.fqdn>\fR if this option is provided. +.RE + +.sp +.ne 2 +.na +\fB\fBquiet\fR\fR +.ad +.sp .6 +.RS 4n +Do not explain KerberosV5 migration to the user. +.sp +This has the same effect as passing the \fBPAM_SILENT\fR flag to +\fBpam_sm_authenticate\fR(3PAM) and is useful where applications cannot handle +\fBPAM_TEXT_INFO\fR messages. +.sp +If not set, the authentication component will issue a \fBPAM_TEXT_INFO\fR +message after creation of the Kerberos V5 principal, indicating that it has +done so. +.RE + +.sp +.ne 2 +.na +\fB\fBexpire_pw\fR\fR +.ad +.sp .6 +.RS 4n +Causes the creation of KerberosV5 user principals with password expiration set +to \fBnow\fR (current time). +.RE + +.SH EXAMPLES +\fBExample 1 \fRSample Entries from \fBpam.conf\fR +.sp +.LP +The following entries from \fBpam.conf\fR(5) demonstrate the use of the +\fBpam_krb5_migrate.so.1\fR module: + +.sp +.in +2 +.nf +login auth requisite pam_authtok_get.so.1 +login auth required pam_dhkeys.so.1 +login auth required pam_unix_cred.so.1 +login auth sufficient pam_krb5.so.1 +login auth requisite pam_unix_auth.so.1 +login auth optional pam_krb5_migrate.so.1 expire_pw +login auth required pam_dial_auth.so.1 + +other account requisite pam_roles.so.1 +other account required pam_krb5.so.1 +other account required pam_unix_account.so.1 +.fi +.in -2 + +.sp +.LP +The \fBpam_krb5_migrate\fR module can generally be present on the +authentication stack of any service where the application calls +\fBpam_sm_authenticate\fR(3PAM) and an authentication token (in the preceding +example, the authentication token would be the user's Unix password) is +available for use as a Kerberos V5 password. + +.LP +\fBExample 2 \fRSample Entries from \fBkadm5.acl\fR +.sp +.LP +The following entries from \fBkadm5.acl\fR(5) permit or deny privileges to the +host client service principal: + +.sp +.in +2 +.nf +host/*@EXAMPLE.COM U root +host/*@EXAMPLE.COM ui * +.fi +.in -2 + +.sp +.LP +The preceding entries permit the \fBpam_krb5_migrate\fR \fBadd\fR privilege to +the host client service principal of any machine in the \fBEXAMPLE.COM\fR +KerberosV5 realm, but denies the \fBadd\fR privilege to all host service +principals for addition of the root user account. + +.LP +\fBExample 3 \fRSample Entries in \fBpam.conf\fR of the Master KDC +.sp +.LP +The entries below enable \fBkadmind\fR(8) on the master KDC to use the +\fBk5migrate\fR PAM service in order to validate Unix user passwords for +accounts that require migration to the Kerberos realm. + +.sp +.in +2 +.nf +k5migrate auth required pam_unix_auth.so.1 +k5migrate account required pam_unix_account.so.1 +.fi +.in -2 + +.SH ATTRIBUTES +See \fBattributes\fR(7) for a description of the following attribute: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +.TE + +.SH SEE ALSO +.BR syslog (3C), +.BR pam_acct_mgmt (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR kadm5.acl (5), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_get (7), +.BR pam_krb5 (7), +.BR kadmind (8) diff --git a/usr/src/man/man7/pam_ldap.7 b/usr/src/man/man7/pam_ldap.7 new file mode 100644 index 0000000000..66173284a8 --- /dev/null +++ b/usr/src/man/man7/pam_ldap.7 @@ -0,0 +1,425 @@ +'\" te +.\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_LDAP 7 "Dec 21, 2005" +.SH NAME +pam_ldap \- authentication and account management PAM module for LDAP +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/pam_ldap.so.1\fR +.fi + +.SH DESCRIPTION +.LP +The \fBpam_ldap\fR module implements \fBpam_sm_authenticate\fR(3PAM) and +\fBpam_sm_acct_mgmt\fR(3PAM), the functions that provide functionality for the +PAM authentication and account management stacks. The \fBpam_ldap\fR module +ties the authentication and account management functionality to the +functionality of the supporting LDAP server. For authentication, \fBpam_ldap\fR +can authenticate the user directly to any LDAP directory server by using any +supported authentication mechanism, such as \fBDIGEST-MD5\fR. However, the +account management component of \fBpam_ldap\fR will work only with the Sun Java +System Directory Server. The server's user account management must be properly +configured before it can be used by \fBpam_ldap\fR. Refer to the \fISun Java +System Directory Server Administration Guide\fR for information on how to +configure user account management, including password and account lockout +policy. +.sp +.LP +\fBpam_ldap\fR must be used in conjunction with the modules that support the +UNIX authentication, password, and account management, which are +\fBpam_authtok_get\fR(7), \fBpam_passwd_auth\fR(7), \fBpam_unix_account\fR(7), +and \fBpam_unix_auth\fR(7). \fBpam_ldap\fR is designed to be stacked directly +below these modules. If other modules are designed to be stacked in this +manner, the modules can be stacked below the \fBpam_ldap\fR module. The +Examples section shows how the UNIX modules are stacked with \fBpam_ldap\fR. +When stacked together, the UNIX modules are used to control local accounts, +such as \fBroot\fR. \fBpam_ldap\fR is used to control network accounts, that +is, LDAP users. For the stacks to work, \fBpam_unix_auth\fR, +\fBpam_unix_account\fR, and \fBpam_passwd_auth\fR must be configured with the +\fBbinding\fR control flag and the \fBserver_policy\fR option. This +configuration allows local account override of a network account. +.SS "LDAP Authentication Module" +.LP +The LDAP authentication module verifies the identity of a user. The +\fBpam_sm_authenticate\fR(3PAM) function uses the password entered by the user +to attempt to authenticate to the LDAP server. If successful, the user is +authenticated. See NOTES for information on password prompting. +.sp +.LP +The authentication method used is either defined in the client profile , or the +authentication method is configured by using the \fBldapclient\fR(8) command. +To determine the authentication method to use, this module first attempts to +use the authentication method that is defined, for service \fBpam_ldap\fR, for +example, \fBserviceAuthenticationMethod:pam_ldap:sasl/DIGEST-MD5\fR. If no +authentication method is defined, \fBpam_ldap\fR uses the default +authentication method. If neither are set, the authentication fails. This +module skips the configured authentication method if the authentication method +is set to \fBnone\fR. +.sp +.LP +The following options can be passed to the LDAP service module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +Turn off warning messages. +.RE + +.sp +.LP +These options are case sensitive and must be used exactly as presented here. +.SS "LDAP Account Management Module" +.LP +The LDAP account management module validates the user's account. The +\fBpam_sm_acct_mgmt\fR(3PAM) function authenticates to the LDAP server to +verify that the user's password has not expired, or that the user's account has +not been locked. In the event that there is no user authentication token +(\fBPAM_AUTHTOK\fR) available, the \fBpam_sm_acct_mgmt\fR(3PAM) function +attempts to retrieve the user's account status without authenticating to the +LDAP server as the user logging in. This procedure will succeed only if the +LDAP server is Sun Java System Directory server 5.2 patch 4 or newer. The +following options can be passed to the LDAP service module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +Turn off warning messages. +.RE + +.sp +.LP +These options are case sensitive, and the options must be used exactly as +presented here. +.SS "LDAP Password Management Module" +.LP +LDAP password management is no longer supported by \fBpam_ldap\fR. Use +\fBpam_authtok_store\fR(7) instead of \fBpam_ldap\fR for password change. +\fBpam_authtok_store\fR(7) handles both the local and LDAP accounts and updates +the passwords in all the repositories configured by \fBnsswitch.conf\fR(5). +.SH ERRORS +.LP +The authentication service returns the following error codes: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +The authentication was successful. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_MAXTRIES\fR\fR +.ad +.RS 20n +The maximum number of authentication attempts was exceeded. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +The authentication failed. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +No account is present for the user. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +A memory buffer error occurred. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +A system error occurred. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +The user's account was inactivated. +.RE + +.sp +.LP +The account management service returns the following error codes: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +The user was allowed access to the account. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +A new authentication token is required. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_ACCT_EXPIRED\fR\fR +.ad +.RS 24n +The user account has expired. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 24n +The user was denied access to the account at this time. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +No account is present for the user. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERROR\fR\fR +.ad +.RS 24n +A memory buffer error occurred. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 24n +A system error occurred. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBpam_ldap\fR With Authentication\fB\fR +.sp +.LP +The following is a configuration for the login service when using +\fBpam_ldap\fR. The service name \fBlogin\fR can be substituted for any other +authentication service such as \fBdtlogin\fR or \fBsu\fR. Lines that begin with +the # symbol are comments and are ignored. + +.sp +.in +2 +.nf +# Authentication management for login service is stacked. +# If pam_unix_auth succeeds, pam_ldap is not invoked. +# The control flag "binding" provides a local overriding +# remote (LDAP) control. The "server_policy" option is used +# to tell pam_unix_auth.so.1 to ignore the LDAP users. + +login auth requisite pam_authtok_get.so.1 +login auth required pam_dhkeys.so.1 +login auth required pam_unix_cred.so.1 +login auth binding pam_unix_auth.so.1 server_policy +login auth required pam_ldap.so.1 +.fi +.in -2 + +.LP +\fBExample 2 \fRUsing \fBpam_ldap\fR With Account Management +.sp +.LP +The following is a configuration for account management when using +\fBpam_ldap\fR. Lines that begin with the # symbol are comments and are +ignored. + +.sp +.in +2 +.nf +# Account management for all services is stacked +# If pam_unix_account succeeds, pam_ldap is not invoked. +# The control flag "binding" provides a local overriding +# remote (LDAP) control. The "server_policy" option is used +# to tell pam_unix_account.so.1 to ignore the LDAP users. + +other account requisite pam_roles.so.1 +other account binding pam_unix_account.so.1 server_policy +other account required pam_ldap.so.1 +.fi +.in -2 + +.LP +\fBExample 3 \fRUsing \fBpam_authtok_store\fR With Password Management For Both +Local and LDAP Accounts +.sp +.LP +The following is a configuration for password management when using +\fBpam_authtok_store\fR. Lines that begin with the # symbol are comments and +are ignored. + +.sp +.in +2 +.nf +# Password management (authentication) +# The control flag "binding" provides a local overriding +# remote (LDAP) control. The server_policy option is used +# to tell pam_passwd_auth.so.1 to ignore the LDAP users. + +passwd auth binding pam_passwd_auth.so.1 server_policy +passwd auth required pam_ldap.so.1 + +# Password management (updates) +# This updates passwords stored both in the local /etc +# files and in the LDAP directory. The "server_policy" +# option is used to tell pam_authtok_store to +# follow the LDAP server's policy when updating +# passwords stored in the LDAP directory + +other password required pam_dhkeys.so.1 +other password requisite pam_authtok_get.so.1 +other password requisite pam_authtok_check.so.1 +other password required pam_authtok_store.so.1 server_policy +.fi +.in -2 + +.SH FILES +.ne 2 +.na +\fB\fB/var/ldap/ldap_client_file\fR\fR +.ad +.br +.na +\fB\fB/var/ldap/ldap_client_cred\fR\fR +.ad +.RS 30n +The LDAP configuration files of the client. Do not manually modify these files, +as these files might not be human readable. Use \fBldapclient\fR(8) to update +these files. +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/pam.conf\fR\fR +.ad +.RS 30n +PAM configuration file. +.RE + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT-Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.LP +.BR ldap (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_sm_acct_mgmt (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR pam_sm_chauthtok (3PAM), +.BR pam_sm_close_session (3PAM), +.BR pam_sm_open_session (3PAM), +.BR pam_sm_setcred (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR idsconfig (8), +.BR ldap_cachemgr (8), +.BR ldapclient (8) +.SH NOTES +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +The previously supported \fBuse_first_pass\fR and \fBtry_first_pass\fR options +are obsolete in this version, are no longer needed, can safely be removed from +\fBpam.conf\fR(5), and are silently ignored. They might be removed in a future +release. Password prompting must be provided for by stacking +\fBpam_authtok_get\fR(7) before \fBpam_ldap\fR in the \fBauth\fR and +\fBpassword\fR module stacks and \fBpam_passwd_auth\fR(7) in the \fBpasswd\fR +service \fBauth\fR stack (as described in the EXAMPLES section). The previously +supported password update function is replaced in this release by the +previously recommended use of \fBpam_authtok_store\fR with the +\fBserver_policy\fR option (as described in the EXAMPLES section). +.sp +.LP +The functions: \fBpam_sm_setcred\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM), +\fBpam_sm_open_session\fR(3PAM), and \fBpam_sm_close_session\fR(3PAM) do +nothing and return \fBPAM_IGNORE\fR in \fBpam_ldap\fR. diff --git a/usr/src/man/man7/pam_list.7 b/usr/src/man/man7/pam_list.7 new file mode 100644 index 0000000000..e7a0c1e9a4 --- /dev/null +++ b/usr/src/man/man7/pam_list.7 @@ -0,0 +1,308 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_LIST 7 "April 22, 2020" +.SH NAME +pam_list \- PAM account management module for UNIX +.SH SYNOPSIS +.nf + pam_list.so.1 +.fi + +.SH DESCRIPTION +The \fBpam_list\fR module implements \fBpam_sm_acct_mgmt\fR(3PAM), which +provides functionality to the PAM account management stack. The module +provides functions to validate that the user's account is valid on this +host based on a list of users, groups, and/or netgroups in the given file. The users, +groups, and netgroups are separated by newline character. Groups are specified +with character '%' and netgroups are specified with character '@' as prefix +before name of the group/netgroup in the list. The maximum line length is 1023 +characters. +.sp +.LP +The username is the value of \fBPAM_USER\fR. The host is the value of +\fBPAM_RHOST\fR or, if \fBPAM_RHOST\fR is not set, the value of the localhost +as returned by \fBgethostname\fR(3C) is used. +.sp +.LP +If neither of the \fBallow\fR, \fBdeny\fR, or \fBcompat\fR options are +specified, the module will look for +/- entries in the local \fB/etc/passwd\fR +file. If this style is used, \fBnsswitch.conf\fR(5) must not be configured +with \fBcompat\fR for the \fBpasswd\fR database. If no relevant +/- entry +exists for the user, \fBpam_list\fR is not participating in result. +.sp +.LP +If \fBcompat\fR option is specified then the module will look for +/- entries +in the local \fB/etc/passwd\fR file. Other entries in this file will be counted +as + entries. If no relevant entry exits for the user, \fBpam_list\fR will deny +the access. +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.na +\fB\fBallow=\fR\fR +.ad +.RS 19n +The full pathname to a file of allowed users, groups, and/or netgroups. +Only one of \fBallow=\fR or \fBdeny=\fR can be specified. +.RE + +.sp +.ne 2 +.na +\fB\fBcompat\fR\fR +.ad +.RS 19n +Activate \fBcompat\fR mode. +.RE + +.sp +.ne 2 +.na +\fB\fBdeny=\fR\fR +.ad +.RS 19n +The full pathname to a file of denied users, groups, and/or netgroups. +Only one of \fBdeny=\fR or \fBallow=\fR can be specified. +.RE + +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 19n +Provide \fBsyslog\fR(3C) debugging information at the \fBLOG_AUTH\fR | +\fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBgroup\fR\fR +.ad +.RS 19n +The module should perform group membership matches for the username. +.RE + +.sp +.ne 2 +.na +\fB\fBuser\fR\fR +.ad +.RS 19n +The module should only perform netgroup matches on the username. This is the +default option. +.RE + +.sp +.ne 2 +.na +\fB\fBnouser\fR\fR +.ad +.RS 19n +The username should not be used in the netgroup match. +.RE + +.sp +.ne 2 +.na +\fB\fBhost\fR\fR +.ad +.RS 19n +Only the host should be used in netgroup matches. +.RE + +.sp +.ne 2 +.na +\fB\fBnohost\fR\fR +.ad +.RS 19n +The hostname should not be used in netgroup matches. +.RE + +.sp +.ne 2 +.na +\fB\fBuser_host_exact\fR\fR +.ad +.RS 19n +The user and hostname must be in the same netgroup. +.RE + +.SH ERRORS +The following error values are returned: +.sp +.ne 2 +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 20n +An invalid set of module options was given in the \fBpam.conf\fR(5) for this +module, or the \fBuser/netgroup\fR file could not be opened. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +A memory buffer error occurred. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +The module is ignored, as it is not participating in the result. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 20n +The user is not on the allow list or is on the deny list. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +The account is valid for use at this time. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +No account is present for the user +.RE + +.SH EXAMPLES +\fBExample 1 \fRUsing \fBpam_list\fR in default mode +.sp +.LP +\fB/etc/pam.conf\fR modification looks like: + +.sp +.in +2 +.nf +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +other account required pam_list.so.1 +.fi +.in -2 + +.sp +.LP +In the case of \fBdefault\fR mode or \fBcompat\fR mode, the important lines in +\fB/etc/passwd\fR appear as follows: + +.sp +.in +2 +.nf ++loginname - user is approved +-loginname - user is disapproved ++@netgroup - netgroup members are approved +-@netgroup - netgroup members are disapproved +.fi +.in -2 + +.LP +\fBExample 2 \fRUsing \fBpam_list\fR with allow file +.sp +.LP +\fB/etc/pam.conf\fR modification looks like: + +.sp +.in +2 +.nf +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +other account required pam_list.so.1 allow=/etc/users.allow +.fi +.in -2 + +.sp +.LP +\fB/etc/users.allow\fR contains: +.sp +.in +2 +.nf +root +localloginname +remoteloginname +@netgroup +.fi +.in -2 + +.LP +\fBExample 3 \fRUsing \fBpam_list\fR with allow file to allow +members of the 'admins' group access. +.sp +.LP +\fB/etc/pam.conf\fR modification looks like: + +.sp +.in +2 +.nf +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +other account required pam_list.so.1 group allow=/etc/users.allow +.fi +.in -2 + +.sp +.LP +\fB/etc/users.allow\fR contains: +.sp +.in +2 +.nf +root +%admins +.fi +.in -2 + +.SH ATTRIBUTES +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT-Level MT-Safe with exceptions +.TE + +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multithreaded application uses its own PAM handle. +.SH SEE ALSO +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_sm_acct_mgmt (3PAM), +.BR nsswitch.conf (5), +.BR pam.conf (5), +.BR attributes (7) diff --git a/usr/src/man/man7/pam_passwd_auth.7 b/usr/src/man/man7/pam_passwd_auth.7 new file mode 100644 index 0000000000..b8ba03367e --- /dev/null +++ b/usr/src/man/man7/pam_passwd_auth.7 @@ -0,0 +1,155 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_PASSWD_AUTH 7 "Aug 10, 2002" +.SH NAME +pam_passwd_auth \- authentication module for password +.SH SYNOPSIS +.LP +.nf +\fBpam_passwd_auth.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +\fBpam_passwd_auth\fR provides authentication functionality to the password +service as implemented by \fBpasswd\fR(1). It differs from the standard +\fBPAM\fR authentication modules in its prompting behavior. It should be the +first module on the password service authentication stack. +.sp +.LP +The name of the user whose password attributes are to be updated must be +present in the \fBPAM_USER\fR item. This can be accomplished due to a previous +call to \fBpam_start\fR(3PAM), or explicitly set by \fBpam_set_item\fR(3PAM). +Based on the current user-id and the repository that is to by updated, the +module determines whether a password is necessary for a successful update of +the password repository, and if so, which password is required. +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 17n +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 17n +Turn off warning messages +.RE + +.sp +.ne 2 +.na +\fB\fBserver_policy\fR\fR +.ad +.RS 17n +If the account authority for the user, as specified by \fBPAM_USER\fR, is a +server, do not apply the Unix policy from the passwd entry in the name service +switch. +.RE + +.SH ERRORS +.sp +.LP +The following error codes are returned: +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 18n +Memory buffer error +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 18n +Ignore module, not participating in result +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +System error +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR passwd (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_set_item (3PAM), +.BR pam_start (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +This module relies on the value of the current real \fBUID\fR, this module is +only safe for MT-applications that don't change \fBUID\fRs during the call to +\fBpam_authenticate\fR(3PAM). +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). diff --git a/usr/src/man/man7/pam_rhosts_auth.7 b/usr/src/man/man7/pam_rhosts_auth.7 new file mode 100644 index 0000000000..68ea961cb6 --- /dev/null +++ b/usr/src/man/man7/pam_rhosts_auth.7 @@ -0,0 +1,72 @@ +'\" te +.\" Copyright (c) 1995, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_RHOSTS_AUTH 7 "Oct 28, 1996" +.SH NAME +pam_rhosts_auth \- authentication management PAM module using ruserok() +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/pam_rhosts_auth.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The rhosts \fBPAM\fR module, \fB/usr/lib/security/pam_rhosts_auth.so.1\fR, +authenticates a user via the \fBrlogin\fR authentication protocol. Only +\fBpam_sm_authenticate()\fR is implemented within this module. +\fBpam_sm_authenticate()\fR uses the \fBruserok\fR(3SOCKET) library function to +authenticate the \fBrlogin\fR or \fBrsh\fR user. \fBpam_sm_setcred()\fR is a +null function. +.sp +.LP +\fB/usr/lib/security/pam_rhosts_auth.so.1\fR is designed to be stacked on top +of the \fB/usr/lib/security/pam_unix.so.1\fR module for both the \fBrlogin\fR +and \fBrsh\fR services. This module is normally configured as \fIsufficient\fR +so that subsequent authentication is performed only on failure of +\fBpam_sm_authenticate()\fR. The following option may be passed in to this +service module: +.sp +.ne 2 +.na +\fB\fBdebug\fR \fR +.ad +.RS 10n +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR ruserok (3SOCKET), +.BR pam.conf (5), +.BR attributes (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam()\fR are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. diff --git a/usr/src/man/man7/pam_roles.7 b/usr/src/man/man7/pam_roles.7 new file mode 100644 index 0000000000..ad7b0ce111 --- /dev/null +++ b/usr/src/man/man7/pam_roles.7 @@ -0,0 +1,199 @@ +'\" te +.\" Copyright (C) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_ROLES 7 "Mar 6, 2007" +.SH NAME +pam_roles \- Solaris Roles account management module +.SH SYNOPSIS +.LP +.nf +pam_roles.so.1 +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_roles\fR module implements \fBpam_sm_acct_mgmt\fR(3PAM). It provides +functionality to verify that a user is authorized to assume a role. It also +prevents direct logins to a role. The \fBuser_attr\fR(5) database is used to +determine which users can assume which roles. +.sp +.LP +The \fBPAM\fR items \fBPAM_USER\fR and \fBPAM_AUSER\fR, and \fBPAM_RHOST\fR are +used to determine the outcome of this module. \fBPAM_USER\fR represents the new +identity being verified. \fBPAM_AUSER\fR, if set, represents the user asserting +a new identity. If \fBPAM_AUSER\fR is not set, the real user \fBID\fR of the +calling service implies that the user is asserting a new identity. Notice that +root can never have roles. +.sp +.LP +This module is generally stacked above the \fBpam_unix_account\fR(7) module. +.sp +.LP +The following options are interpreted: +.sp +.ne 2 +.na +\fB\fBallow_remote\fR\fR +.ad +.RS 16n +Allows a remote service to specify the user to enter as a role. +.RE + +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 16n +Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level. +.RE + +.SH ERRORS +.sp +.LP +The following values are returned: +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +If the type of the new user identity (\fBPAM_USER\fR) is "\fBnormal\fR". Or, if +the type of the new user identity is "\fBrole\fR" and the user asserting the +new identity (\fBPAM_AUSER\fR) has the new identity name in its list of roles. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +No account is present for user. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 20n +If the type of the new user identity (\fBPAM_USER\fR) is "\fBrole\fR" and the +user asserting the new identity (\fBPAM_AUSER\fR) does not have the new +identity name in its list of roles. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing the \fBpam_roles.so.1\fR Module +.sp +.LP +The following are sample entries from \fBpam.conf\fR(5). These entries +demonstrate the use of the \fBpam_roles.so.1\fR module: + +.sp +.in +2 +.nf +cron account required pam_unix_account.so.1 +# +other account requisite pam_roles.so.1 +other account required pam_unix_account.so.1 +# +.fi +.in -2 +.sp + +.sp +.LP +The \fBcron\fR service does not invoke \fBpam_roles.so.1\fR. Delayed jobs are +independent of role assumption. All other services verify that roles cannot +directly login. The "\fBsu\fR" service (covered by the "\fBother\fR" service +entry) verifies that if the new user is a role, the calling user is authorized +for that role. + +.LP +\fBExample 2 \fRAllowing Remote Roles +.sp +.LP +Remote roles should only be allowed from remote services that can be trusted to +provide an accurate \fBPAM_AUSER\fRname. This trust is a function of the +protocol (such as \fBsshd\fR-hostbased). + +.sp +.LP +The following is a sample entry for a \fBpam.conf\fR(5) file. It demonstrates +the use of \fBpam_roles\fR configuration for remote roles for the +\fBsshd\fR-hostbased service. + +.sp +.in +2 +.nf +sshd-hostbased account requisite pam_roles.so.1 allow_remote +sshd-hostbased account required pam_unix_account +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR roles (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_acct_mgmt (3PAM), +.BR pam_set_item (3PAM), +.BR pam_setcred (3PAM), +.BR pam_sm_acct_mgmt (3PAM), +.BR pam.conf (5), +.BR user_attr (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7), +.BR sshd (8), +.BR su (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +This module should never be stacked alone. It never returns \fBPAM_SUCCESS\fR, +as it never makes a positive decision. +.sp +.LP +The \fBallow_remote\fR option should only be specified for services that are +trusted to correctly identify the remote user (that is, \fBsshd\fR-hostbased). +.sp +.LP +\fBPAM_AUSER\fR has replaced \fBPAM_RUSER\fR whose definition is limited to the +\fBrlogin\fR/\fBrsh\fR untrusted remote user name. See +\fBpam_set_item\fR(3PAM). diff --git a/usr/src/man/man7/pam_sample.7 b/usr/src/man/man7/pam_sample.7 new file mode 100644 index 0000000000..b6f3b9f9ed --- /dev/null +++ b/usr/src/man/man7/pam_sample.7 @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_SAMPLE 7 "Apr 4, 2007" +.SH NAME +pam_sample \- a sample PAM module +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/pam_sample.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The SAMPLE service module for \fBPAM\fR is divided into four components: +authentication, account management, password management, and session +management. The sample module is a shared object that is dynamically loaded to +provide the necessary functionality. +.SH SAMPLE AUTHENTICATION COMPONENT +.sp +.LP +The SAMPLE authentication module provides functions to test the \fBPAM\fR +framework functionality using the \fBpam_sm_authenticate\fR(3PAM) call. The +SAMPLE module implementation of the \fBpam_sm_authenticate\fR(3PAM) function +compares the user entered password with the password set in the +\fBpam.conf\fR(5) file, or the string "test" if a default test password has not +been set. The following options can be passed in to the SAMPLE Authentication +module: +.sp +.ne 2 +.na +\fB\fBdebug\fR \fR +.ad +.RS 20n +Syslog debugging information at the \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBpass=newone\fR \fR +.ad +.RS 20n +Sets the password to be "newone". +.RE + +.sp +.ne 2 +.na +\fB\fBfirst_pass_good\fR \fR +.ad +.RS 20n +The first password is always good when used with the use_first_pass or +try_first_pass option. +.RE + +.sp +.ne 2 +.na +\fB\fBfirst_pass_bad\fR \fR +.ad +.RS 20n +The first password is always bad when used with the use_first_pass or +try_first_pass option. +.RE + +.sp +.ne 2 +.na +\fB\fBalways_fail\fR \fR +.ad +.RS 20n +Always returns \fBPAM_AUTH_ERR.\fR +.RE + +.sp +.ne 2 +.na +\fB\fBalways_succeed\fR \fR +.ad +.RS 20n +Always returns \fBPAM_SUCCESS.\fR +.RE + +.sp +.ne 2 +.na +\fB\fBalways_ignore\fR \fR +.ad +.RS 20n +Always returns \fBPAM_IGNORE.\fR +.RE + +.sp +.ne 2 +.na +\fB\fBuse_first_pass\fR \fR +.ad +.RS 20n +Use the user's initial password (entered when the user is authenticated to the +first authentication module in the stack) to authenticate with the SAMPLE +module. If the passwords do not match, or if this is the first authentication +module in the stack, quit and do not prompt the user for a password. It is +recommended that this option only be used if the SAMPLE authentication module +is designated as \fIoptional\fR in the \fBpam.conf\fR configuration file. +.RE + +.sp +.ne 2 +.na +\fB\fBtry_first_pass\fR \fR +.ad +.RS 20n +Use the user's initial password (entered when the user is authenticated to the +first authentication module in the stack) to authenticate with the SAMPLE +module. If the passwords do not match, or if this is the first authentication +module in the stack, prompt the user for a password. +.sp +The SAMPLE module \fBpam_sm_setcred\fR(3PAM) function always returns +\fBPAM_SUCCESS.\fR +.RE + +.SH SAMPLE ACCOUNT MANAGEMENT COMPONENT +.sp +.LP +The SAMPLE Account Management Component implements a simple access control +scheme that limits machine access to a list of authorized users. The list of +authorized users is supplied as option arguments to the entry for the SAMPLE +account management \fBPAM\fR module in the \fBpam.conf\fR file. Note that the +module always permits access to the root super user. +.sp +.LP +The option field syntax to limit access is shown below: allow= +\fIname[,name]\fR allow= \fIname\fR \fI[allow=name]\fR +.sp +.LP +The example \fBpam.conf\fR show below permits only larry to \fBlogin\fR +directly. \fBrlogin\fR is allowed only for don and larry. Once a user is logged +in, the user can use \fBsu\fR if the user are sam or eric. +.sp + +.sp +.TS +l l l l l +l l l l l . +login account require pam_sample.so.1 allow=larry +dtlogin account require pam_sample.so.1 allow=larry +rlogin account require pam_sample.so.1 allow=don allow=larry +su account require pam_sample.so.1 allow=sam,eric +.TE + +.sp +.LP +The debug and nowarn options are also supported. +.SH SAMPLE PASSWORD MANAGEMENT COMPONENT +.sp +.LP +The SAMPLE Password Management Component function ( +\fBpam_sm_chauthtok\fR(3PAM)), always returns \fBPAM_SUCCESS.\fR +.SH SAMPLE SESSION MANAGEMENT COMPONENT +.sp +.LP +The SAMPLE Session Management Component functions ( +\fBpam_sm_open_session\fR(3PAM), \fBpam_sm_close_session\fR(3PAM)) always +return \fBPAM_SUCCESS.\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR pam_sm_chauthtok (3PAM), +.BR pam_sm_close_session (3PAM), +.BR pam_sm_open_session (3PAM), +.BR pam_sm_setcred (3PAM), +.BR pam.conf (5), +.BR attributes (7) +.SH WARNINGS +.sp +.LP +This module should never be used outside of a closed debug environment. The +examples of the \fBuse_first_pass\fR and \fBtry_first_pass\fR options are +obsolete for all other Solaris delivered PAM service modules +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam()\fR are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. diff --git a/usr/src/man/man7/pam_smb_passwd.7 b/usr/src/man/man7/pam_smb_passwd.7 new file mode 100644 index 0000000000..b55b0d7229 --- /dev/null +++ b/usr/src/man/man7/pam_smb_passwd.7 @@ -0,0 +1,190 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_SMB_PASSWD 7 "Apr 29, 2008" +.SH NAME +pam_smb_passwd \- SMB password management module +.SH SYNOPSIS +.LP +.nf +\fBpam_smb_passwd.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_smb_passwd\fR module enhances the PAM password management stack. +This functionality supports the changing or adding of SMB passwords for local +Solaris users. The Solaris CIFS server uses SMB passwords to authenticate +connected Solaris users. This module includes the \fBpam_sm_chauthtok\fR(3PAM) +function. +.sp +.LP +The \fBpam_sm_chauthtok()\fR function accepts the following flags: +.sp +.ne 2 +.na +\fB\fBPAM_PRELIM_CHECK\fR\fR +.ad +.sp .6 +.RS 4n +Always returns \fBPAM_IGNORE\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SILENT\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses messages. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_UPDATE_AUTHTOK\fR\fR +.ad +.sp .6 +.RS 4n +Updates or creates a new \fBCIFS\fR local \fBLM\fR/\fBNTLM\fR hash for the user +that is specified in \fBPAM_USER\fR by using the authentication information +found in \fBPAM_AUTHTOK\fR. The \fBLM\fR hash is only created if the +\fBsmbd/lmauth_level\fR property value of the \fBsmb/server\fR service is set +to 3 or less. \fBPAM_IGNORE\fR is returned if the user is not in the local +\fB/etc/passwd\fR repository. +.RE + +.sp +.LP +The following options can be passed to the \fBpam_smb_passwd\fR module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.sp .6 +.RS 4n +Produces \fBsyslog\fR(3C) debugging information at the \fBLOG_AUTH\fR or +\fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses warning messages. +.RE + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/var/smb/smbpasswd\fR\fR +.ad +.sp .6 +.RS 4n +Stores SMB passwords for Solaris users. +.RE + +.SH ERRORS +.sp +.LP +Upon successful completion of \fBpam_sm_chauthtok()\fR, \fBPAM_SUCCESS\fR is +returned. The following error codes are returned upon error: +.sp +.ne 2 +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Authentication token manipulation error +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTHTOK_LOCK_BUSY\fR\fR +.ad +.sp .6 +.RS 4n +\fBSMB\fR password file is locked +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.sp .6 +.RS 4n +Permissions are insufficient for accessing the \fBSMB\fR password file +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.sp .6 +.RS 4n +System error +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.sp .6 +.RS 4n +User is unknown +.RE + +.SH ATTRIBUTES +.sp +.LP +See the \fBattributes\fR(7) man page for descriptions of the following +attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_chauthtok (3PAM), +.BR pam_sm (3PAM), +.BR pam_sm_chauthtok (3PAM), +.BR pam.conf (5), +.BR attributes (7), +.BR smbd (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe \fBonly\fR if each thread +within the multi-threaded application uses its own PAM handle. +.sp +.LP +The \fBpam_smb_passwd.so.1\fR module should be stacked following all password +qualification modules in the \fBPAM\fR password stack. diff --git a/usr/src/man/man7/pam_smbfs_login.7 b/usr/src/man/man7/pam_smbfs_login.7 new file mode 100644 index 0000000000..0ad333585b --- /dev/null +++ b/usr/src/man/man7/pam_smbfs_login.7 @@ -0,0 +1,232 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_SMBFS_LOGIN 7 "Sep 25, 2008" +.SH NAME +pam_smbfs_login \- PAM user credential authentication module for SMB/CIFS +client login +.SH SYNOPSIS +.LP +.nf +pam_smb_cred.so.1 +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_smbfs_login\fR module implements \fBpam_sm_setcred\fR(3PAM) to +provide functions that act equivalently to the \fBsmbutil\fR(1) login command. +.sp +.LP +This optional functionality is meant to be used only in environments that do +not run Active Directory or Kerberos, but which synchronize passwords between +Solaris clients and their CIFS/SMB servers. +.sp +.LP +This module permits the login password to be stored as if the \fBsmbutil\fR(1) +login command was used to store a password for PAM_USER in the user or system +default domain. The choice of default domain is the first of the following: +.br +.in +2 +-Domain entry specified in the default section of the \fB$HOME/.nsmbrc\fR +file, if readable. +.in -2 +.br +.in +2 +-Domain entry specified in the default section shown by the sharectl get smbfs +command. +.in -2 +.br +.in +2 +-String WORKGROUP. +.in -2 +.sp +.LP +Because \fBpam_smbfs_login\fR runs as root during the login process, a +\fB$HOME/.nsmbrc\fR file accessed through NFS may only be readable if the file +permits reads by others. This conflicts with the requirement that passwords +stored in \fB$HOME/.nsmbrc\fR are ignored when permissions are open. +.sp +.LP +To use this functionality, add the following line to the \fB/etc/pam.conf\fR +file: +.sp +.in +2 +.nf +login auth optional pam_smbfs_login.so.1 +.fi +.in -2 + +.sp +.LP +Authentication service modules must implement both +\fBpam_sm_authenticate\fR(3PAM) and \fBpam_sm_setcred\fR(3PAM). In this module, +\fBpam_sm_authenticate\fR(3PAM) always returns \fBPAM_IGNORE\fR. +.sp +.LP +The \fBpam_sm_setcred\fR(3PAM) function accepts the following flags: +.sp +.ne 2 +.na +\fB\fBPAM_REFRESH_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Returns PAM_IGNORE. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SILENT\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses messages. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_ESTABLISH_CRED\fR\fR +.ad +.br +.na +\fB\fBPAM_REINITIALIZE_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Stores the authentication token for PAM_USER in the same manner as the +\fBsmbutil\fR(1) login command. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_DELETE_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Deletes the stored password for PAM_USER in the same manner as the +\fBsmbutil\fR(1) logout command. +.RE + +.sp +.LP +The following options can be passed to the \fBpam_smbfs_login\fR module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.sp .6 +.RS 4n +Produces \fBsyslog\fR(3C) debugging information at the LOG_AUTH or LOG_DEBUG +level. +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses warning messages. +.RE + +.SH FILES +.sp +.ne 2 +.na +\fB\fB$HOME/.nsmbrc\fR\fR +.ad +.RS 28n +Find default domain, if present. +.RE + +.SH ERRORS +.sp +.LP +Upon successful completion of \fBpam_sm_setcred\fR(3PAM), \fBPAM_SUCCESS\fR is +returned. The following error codes are returned upon error: +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.sp .6 +.RS 4n +User is unknown. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Password is bad. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Domain is bad. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.sp .6 +.RS 4n +System error. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attribute: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR smbutil (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_setcred (3PAM), +.BR pam_sm (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR pam_sm_chauthtok (3PAM), +.BR pam_sm_setcred (3PAM), +.BR smbfs (4FS), +.BR pam.conf (5), +.BR attributes (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within +the multi-threaded application uses its own PAM handle. diff --git a/usr/src/man/man7/pam_timestamp.7 b/usr/src/man/man7/pam_timestamp.7 new file mode 100644 index 0000000000..695106d84d --- /dev/null +++ b/usr/src/man/man7/pam_timestamp.7 @@ -0,0 +1,113 @@ +.\" +.\" 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 Nexenta Systems, Inc. +.\" +.Dd Nov 26, 2017 +.Dt PAM_TIMESTAMP 7 +.Os +.Sh NAME +.Nm pam_timestamp +.Nd PAM authentication module using cached successful authentication attempts +.Sh SYNOPSIS +.Nm pam_timestamp.so.1 +.Op Ar debug +.Op Ar timeout=min +.Sh DESCRIPTION +The +.Nm +module caches successful tty-based authentication attempts by +creating user's directories and per tty timestamp files in the +common timestamp directory +.Pa /var/run/tty_timestamps . +Next authentication, if the timestamp file exist and not expired, +the user will not be asked for a password, otherwise timestamp +file will be deleted and user will be prompted to enter a password. +.Lp +The PAM items +.Dv PAM_USER , +.Dv PAM_AUSER +and +.Dv PAM_TTY +are used by this module. +.Sy pam_timestamp +is normally configured as +.Sy sufficient +and must be used in conjunction with the modules that support +the UNIX authentication, which are +.Xr pam_authtok_get 7 , +.Xr pam_unix_cred 7 +and +.Xr pam_unix_auth 7 . +Proper authentication operation requires +.Xr pam_unix_cred 7 +be stacked above +.Nm . +.Sh OPTIONS +.Bl -tag -width Ds +.It Dv debug +Provides +.Xr syslog 3C +debugging information at the +.Sy LOG_AUTH | LOG_DEBUG +level. +.It Dv timeout +Specifies the period (in minutes) for which the timestamp file is valid. +The default value is 5 minutes. +.El +.Sh FILES +.Bl -tag -width indent +.It Pa /var/run/tty_timestamps/... +stores timestamp directories and files +.El +.Sh EXIT STATUS +.Bl -tag -width Ds +.It Dv PAM_SUCCESS +Timestamp file is not expired. +.It Dv PAM_IGNORE +The +.Nm +module was not able to retrieve required credentials +or timestamp file is expired or corrupt. +.El +.Sh EXAMPLES +.Ss Example 1 Allowing su authentication +. +The following example is a +.Xr pam.conf 5 +fragment that illustrates default settings for allowing +.Xr su 8 +authentication: +.Bd -literal -offset indent +su auth required pam_unix_cred.so.1 +su auth sufficient pam_timestamp.so.1 +su auth requisite pam_authtok_get.so.1 +su auth required pam_unix_auth.so.1 +.Ed +.Ss Example 2 Changing default timeout +. +The default timeout set to 10 minutes: +.Bd -literal -offset indent +su auth required pam_unix_cred.so.1 +su auth sufficient pam_timestamp.so.1 timeout=10 +su auth requisite pam_authtok_get.so.1 +su auth required pam_unix_auth.so.1 +.Ed +.Sh INTERFACE STABILITY +.Sy Uncommitted . +.Sh MT LEVEL +.Sy MT-Safe . +.Sh SEE ALSO +.Xr syslog 3C , +.Xr pam 3PAM , +.Xr pam_sm_authenticate 3PAM , +.Xr pam_sm_setcred 3PAM , +.Xr pam.conf 5 , +.Xr su 8 diff --git a/usr/src/man/man7/pam_tsol_account.7 b/usr/src/man/man7/pam_tsol_account.7 new file mode 100644 index 0000000000..3b12a24648 --- /dev/null +++ b/usr/src/man/man7/pam_tsol_account.7 @@ -0,0 +1,144 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_TSOL_ACCOUNT 7 "Jul 20, 2007" +.SH NAME +pam_tsol_account \- PAM account management module for Trusted Extensions +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/pam_tsol_account.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The Solaris Trusted Extensions service module for \fBPAM\fR, +\fB/usr/lib/security/pam_tsol_account.so.1\fR, checks account limitations that +are related to labels. The \fBpam_tsol_account.so.1\fR module is a shared +object that can be dynamically loaded to provide the necessary functionality +upon demand. Its path is specified in the \fBPAM\fR configuration file. +.sp +.LP +\fBpam_tsol_account.so.1\fR contains a function to perform account management, +\fBpam_sm_acct_mgmt()\fR. The function checks for the allowed label range for +the user. The allowable label range is set by the defaults in the +\fBlabel_encodings\fR(5) file. These defaults can be overridden by entries in +the \fBuser_attr\fR(5) database. +.sp +.LP +By default, this module requires that remote hosts connecting to the global +zone must have a CIPSO host type. To disable this policy, add the +\fBallow_unlabeled\fR keyword as an option to the entry in \fBpam.conf\fR(5), +as in: +.sp +.in +2 +.nf +other account required pam_tsol_account allow_unlabeled +.fi +.in -2 +.sp + +.SH OPTIONS +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.na +\fB\fBallow_unlabeled\fR\fR +.ad +.RS 19n +Allows remote connections from hosts with unlabeled template types. +.RE + +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 19n +Provides debugging information at the \fBLOG_DEBUG\fR level. See +\fBsyslog\fR(3C). +.RE + +.SH RETURN VALUES +.sp +.LP +The following values are returned: +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 19n +The account is valid for use at this time and label. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 19n +The current process label is outside the user's label range, or the label +information for the process is unavailable, or the remote host type is not +valid. +.RE + +.sp +.ne 2 +.na +\fBOther values\fR +.ad +.RS 19n +Returns an error code that is consistent with typical PAM operations. For +information on error-related return values, see the \fBpam\fR(3PAM) man page. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT Level MT-Safe with exceptions +.TE + +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.SH SEE ALSO +.sp +.LP +.BR keylogin (1), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_sm_acct_mgmt (3PAM), +.BR pam_start (3PAM), +.BR label_encodings (5), +.BR pam.conf (5), +.BR user_attr (5), +.BR attributes (7) +.sp +.LP +Chapter 17, \fIUsing PAM,\fR in \fISystem Administration Guide: Security +Services\fR +.SH NOTES +.sp +.LP +The functionality described on this manual page is available only if the system +is configured with Trusted Extensions. diff --git a/usr/src/man/man7/pam_unix_account.7 b/usr/src/man/man7/pam_unix_account.7 new file mode 100644 index 0000000000..516f486550 --- /dev/null +++ b/usr/src/man/man7/pam_unix_account.7 @@ -0,0 +1,177 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_UNIX_ACCOUNT 7 "Feb 14, 2005" +.SH NAME +pam_unix_account \- PAM account management module for UNIX +.SH SYNOPSIS +.LP +.nf +\fBpam_unix_account.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +\fBpam_unix_account\fR module implements \fBpam_sm_acct_mgmt()\fR, which +provides functionality to the \fBPAM\fR account management stack. The module +provides functions to validate that the user's account is not locked or expired +and that the user's password does not need to be changed. The module retrieves +account information from the configured databases in \fBnsswitch.conf\fR(5). +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 17n +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 17n +Turn off warning messages +.RE + +.sp +.ne 2 +.na +\fB\fBserver_policy\fR\fR +.ad +.RS 17n +If the account authority for the user, as specified by \fBPAM_USER\fR, is a +server, do not apply the Unix policy from the passwd entry in the name service +switch. +.RE + +.SH ERRORS +.sp +.LP +The following values are returned: +.sp +.ne 2 +.na +\fB\fBPAM_UNIX_ACCOUNT\fR\fR +.ad +.RS 24n +User account has expired +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_AUTHTOK_EXPIRED\fR\fR +.ad +.RS 24n +Password expired and no longer usable +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 24n +Memory buffer error +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 24n +Ignore module, not participating in result +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +Obtain new authentication token from the user +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 24n +The account is locked or has been inactive for too long +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 24n +Error in underlying service module +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +The account is valid for use at this time +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +No account is present for the user +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR nsswitch.conf (5), +.BR pam.conf (5), +.BR attributes (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +Attempts to validate locked accounts are logged via \fBsyslog\fR(3C) to the +\fBLOG_AUTH\fR facility with a \fBLOG_NOTICE\fR severity. diff --git a/usr/src/man/man7/pam_unix_auth.7 b/usr/src/man/man7/pam_unix_auth.7 new file mode 100644 index 0000000000..9b3f09430f --- /dev/null +++ b/usr/src/man/man7/pam_unix_auth.7 @@ -0,0 +1,244 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_UNIX_AUTH 7 "Apr 23, 2008" +.SH NAME +pam_unix_auth \- PAM authentication module for UNIX +.SH SYNOPSIS +.LP +.nf +\fBpam_unix_auth.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_unix_auth\fR module implements \fBpam_sm_authenticate()\fR, which +provides functionality to the PAM authentication stack. It provides functions +that use \fBcrypt\fR(3C) to verify that the password contained in the \fBPAM\fR +item \fBPAM_AUTHTOK\fR is the correct password for the user specified in the +item \fBPAM_USER\fR. If \fBPAM_REPOSITORY\fR is specified, then user's password +is fetched from that repository. Otherwise, the default \fBnsswitch.conf\fR(5) +repository is searched for that user. +.sp +.LP +For accounts in the name services which support automatic account locking, the +account may be configured to be automatically locked (see \fBuser_attr\fR(5) +and \fBpolicy.conf\fR(5)) after multiple failed login attempts. For accounts +that are configured for automatic locking, if authentication failure is to be +returned, the failed login counter is incremented upon each failure. If the +number of successive failures equals or exceeds \fBRETRIES\fR as defined in +\fBlogin\fR(1), the account is locked and \fBPAM_MAXTRIES\fR is returned. +Currently, only the "files" repository (see \fBpasswd\fR(5) and +\fBshadow\fR(5)) supports automatic account locking. A successful +authentication by this module clears the failed login counter and reports the +number of failed attempts since the last successful authentication. +.sp +.LP +Authentication service modules must implement both \fBpam_sm_authenticate()\fR +and \fBpam_sm_setcred()\fR. To allow the authentication portion of UNIX +authentication to be replaced, \fBpam_sm_setcred()\fR in this module always +returns \fBPAM_IGNORE\fR. This module should be stacked with +\fBpam_unix_cred\fR(7) to ensure a successful return from +\fBpam_setcred\fR(3PAM). +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.sp .6 +.RS 4n +Turn off warning messages. +.RE + +.sp +.ne 2 +.na +\fB\fBserver_policy\fR\fR +.ad +.sp .6 +.RS 4n +If the account authority for the user, as specified by \fBPAM_USER\fR, is a +server, do not apply the UNIX policy from the \fBpasswd\fR entry in the name +service switch. +.RE + +.sp +.ne 2 +.na +\fB\fBnolock\fR\fR +.ad +.sp .6 +.RS 4n +Regardless of the automatic account locking setting for the account, do not +lock the account, increment or clear the failed login count. The \fBnolock\fR +option allows for exempting account locking on a per service basis. +.RE + +.SH ERRORS +.sp +.LP +The following error codes are returned from \fBpam_sm_authenticate()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Authentication failure. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Memory buffer error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.sp .6 +.RS 4n +Ignores module, not participating in result. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_MAXTRIES\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of retries exceeded. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.sp .6 +.RS 4n +Permission denied. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +Successfully obtains authentication token. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.sp .6 +.RS 4n +System error. +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.sp .6 +.RS 4n +No account present for user. +.RE + +.sp +.LP +The following error codes are returned from \fBpam_sm_setcred()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.sp .6 +.RS 4n +Ignores this module regardless of the control flag. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR login (1), +.BR passwd (1), +.BR crypt (3C), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR pam_setcred (3PAM), +.BR nsswitch.conf (5), +.BR pam.conf (5), +.BR passwd (5), +.BR policy.conf (5), +.BR shadow (5), +.BR user_attr (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_session (7), +.BR roleadd (8), +.BR rolemod (8), +.BR useradd (8), +.BR usermod (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), +\fBpam_passwd_auth\fR(7), \fBpam_setcred\fR(3PAM), \fBpam_unix_account\fR(7), +\fBpam_unix_cred\fR(7), \fBpam_unix_session\fR(7). +.sp +.LP +If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does +not recognize the type, the service module does not process any information, +and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is +not set, a service module performs its default action. diff --git a/usr/src/man/man7/pam_unix_cred.7 b/usr/src/man/man7/pam_unix_cred.7 new file mode 100644 index 0000000000..add7af7527 --- /dev/null +++ b/usr/src/man/man7/pam_unix_cred.7 @@ -0,0 +1,226 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_UNIX_CRED 7 "Mar 9, 2005" +.SH NAME +pam_unix_cred \- PAM user credential authentication module for UNIX +.SH SYNOPSIS +.LP +.nf +\fBpam_unix_cred.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_unix_cred\fR module implements \fBpam_sm_setcred\fR(3PAM). It +provides functions that establish user credential information. It is a module +separate from the \fBpam_unix_auth\fR(7) module to allow replacement of the +authentication functionality independently from the credential functionality. +.sp +.LP +The \fBpam_unix_cred\fR module must always be stacked along with whatever +authentication module is used to ensure correct credential setting. +.sp +.LP +Authentication service modules must implement both \fBpam_sm_authenticate()\fR +and \fBpam_sm_setcred()\fR. +.sp +.LP +\fBpam_sm_authenticate()\fR in this module always returns \fBPAM_IGNORE\fR. +.sp +.LP +\fBpam_sm_setcred()\fR initializes the user's project, privilege sets and +initializes or updates the user's audit context if it hasn't already been +initialized. The following flags may be set in the flags field: +.sp +.ne 2 +.na +\fB\fBPAM_ESTABLISH_CRED\fR\fR +.ad +.br +.na +\fB\fBPAM_REFRESH_CRED\fR\fR +.ad +.br +.na +\fB\fBPAM_REINITIALIZE_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Initializes the user's project to the project specified in \fBPAM_RESOURCE\fR, +or if \fBPAM_RESOURCE\fR is not specified, to the user's default project. +Establishes the user's privilege sets. +.sp +If the audit context is not already initialized and auditing is configured, +these flags cause the context to be initialized to that of the user specified +in \fBPAM_AUSER\fR (if any) merged with the user specified in \fBPAM_USER\fR +and host specified in \fBPAM_RHOST\fR. If \fBPAM_RHOST\fR is not specified, +\fBPAM_TTY\fR specifies the local terminal name. Attributing audit to +\fBPAM_AUSER\fR and merging \fBPAM_USER\fR is required for correctly +attributing auditing when the system entry is performed by another user that +can be identified as trustworthy. +.sp +If the audit context is already initialized, the \fBPAM_REINITIALIZE_CRED\fR +flag merges the current audit context with that of the user specified in +\fBPAM_USER\fR. \fBPAM_REINITIALIZE_CRED\fR is useful when a user is assuming a +new identity, as with \fBsu\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_DELETE_CRED\fR\fR +.ad +.sp .6 +.RS 4n +This flag has no effect and always returns \fBPAM_SUCCESS\fR. +.RE + +.sp +.LP +The following options are interpreted: +.sp +.ne 2 +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +Disables any warning messages. +.RE + +.SH ERRORS +.sp +.LP +Upon successful completion of \fBpam_sm_setcred()\fR, \fBPAM_SUCCESS\fR is +returned. The following error codes are returned upon error: +.sp +.ne 2 +.na +\fB\fBPAM_CRED_UNAVAIL\fR\fR +.ad +.RS 20n +Underlying authentication service cannot retrieve user credentials +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_CRED_EXPIRED\fR\fR +.ad +.RS 20n +User credentials have expired +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +User is unknown to the authentication service +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_CRED_ERR\fR\fR +.ad +.RS 20n +Failure in setting user credentials +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +Memory buffer error +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +System error +.RE + +.sp +.LP +The following values are returned from \fBpam_sm_authenticate()\fR: +.sp +.ne 2 +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 14n +Ignores this module regardless of the control flag +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR ssh (1), +.BR settaskid (2), +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_set_item (3PAM), +.BR pam_sm_authenticate (3PAM), +.BR getprojent (3PROJECT), +.BR setproject (3PROJECT), +.BR nsswitch.conf (5), +.BR pam.conf (5), +.BR project (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7), +.BR pam_unix_session (7), +.BR privileges (7), +.BR su (8) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own \fBPAM\fR handle. +.sp +.LP +If this module is replaced, the audit context and credential may not be +correctly configured. diff --git a/usr/src/man/man7/pam_unix_session.7 b/usr/src/man/man7/pam_unix_session.7 new file mode 100644 index 0000000000..1076e93a59 --- /dev/null +++ b/usr/src/man/man7/pam_unix_session.7 @@ -0,0 +1,122 @@ +'\" te +.\" Copyright 2016 Toomas Soome <tsoome@me.com> +.\" Copyright (C) 2002, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PAM_UNIX_SESSION 7 "Jan 3, 2016" +.SH NAME +pam_unix_session \- session management PAM module for UNIX +.SH SYNOPSIS +.LP +.nf +\fBpam_unix_session.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_unix_session\fR module implements \fBpam_sm_open_session\fR(3PAM) +and \fBpam_sm_close_session\fR(3PAM). +.sp +.LP +\fBpam_sm_open_session()\fR updates the \fB/var/adm/lastlog\fR file with the +information contained in the \fBPAM_USER\fR, \fBPAM_TTY\fR, and +\fBPAM_RHOSTS\fR items. \fBpam_unix_account\fR(7) uses this account to +determine the previous time the user logged in. +.sp +.LP +\fBpam_sm_close_session()\fR is a null function. +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.na +\fBdebug\fR +.ad +.RS 9n +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.na +\fB\fBnowarn\fR\fR +.ad +.RS 9n +Turn off last login PAM_TEXT_INFO message. +.RE + +.SH ERRORS +.sp +.LP +Upon successful completion, \fBPAM_SUCCESS\fR is returned. The following error +codes are returned upon error: +.sp +.ne 2 +.na +\fB\fBPAM_SESSION_ERR\fR\fR +.ad +.RS 20n +Cannot make or remove the entry for the specified session (PAM_TTY is not +present). +.RE + +.sp +.ne 2 +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +No account is present for \fIuser\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +_ +MT Level MT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +.BR syslog (3C), +.BR libpam (3LIB), +.BR pam (3PAM), +.BR pam_authenticate (3PAM), +.BR nsswitch.conf (5), +.BR pam.conf (5), +.BR attributes (7), +.BR pam_authtok_check (7), +.BR pam_authtok_get (7), +.BR pam_authtok_store (7), +.BR pam_dhkeys (7), +.BR pam_passwd_auth (7), +.BR pam_unix_account (7), +.BR pam_unix_auth (7) +.SH NOTES +.sp +.LP +The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the +multi-threaded application uses its own PAM handle. +.sp +.LP +The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7), +\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7), +\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and +\fBpam_unix_session\fR(7). diff --git a/usr/src/man/man7/pkcs11_kernel.7 b/usr/src/man/man7/pkcs11_kernel.7 new file mode 100644 index 0000000000..61d96b679c --- /dev/null +++ b/usr/src/man/man7/pkcs11_kernel.7 @@ -0,0 +1,114 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PKCS11_KERNEL 7 "Oct 27, 2005" +.SH NAME +pkcs11_kernel \- PKCS#11 interface to Kernel Cryptographic Framework +.SH SYNOPSIS +.LP +.nf +/usr/lib/security/pkcs11_kernel.so +/usr/lib/security/64/pkcs11_kernel.so +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpkcs11_kernel.so\fR object implements the RSA PKCS#11 v2.20 +specification by using a private interface to communicate with the Kernel +Cryptographic Framework. +.sp +.LP +Each unique hardware provider is represented by a PKCS#11 slot. In a system +with no hardware Kernel Cryptographic Framework providers, this PKCS#11 library +presents no slots. +.sp +.LP +The PKCS#11 mechanisms provided by this library is determined by the available +hardware providers. +.sp +.LP +Application developers should link to \fBlibpkcs11.so\fR rather than link +directly to \fBpkcs11_kernel.so\fR. See \fBlibpkcs11\fR(3LIB). +.sp +.LP +All of the Standard PKCS#11 functions listed on \fBlibpkcs11\fR(3LIB) are +implemented except for the following: +.sp +.in +2 +.nf +C_DecryptDigestUpdate +C_DecryptVerifyUpdate +C_DigestEncryptUpdate +C_GetOperationState +C_InitToken +C_InitPIN +C_SetOperationState +C_SignEncryptUpdate +C_WaitForSlotEvent +.fi +.in -2 + +.sp +.LP +A call to these functions returns \fBCKR_FUNCTION_NOT_SUPPORTED\fR. +.sp +.LP +Buffers cannot be greater than 2 megabytes. For example, \fBC_Encrypt()\fR can +be called with a 2 megabyte buffer of plaintext and a 2 megabyte buffer for the +ciphertext. +.sp +.LP +The maximum number of object handles that can be returned by a call to +\fBC_FindObjects()\fR is 512. +.sp +.LP +The maximum amount of kernel memory that can be used for crypto operations is +limited by the \fBproject.max-crypto-memory\fR resource control. Allocations in +the kernel for buffers and session-related structures are charged against this +resource control. +.SH RETURN VALUES +.sp +.LP +The return values of each of the implemented functions are defined and listed +in the RSA PKCS#11 v2.20 specification. See http://www.rsasecurity.com. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Standard: PKCS#11 v2.20 +_ +MT-Level T{ +MT-Safe with exceptions. See section 6.5.2 of RSA PKCS#11 v2.20 +T} +.TE + +.SH SEE ALSO +.sp +.LP +.BR libpkcs11 (3LIB), +.BR attributes (7), +.BR pkcs11_softtoken (7), +.BR cryptoadm (8), +.BR rctladm (8) +.sp +.LP +RSA PKCS#11 v2.20 http://www.rsasecurity.com +.SH NOTES +.sp +.LP +Applications that have an open session to a PKCS#11 slot make the corresponding +hardware provider driver not unloadable. An administrator must close the +applications that have an PKCS#11 session open to the hardware provider to make +the driver unloadable. diff --git a/usr/src/man/man7/pkcs11_softtoken.7 b/usr/src/man/man7/pkcs11_softtoken.7 new file mode 100644 index 0000000000..ee20e34e2b --- /dev/null +++ b/usr/src/man/man7/pkcs11_softtoken.7 @@ -0,0 +1,283 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PKCS11_SOFTTOKEN 7 "Mar 25, 2008" +.SH NAME +pkcs11_softtoken \- Software RSA PKCS#11 softtoken +.SH SYNOPSIS +.LP +.nf +/usr/lib/security/pkcs11_softtoken.so +/usr/lib/security/64/pkcs11_softtoken.so +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpkcs11_softtoken.so\fR object implements the RSA PKCS#11 v2.20 +specification in software. Persistent storage for "token" objects is provided +by this PKCS#11 implementation. +.sp +.LP +Application developers should link to \fBlibpkcs11.so\fR rather than link +directly to \fBpkcs11_softtoken.so\fR. See \fBlibpkcs11\fR(3LIB). +.sp +.LP +The following cryptographic algorithms are implemented: DES, 3DES, AES, +Blowfish, RC4, MD5, SHA1, SHA256, SHA384, SHA512, RSA, DSA, DH, and ECC. +.sp +.LP +All of the Standard PKCS#11 functions listed on \fBlibpkcs11\fR(3LIB) are +implemented except for the following: +.sp +.in +2 +.nf +C_GetObjectSize +C_InitPIN +C_InitToken +C_WaitForSlotEvent +.fi +.in -2 + +.sp +.LP +A call to these functions returns \fBCKR_FUNCTION_NOT_SUPPORTED\fR. +.sp +.LP +The following RSA PKCS#11 v2.20 mechanisms are supported: +.sp +.in +2 +.nf +CKM_RSA_PKCS_KEY_PAIR_GEN +CKM_RSA_PKCS +CKM_RSA_X_509 + +CKM_DSA_KEY_PAIR_GEN +CKM_DSA +CKM_DSA_SHA1 + +CKM_DH_PKCS_KEY_PAIR_GEN +CKM_DH_PKCS_DERIVE + +CKM_EC_KEY_PAIR_GEN +CKM_ECDSA +CKM_ECDSA_SHA1 +CKM_ECDH1_DERIVE + +CKM_DES_KEY_GEN +CKM_DES_ECB +CKM_DES_CBC +CKM_DES_CBC_PAD + +CKM_DES3_KEY_GEN +CKM_DES3_ECB +CKM_DES3_CBC +CKM_DES3_CBC_PAD + +CKM_AES_KEY_GEN +CKM_AES_ECB +CKM_AES_CBC +CKM_AES_CBC_PAD +CKM_AES_CTR + +CKM_BLOWFISH_KEY_GEN +CKM_BLOWFISH_CBC + +CKM_RC4_KEY_GEN +CKM_RC4 + +CKM_MD5_RSA_PKCS +CKM_SHA1_RSA_PKCS +CKM_SHA256_RSA_PKCS +CKM_SHA384_RSA_PKCS +CKM_SHA512_RSA_PKCS + +CKM_MD5 +CKM_SHA_1 +CKM_SHA256 +CKM_SHA384 +CKM_SHA512 + +CKM_MD5_HMAC +CKM_MD5_HMAC_GENERAL +CKM_SHA_1_HMAC +CKM_SHA_1_HMAC_GENERAL +CKM_SHA256_HMAC +CKM_SHA256_HMAC_GENERAL +CKM_SHA384_HMAC +CKM_SHA384_HMAC_GENERAL + +CKM_MD5_KEY_DERIVATION +CKM_SHA1_KEY_DERIVATION +CKM_SHA256_KEY_DERIVATION +CKM_SHA384_KEY_DERIVATION +CKM_SHA512_KEY_DERIVATION + +CKM_SSL3_PRE_MASTER_KEY_GEN +CKM_SSL3_MASTER_KEY_DERIVE +CKM_SSL3_KEY_AND_MAC_DERIVE +CKM_SSL3_MASTER_KEY_DERIVE_DH +CKM_TLS_PRE_MASTER_KEY_GEN +CKM_TLS_MASTER_KEY_DERIVE +CKM_TLS_KEY_AND_MAC_DERIVE +CKM_TLS_MASTER_KEY_DERIVE_DH +.fi +.in -2 + +.sp +.LP +Each of the following types of key objects has certain token-specific +attributes that are set to true by default as a result of object creation, +key/key pair generation, and key derivation. +.sp +.ne 2 +.na +\fBPublic key object\fR +.ad +.RS 22n +\fBCKA_ENCRYPT\fR, \fBCKA_VERIFY\fR, \fBCKA_VERIFY_RECOVER\fR +.RE + +.sp +.ne 2 +.na +\fBPrivate key object\fR +.ad +.RS 22n +\fBCKA_DECRYPT\fR, \fBCKA_SIGN\fR, \fBCKA_SIGN_RECOVER\fR, +\fBCKA_EXTRACTABLE\fR +.RE + +.sp +.ne 2 +.na +\fBSecret key object\fR +.ad +.RS 22n +\fBCKA_ENCRYPT\fR, \fBCKA_DECRYPT\fR, \fBCKA_SIGN\fR, \fBCKA_VERIFY\fR, +\fBCKA_EXTRACTABLE\fR +.RE + +.sp +.LP +The following certificate objects are supported: +.sp +.ne 2 +.na +\fB\fBCKC_X_509\fR\fR +.ad +.RS 23n +For \fBCKC_X_509\fR certificate objects, the following attributes are +supported: \fBCKA_SUBJECT\fR, \fBCKA_VALUE\fR, \fBCKA_LABEL\fR, \fBCKA_ID\fR, +\fBCKA_ISSUER\fR, \fBCKA_SERIAL_NUMBER\fR, and \fBCKA_CERTIFICATE_TYPE\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBCKC_X_509_ATTR_CERT\fR\fR +.ad +.RS 23n +For \fBCKC_X_509_ATTR_CERT\fR certificate objects, the following attributes are +supported: \fBCKA_OWNER\fR, \fBCKA_VALUE, CKA_LABEL\fR, +\fBCKA_SERIAL_NUMBER\fR, \fBCKA_AC_ISSUER\fR, \fBCKA_ATTR_TYPES\fR, and +\fBCKA_CERTIFICATE_TYPE\fR. +.RE + +.sp +.LP +The search operation of objects matching the template is performed at +\fBC_FindObjectsInit\fR. The matched objects are cached for subsequent +\fBC_FindObjects\fR operations. +.sp +.LP +The \fBpkcs11_softtoken.so\fR object provides a filesystem-based persistent +token object store for storing token objects. The default location of the token +object store is the user's home directory returned by \fBgetpwuid_r()\fR. The +user can override the default location by using the \fB${SOFTTOKEN_DIR}\fR +environment variable. +.sp +.LP +If the token object store has never been initialized, the \fBC_Login()\fR +function might return \fBCKR_OK\fR but the user will not be able to create, +generate, derive or find any private token object and receives +\fBCKR_PIN_EXPIRED\fR. +.sp +.LP +The user must use the \fBpktool\fR(1) \fBsetpin\fR command with the default +passphrase "changeme" as the old passphrase to change the passphrase of the +object store. This action is needed to initialize and set the passphrase to a +newly created token object store. +.sp +.LP +After logging into object store with the new passphrase that was set by the +\fBpktool setpin\fR command, the user can create and store the private token +object in this newly created object store. Until the token object store is +initialized by \fBsetpin\fR, the \fBC_Login()\fR function is allowed, but all +attempts by the user to create, generate, derive or find any private token +object fails with a \fBCKR_PIN_EXPIRED\fR error. +.sp +.LP +The PIN provided for \fBC_Login()\fR and \fBC_SetPIN()\fR functions can be any +string of characters with lengths between 1 and 256 and no embedded nulls. +.SH RETURN VALUES +.sp +.LP +The return values for each of the implemented functions are defined and listed +in the RSA PKCS#11 v2.20 specification. See http://www.rsasecurity.com +.SH FILES +.sp +.ne 2 +.na +\fB\fB\fIuser_home_directory\fR/.sunw/pkcs11_softtoken\fR\fR +.ad +.sp .6 +.RS 4n +user's default token object store +.RE + +.sp +.ne 2 +.na +\fB\fB${SOFTTOKEN_DIR}/pkcs11_softtoken\fR\fR +.ad +.sp .6 +.RS 4n +alternate token object store +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT-Level T{ +MT-Safe with exceptions. See section 6.5.2 of RSA PKCS#11 v2.20. +T} +_ +Standard PKCS#11 v2.20 +.TE + +.SH SEE ALSO +.sp +.LP +.BR pktool (1), +.BR libpkcs11 (3LIB), +.BR attributes (7), +.BR pkcs11_kernel (7), +.BR cryptoadm (8) +.sp +.LP +RSA PKCS#11 v2.20 http://www.rsasecurity.com diff --git a/usr/src/man/man7/pkcs11_tpm.7 b/usr/src/man/man7/pkcs11_tpm.7 new file mode 100644 index 0000000000..3d67400906 --- /dev/null +++ b/usr/src/man/man7/pkcs11_tpm.7 @@ -0,0 +1,275 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH PKCS11_TPM 7 "May 13, 2017" +.SH NAME +pkcs11_tpm \- RSA PKCS#11 token for Trusted Platform Modules (TPM) +.SH SYNOPSIS +.LP +.nf +/usr/lib/security/pkcs11_tpm.so +.fi + +.LP +.nf +/usr/lib/security/64/pkcs11_tpm.so +.fi + +.SH DESCRIPTION +.LP +The \fBpkcs11_tpm.so\fR object implements the RSA PKCS#11 v2.20 specification +using Trusted Computing Group protocols to talk to a TPM security device. This +provider implements the PKCS#11 specification and uses the TCG Software Stack +(TSS) APIs in the \fBtrousers\fR package. +.sp +.LP +Application developers should link to \fBlibpkcs11.so.1\fR rather than link +directly with \fBpkcs11_tpm.so\fR. See \fBlibpkcs11\fR(3LIB). +.sp +.LP +The following cryptographic algorithms are implemented: \fBRSA\fR, \fBSHA1\fR, +and \fBMD5\fR. +.sp +.LP +All of the standard PKCS#11 functions listed in \fBlibpkcs11\fR(3LIB) are +implemented except for the following: +.sp +.in +2 +.nf +C_EncryptUpdate +C_EncryptFinal +C_DecryptUpdate +C_DecryptFinal +C_DigestEncryptUpdate +C_DecryptDigestUpdate +C_SignEncryptUpdate +C_DecryptVerifyUpdate +C_GetFunctionStatus +C_CancelFunction +C_WaitForSlotEvent +C_GenerateKey +C_DeriveKey +.fi +.in -2 +.sp + +.sp +.LP +The following RSA PKCS#11 v2.20 mechanisms are supported: +.sp +.in +2 +.nf +CKM_RSA_PKCS_KEY_PAIR_GEN +CKM_RSA_PKCS +CKM_RSA_PKCS_OAEP +CKM_RSA_X_509 +CKM_MD5_RSA_PKCS +CKM_SHA1_RSA_PKCS +CKM_SHA_1 +CKM_SHA_1_HMAC +CKM_SHA_1_HMAC_GENERAL +CKM_MD5 +CKM_MD5_HMAC +CKM_MD5_HMAC_GENERAL +.fi +.in -2 +.sp + +.SS "Per-User Initialization" +.LP +The \fBpkcs11_tpm\fR provider can only be used on a system which has a TPM +device and which also has the \fBtrousers\fR package installed. If those +prerequisites are met, users can create their own private tokens using +\fBpktool\fR(1), which will allow them to perform operations using the TPM +device and protect their private data with TPM-protected keys. +.sp +.LP +To prepare and initialize a user's TPM token, the following steps must be +performed: +.RS +4 +.TP +1. +Initialize the token. +.RE +.RS +4 +.TP +2. +Set the SO (security officer) PIN. +.RE +.RS +4 +.TP +3. +Set the user's unique PIN. +.RE +.sp +.LP +Initializing the token is done using the \fBpktool\fR(1) command as follows: +.sp +.in +2 +.nf +$ \fBpktool inittoken currlabel=TPM newlabel=tpm/myname\fR +.fi +.in -2 +.sp + +.RS +4 +.TP +.ie t \(bu +.el o +By default, an uninitialized TPM is recognized by the name \fBTPM\fR. When a +user initializes their own private token, it can either be renamed to something +else (for example, \fBtpm/joeuser\fR) or kept as \fBTPM\fR (in which case the +\fBnewlabel\fR argument would be omitted). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The user will have to supply the default SO PIN before being able to initialize +his or her token. The default SO PIN is \fB87654321\fR. It is changed in step +2, above. +.RE +.sp +.LP +Once the token is initialized, the SO and user PINs must be changed from the +default values. Again, \fBpktool\fR(1) is used to change these PIN values. +.sp +.LP +Changing the SO PIN: +.sp +.in +2 +.nf +$ \fBpktool setpin token=tpm/joeuser so\fR +.fi +.in -2 +.sp + +.sp +.LP +The \fBso\fR option indicates that this "setpin" operation is to change the SO +PIN and must be present. The user must then enter the default SO PIN +(\fB87654321\fR) and then enter (and confirm) a new PIN. +.sp +.LP +Once the SO PIN is reset from the default, the user's unique PIN must also be +changed. +.sp +.LP +Changing the user's PIN: +.sp +.in +2 +.nf +$ \fBpktool setpin token=tmp/joeuser\fR +.fi +.in -2 +.sp + +.sp +.LP +The default PIN for a non-SO user is \fB12345678\fR. The user must enter the +default PIN and then enter (and confirm) a new, unique PIN. +.sp +.LP +The PIN provided for the \fBpktool\fR \fBsetpin\fR operation or by calling +\fBC_Login()\fR and \fBC_SetPIN()\fR functions can be any string of characters +with a length between 1 and 256 and no embedded nulls. +.SS "Accessing the Token" +.LP +After a user initializes their token, they can begin using it with +\fBpktool\fR(1) or by writing PKCS11 applications and locating the token using +the name created above (\fBtpm/joeuser\fR in the examples above). +.sp +.LP +Examples: +.sp +.in +2 +.nf +$ \fBpktool gencert token=tpm/joeuser -i\fR +$ \fBpktool list token=tpm/joeuser\fR +.fi +.in -2 +.sp + +.SS "Notes" +.LP +\fBpkcs11_tpm.so\fR provides object storage in a filesystem-specific token +object storage area. Private objects are protected by encryption with private +keys and can only be decrypted by loading the token's private key into the TPM +and performing the decryption entirely in the TPM. The user's private key is +generated by the TPM when the user sets their personal PIN (see above). The +keys for both the SO and users are stored in the TSS persistent storage +database and are referenced by a unique UUID value. All user tokens have a +unique SO key and unique user key so that the PINs for one user's token will +not unlock private data in another user's token on the same machine. +.sp +.LP +Each TPM is unique and the token keys created on one TPM may not be used on +another TPM. The \fBpkcs11_tpm.so\fR token data is all managed on the system +where the TPM resides and may not be moved to other systems. If the TPM is +reset and the SRK (Storage Root Key) is changed, all of the keys previously +generated for that TPM will no longer be valid. +.sp +.LP +\fBpkcs11_tpm.so\fR creates a private workspace to manage administrative files +for each token created. By default, this area is created as +\fB/var/tpm/pkcs11/$USERNAME\fR. However, users may override this by setting +the \fBPKCS11_TPM_DIR\fR environment variable prior to initializing or using +the token. +.SH RETURN VALUES +.LP +The return values for each of the implemented functions are defined and listed +in the RSA PKCS#11 v2.20 specification. See \fBhttp://www.rsasecurity.com\fR. +.SH FILES +.ne 2 +.na +\fB\fB/var/tpm/pkcs11/USERNAME\fR\fR +.ad +.sp .6 +.RS 4n +User's default token object store. +.RE + +.sp +.ne 2 +.na +\fB\fB${PKCS11_TPM_DIR}\fR\fR +.ad +.sp .6 +.RS 4n +Alternate token object store. +.RE + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT-Level MT-Safe with Exceptions (see below) +_ +Standard PKCS#11 v2.20 +.TE + +.sp +.LP +Exceptions to MT-Safe attribute are documented in section 6.5.2 of RSA PKCS#11 +v2.20. +.SH SEE ALSO +.LP +.BR pktool (1), +.BR libpkcs11 (3LIB), +.BR attributes (7), +.BR cryptoadm (8) +.sp +.LP +TCG Software Stack (TSS) Specifications: \fBhttps://www.trustedcomputinggroup.org/specs/TSS\fR (as of the date of publication) diff --git a/usr/src/man/man7/privileges.7 b/usr/src/man/man7/privileges.7 new file mode 100644 index 0000000000..aade5c020c --- /dev/null +++ b/usr/src/man/man7/privileges.7 @@ -0,0 +1,1429 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2016, Joyent, Inc. All Rights Reserved. +.\" Copyright 2019 Peter Tribble +.\" 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 7 "Aug 26, 2019" +.SH NAME +privileges \- process privilege model +.SH DESCRIPTION +In illumos, software implements a set of privileges that provide fine-grained +control over the actions of processes. The possession of a certain privilege +allows a process to perform a specific set of restricted operations. +.sp +.LP +The change to a primarily privilege-based security model in the +operating system gives developers an opportunity to restrict processes to those +privileged operations actually needed instead of all (super-user) or no +privileges (non-zero UIDs). Additionally, a set of previously unrestricted +operations now requires a privilege; these privileges are dubbed the "basic" +privileges and are by default given to all processes. +.sp +.LP +Taken together, all defined privileges with the exception of the "basic" +privileges compose the set of privileges that are traditionally associated with +the root user. The "basic" privileges are "privileges" unprivileged processes +were accustomed to having. +.sp +.LP +The defined privileges are: +.sp +.ne 2 +.na +\fB\fBPRIV_CONTRACT_EVENT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to request reliable delivery of events to an event endpoint. +.sp +Allow a process to include events in the critical event set term of a template +which could be generated in volume by the user. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_CONTRACT_IDENTITY\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process to set the service FMRI value of a process contract template. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_CONTRACT_OBSERVER\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to observe contract events generated by contracts created and +owned by users other than the process's effective user ID. +.sp +Allow a process to open contract event endpoints belonging to contracts created +and owned by users other than the process's effective user ID. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_CPC_CPU\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to access per-CPU hardware performance counters. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_DTRACE_KERNEL\fR\fR +.ad +.sp .6 +.RS 4n +Allow DTrace kernel-level tracing. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_DTRACE_PROC\fR\fR +.ad +.sp .6 +.RS 4n +Allow DTrace process-level tracing. Allow process-level tracing probes to be +placed and enabled in processes to which the user has permissions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_DTRACE_USER\fR\fR +.ad +.sp .6 +.RS 4n +Allow DTrace user-level tracing. Allow use of the syscall and profile DTrace +providers to examine processes to which the user has permissions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_CHOWN\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to change a file's owner user ID. Allow a process to change a +file's group ID to one other than the process's effective group ID or one of +the process's supplemental group IDs. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_CHOWN_SELF\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to give away its files. A process with this privilege runs as +if {\fB_POSIX_CHOWN_RESTRICTED\fR} is not in effect. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_DAC_EXECUTE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to execute an executable file whose permission bits or ACL +would otherwise disallow the process execute permission. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_DAC_READ\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to read a file or directory whose permission bits or ACL would +otherwise disallow the process read permission. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_DAC_SEARCH\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to search a directory whose permission bits or ACL would not +otherwise allow the process search permission. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_DAC_WRITE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to write a file or directory whose permission bits or ACL do +not allow the process write permission. All privileges are required to write +files owned by UID 0 in the absence of an effective UID of 0. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_DOWNGRADE_SL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set the sensitivity label of a file or directory to a +sensitivity label that does not dominate the existing sensitivity label. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_FLAG_SET\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process to set immutable, nounlink or appendonly file attributes. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_LINK_ANY\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to create hardlinks to files owned by a UID different from the +process's effective UID. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_OWNER\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process that is not the owner of a file to modify that file's access +and modification times. Allow a process that is not the owner of a directory to +modify that directory's access and modification times. Allow a process that is +not the owner of a file or directory to remove or rename a file or directory +whose parent directory has the "save text image after execution" (sticky) bit +set. Allow a process that is not the owner of a file to mount a \fBnamefs\fR +upon that file. Allow a process that is not the owner of a file or directory to +modify that file's or directory's permission bits or ACL. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_READ\fR\fR +.ad +.sp .6 +.RS 4n +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 +.ne 2 +.na +\fB\fBPRIV_FILE_SETID\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to change the ownership of a file or write to a file without +the set-user-ID and set-group-ID bits being cleared. Allow a process to set the +set-group-ID bit on a file or directory whose group is not the process's +effective group or one of the process's supplemental groups. Allow a process to +set the set-user-ID bit on a file with different ownership in the presence of +\fBPRIV_FILE_OWNER\fR. Additional restrictions apply when creating or modifying +a setuid 0 file. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_UPGRADE_SL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set the sensitivity label of a file or directory to a +sensitivity label that dominates the existing sensitivity label. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_FILE_WRITE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to open objects in the filesystem 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 +.ne 2 +.na +\fB\fBPRIV_GRAPHICS_ACCESS\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to make privileged ioctls to graphics devices. Typically only +an xserver process needs to have this privilege. A process with this privilege +is also allowed to perform privileged graphics device mappings. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_GRAPHICS_MAP\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to perform privileged mappings through a graphics device. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_IPC_DAC_READ\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to read a System V IPC Message Queue, Semaphore Set, or Shared +Memory Segment whose permission bits would not otherwise allow the process read +permission. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_IPC_DAC_WRITE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to write a System V IPC Message Queue, Semaphore Set, or Shared +Memory Segment whose permission bits would not otherwise allow the process +write permission. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_IPC_OWNER\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process that is not the owner of a System V IPC Message Queue, +Semaphore Set, or Shared Memory Segment to remove, change ownership of, or +change permission bits of the Message Queue, Semaphore Set, or Shared Memory +Segment. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_ACCESS\fR\fR +.ad +.sp .6 +.RS 4n +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 +.ne 2 +.na +\fB\fBPRIV_NET_BINDMLP\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to bind to a port that is configured as a multi-level port +(MLP) for the process's zone. This privilege applies to both shared address and +zone-specific address MLPs. See \fBtnzonecfg\fR(\fB4\fR) from the Trusted +Extensions manual pages for information on configuring MLP ports. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_ICMPACCESS\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to send and receive ICMP packets. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_MAC_AWARE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set the \fBNET_MAC_AWARE\fR process flag by using +\fBsetpflags\fR(2). This privilege also allows a process to set the +\fBSO_MAC_EXEMPT\fR socket option by using \fBsetsockopt\fR(3SOCKET). The +\fBNET_MAC_AWARE\fR process flag and the \fBSO_MAC_EXEMPT\fR socket option both +allow a local process to communicate with an unlabeled peer if the local +process's label dominates the peer's default label, or if the local process +runs in the global zone. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_MAC_IMPLICIT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set \fBSO_MAC_IMPLICIT\fR option by using +\fBsetsockopt\fR(3SOCKET). This allows a privileged process to transmit +implicitly-labeled packets to a peer. +.sp +This privilege is interpreted only if the system is configured with +Trusted Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_OBSERVABILITY\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to open a device for just receiving network traffic, sending +traffic is disallowed. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_PRIVADDR\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to bind to a privileged port number. The privilege port numbers +are 1-1023 (the traditional UNIX privileged ports) as well as those ports +marked as "\fBudp/tcp_extra_priv_ports\fR" with the exception of the ports +reserved for use by NFS and SMB. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_NET_RAWACCESS\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to have direct access to the network layer. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_AUDIT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to generate audit records. Allow a process to get its own audit +pre-selection information. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_CHROOT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to change its root directory. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_CLOCK_HIGHRES\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to use high resolution timers with very small time values. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_EXEC\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to call \fBexec\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_FORK\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to call \fBfork\fR(2), \fBfork1\fR(2), or \fBvfork\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_INFO\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to examine the status of processes other than those to which it +can send signals. Processes that cannot be examined cannot be seen in +\fB/proc\fR and appear not to exist. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_LOCK_MEMORY\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to lock pages in physical memory. +.RE + +.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 +.RS 4n +Allow a process to send signals to other processes and inspect and modify the +process state in other processes, regardless of ownership. When modifying +another process, additional restrictions apply: the effective privilege set of +the attaching process must be a superset of the target process's effective, +permitted, and inheritable sets; the limit set must be a superset of the +target's limit set; if the target process has any UID set to 0 all privilege +must be asserted unless the effective UID is 0. Allow a process to bind +arbitrary processes to CPUs. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_PRIOUP\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to elevate its priority above its current level. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_PRIOCNTL\fR\fR +.ad +.sp .6 +.RS 4n +Allows all that PRIV_PROC_PRIOUP allows. +Allow a process to change its scheduling class to any scheduling class, +including the RT class. +.RE + +.sp +.ne 2 +.na +\fBPRIV_PROC_SECFLAGS\fR +.ad +.sp .6 +.RS 4n +Allow a process to manipulate the secflags of processes (subject to, +additionally, the ability to signal that process). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_SESSION\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to send signals or trace processes outside its session. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_SETID\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set its UIDs at will, assuming UID 0 requires all privileges +to be asserted. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_TASKID\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to assign a new task ID to the calling process. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_PROC_ZONE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to trace or send signals to processes in other zones. See +\fBzones\fR(7). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_ACCT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to enable and disable and manage accounting through +\fBacct\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_ADMIN\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to perform system administration tasks such as setting node and +domain name and managing \fBfmd\fR(8) and \fBnscd\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_AUDIT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to start the (kernel) audit daemon. Allow a process to view and +set audit state (audit user ID, audit terminal ID, audit sessions ID, audit +pre-selection mask). Allow a process to turn off and on auditing. Allow a +process to configure the audit parameters (cache and queue sizes, event to +class mappings, and policy options). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to perform various system configuration tasks. Allow +filesystem-specific administrative procedures, such as filesystem configuration +ioctls, quota calls, creation and deletion of snapshots, and manipulating the +PCFS bootsector. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_DEVICES\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to create device special files. Allow a process to successfully +call a kernel module that calls the kernel \fBdrv_priv\fR(9F) function to check +for allowed access. Allow a process to open the real console device directly. +Allow a process to open devices that have been exclusively opened. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_DL_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to configure a system's datalink interfaces. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_IP_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to configure a system's IP interfaces and routes. Allow a +process to configure network parameters for \fBTCP/IP\fR using \fBndd\fR. Allow +a process access to otherwise restricted \fBTCP/IP\fR information using +\fBndd\fR. Allow a process to configure \fBIPsec\fR. Allow a process to pop +anchored \fBSTREAM\fRs modules with matching \fBzoneid\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_IPC_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to increase the size of a System V IPC Message Queue buffer. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_IPTUN_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to configure IP tunnel links. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_LINKDIR\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to unlink and link directories. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_MOUNT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to mount and unmount filesystems that would otherwise be +restricted (that is, most filesystems except \fBnamefs\fR). Allow a process to +add and remove swap devices. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_NET_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to do all that \fBPRIV_SYS_IP_CONFIG\fR, +\fBPRIV_SYS_DL_CONFIG\fR, and \fBPRIV_SYS_PPP_CONFIG\fR allow, plus the +following: use the \fBrpcmod\fR STREAMS module and insert/remove STREAMS +modules on locations other than the top of the module stack. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_NFS\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to provide NFS service: start NFS kernel threads, perform NFS +locking operations, bind to NFS reserved ports: ports 2049 (\fBnfs\fR) and port +4045 (\fBlockd\fR). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_PPP_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to create, configure, and destroy PPP instances with pppd(8) +\fBpppd\fR(8) and control PPPoE plumbing with \fBsppptun\fR(8). +This privilege is granted by default to exclusive IP stack instance zones. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_RES_BIND\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process to bind processes to processor sets. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_RES_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allows all that PRIV_SYS_RES_BIND allows. +Allow a process to create and delete processor sets, assign CPUs to processor +sets and override the \fBPSET_NOESCAPE\fR property. Allow a process to change +the operational status of CPUs in the system using \fBp_online\fR(2). Allow a +process to configure filesystem quotas. Allow a process to configure resource +pools and bind processes to pools. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_RESOURCE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to exceed the resource limits imposed on it by +\fBsetrlimit\fR(2) and \fBsetrctl\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_SMB\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to provide NetBIOS or SMB services: start SMB kernel threads or +bind to NetBIOS or SMB reserved ports: ports 137, 138, 139 (NetBIOS) and 445 +(SMB). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_SUSER_COMPAT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to successfully call a third party loadable module that calls +the kernel \fBsuser()\fR function to check for allowed access. This privilege +exists only for third party loadable module compatibility and is not used by +illumos. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_TIME\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to manipulate system time using any of the appropriate system +calls: \fBstime\fR(2), \fBadjtime\fR(2), and \fBntp_adjtime\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_SYS_TRANS_LABEL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to translate labels that are not dominated by the process's +sensitivity label to and from an external string form. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_VIRT_MANAGE\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process to manage virtualized environments such as \fBxVM\fR(7). +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_COLORMAP\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to override colormap restrictions. +.sp +Allow a process to install or remove colormaps. +.sp +Allow a process to retrieve colormap cell entries allocated by other processes. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to configure or destroy resources that are permanently retained +by the X server. +.sp +Allow a process to use SetScreenSaver to set the screen saver timeout value +.sp +Allow a process to use ChangeHosts to modify the display access control list. +.sp +Allow a process to use GrabServer. +.sp +Allow a process to use the SetCloseDownMode request that can retain window, +pixmap, colormap, property, cursor, font, or graphic context resources. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_DAC_READ\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to read from a window resource that it does not own (has a +different user ID). +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_DAC_WRITE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to write to or create a window resource that it does not own +(has a different user ID). A newly created window property is created with the +window's user ID. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_DEVICES\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to perform operations on window input devices. +.sp +Allow a process to get and set keyboard and pointer controls. +.sp +Allow a process to modify pointer button and key mappings. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_DGA\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to use the direct graphics access (DGA) X protocol extensions. +Direct process access to the frame buffer is still required. Thus the process +must have MAC and DAC privileges that allow access to the frame buffer, or the +frame buffer must be allocated to the process. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_DOWNGRADE_SL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set the sensitivity label of a window resource to a +sensitivity label that does not dominate the existing sensitivity label. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_FONTPATH\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set a font path. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_MAC_READ\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to read from a window resource whose sensitivity label is not +equal to the process sensitivity label. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_MAC_WRITE\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to create a window resource whose sensitivity label is not +equal to the process sensitivity label. A newly created window property is +created with the window's sensitivity label. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_SELECTION\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to request inter-window data moves without the intervention of +the selection confirmer. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_WIN_UPGRADE_SL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to set the sensitivity label of a window resource to a +sensitivity label that dominates the existing sensitivity label. +.sp +This privilege is interpreted only if the system is configured with Trusted +Extensions. +.RE + +.sp +.ne 2 +.na +\fB\fBPRIV_XVM_CONTROL\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process access to the \fBxVM\fR(7) control devices for managing guest +domains and the hypervisor. This privilege is used only if booted into xVM on +x86 platforms. +.RE + +.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, +\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. +.sp +.LP +The privileges \fBPRIV_PROC_SETID\fR and \fBPRIV_PROC_AUDIT\fR must be present +in the Limit set (see below) of a process in order for set-uid root \fBexec\fRs +to be successful, that is, get an effective UID of 0 and additional privileges. +.sp +.LP +The privilege implementation in illumos extends the process credential with +four privilege sets: +.sp +.ne 2 +.na +\fBI, the inheritable set\fR +.ad +.RS 26n +The privileges inherited on \fBexec\fR. +.RE + +.sp +.ne 2 +.na +\fBP, the permitted set\fR +.ad +.RS 26n +The maximum set of privileges for the process. +.RE + +.sp +.ne 2 +.na +\fBE, the effective set\fR +.ad +.RS 26n +The privileges currently in effect. +.RE + +.sp +.ne 2 +.na +\fBL, the limit set\fR +.ad +.RS 26n +The upper bound of the privileges a process and its offspring can obtain. +Changes to L take effect on the next \fBexec\fR. +.RE + +.sp +.LP +The sets I, P and E are typically identical to the basic set of privileges for +unprivileged processes. The limit set is typically the full set of privileges. +.sp +.LP +Each process has a Privilege Awareness State (PAS) that can take the value PA +(privilege-aware) and NPA (not-PA). PAS is a transitional mechanism that allows +a choice between full compatibility with the old superuser model and completely +ignoring the effective UID. +.sp +.LP +To facilitate the discussion, we introduce the notion of "observed effective +set" (oE) and "observed permitted set" (oP) and the implementation sets iE and +iP. +.sp +.LP +A process becomes privilege-aware either by manipulating the effective, +permitted, or limit privilege sets through \fBsetppriv\fR(2) or by using +\fBsetpflags\fR(2). In all cases, oE and oP are invariant in the process of +becoming privilege-aware. In the process of becoming privilege-aware, the +following assignments take place: +.sp +.in +2 +.nf +iE = oE +iP = oP +.fi +.in -2 + +.sp +.LP +When a process is privilege-aware, oE and oP are invariant under UID changes. +When a process is not privilege-aware, oE and oP are observed as follows: +.sp +.in +2 +.nf +oE = euid == 0 ? L : iE +oP = (euid == 0 || ruid == 0 || suid == 0) ? L : iP +.fi +.in -2 + +.sp +.LP +When a non-privilege-aware process has an effective UID of 0, it can exercise +the privileges contained in its limit set, the upper bound of its privileges. +If a non-privilege-aware process has any of the UIDs 0, it appears to be +capable of potentially exercising all privileges in L. +.sp +.LP +It is possible for a process to return to the non-privilege aware state using +\fBsetpflags()\fR. The kernel always attempts this on \fBexec\fR(2). This +operation is permitted only if the following conditions are met: +.RS +4 +.TP +.ie t \(bu +.el o +If any of the UIDs is equal to 0, P must be equal to L. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the effective UID is equal to 0, E must be equal to L. +.RE +.sp +.LP +When a process gives up privilege awareness, the following assignments take +place: +.sp +.in +2 +.nf +if (euid == 0) iE = L & I +if (any uid == 0) iP = L & I +.fi +.in -2 + +.sp +.LP +The privileges obtained when not having a UID of \fB0\fR are the inheritable +set of the process restricted by the limit set. +.sp +.LP +Only privileges in the process's (observed) effective privilege set allow the +process to perform restricted operations. A process can use any of the +privilege manipulation functions to add or remove privileges from the privilege +sets. Privileges can be removed always. Only privileges found in the permitted +set can be added to the effective and inheritable set. The limit set cannot +grow. The inheritable set can be larger than the permitted set. +.sp +.LP +When a process performs an \fBexec\fR(2), the kernel first tries to relinquish +privilege awareness before making the following privilege set modifications: +.sp +.in +2 +.nf +E' = P' = I' = L & I +L is unchanged +.fi +.in -2 + +.sp +.LP +If a process has not manipulated its privileges, the privilege sets effectively +remain the same, as E, P and I are already identical. +.sp +.LP +The limit set is enforced at \fBexec\fR time. +.sp +.LP +To run a non-privilege-aware application in a backward-compatible manner, a +privilege-aware application should start the non-privilege-aware application +with I=basic. +.sp +.LP +For most privileges, absence of the privilege simply results in a failure. In +some instances, the absence of a privilege can cause system calls to behave +differently. In other instances, the removal of a privilege can force a set-uid +application to seriously malfunction. Privileges of this type are considered +"unsafe". When a process is lacking any of the unsafe privileges from its limit +set, the system does not honor the set-uid bit of set-uid root applications. +The following unsafe privileges have been identified: \fBproc_setid\fR, +\fBsys_resource\fR and \fBproc_audit\fR. +.SS "Privilege Escalation" +In certain circumstances, a single privilege could lead to a process gaining +one or more additional privileges that were not explicitly granted to that +process. To prevent such an escalation of privileges, the security policy +requires explicit permission for those additional privileges. +.sp +.LP +Common examples of escalation are those mechanisms that allow modification of +system resources through "raw" interfaces; for example, changing kernel data +structures through \fB/dev/kmem\fR or changing files through \fB/dev/dsk/*\fR. +Escalation also occurs when a process controls processes with more privileges +than the controlling process. A special case of this is manipulating or +creating objects owned by UID 0 or trying to obtain UID 0 using +\fBsetuid\fR(2). The special treatment of UID 0 is needed because the UID 0 +owns all system configuration files and ordinary file protection mechanisms +allow processes with UID 0 to modify the system configuration. With appropriate +file modifications, a given process running with an effective UID of 0 can gain +all privileges. +.sp +.LP +In situations where a process might obtain UID 0, the security policy requires +additional privileges, up to the full set of privileges. Such restrictions +could be relaxed or removed at such time as additional mechanisms for +protection of system files became available. There are no such mechanisms in +the current release. +.sp +.LP +The use of UID 0 processes should be limited as much as possible. They should +be replaced with programs running under a different UID but with exactly the +privileges they need. +.sp +.LP +Daemons that never need to \fBexec\fR subprocesses should remove the +\fBPRIV_PROC_EXEC\fR privilege from their permitted and limit sets. +.SS "Assigned Privileges and Safeguards" +When privileges are assigned to a user, the system administrator could give +that user more powers than intended. The administrator should consider whether +safeguards are needed. For example, if the \fBPRIV_PROC_LOCK_MEMORY\fR +privilege is given to a user, the administrator should consider setting the +\fBproject.max-locked-memory\fR resource control as well, to prevent that user +from locking all memory. +.SS "Privilege Debugging" +When a system call fails with a permission error, it is not always immediately +obvious what caused the problem. To debug such a problem, you can use a tool +called \fBprivilege debugging\fR. When privilege debugging is enabled for a +process, the kernel reports missing privileges on the controlling terminal of +the process. (Enable debugging for a process with the \fB-D\fR option of +\fBppriv\fR(1).) Additionally, the administrator can enable system-wide +privilege debugging by setting the \fBsystem\fR(5) variable \fBpriv_debug\fR +using: +.sp +.in +2 +.nf +set priv_debug = 1 +.fi +.in -2 + +.sp +.LP +On a running system, you can use \fBmdb\fR(1) to change this variable. +.SS "Privilege Administration" +Use \fBusermod\fR(8) or \fBrolemod\fR(8) +to assign privileges to or modify privileges for, respectively, a user or a +role. Use \fBppriv\fR(1) to enumerate the privileges supported on a system and +\fBtruss\fR(1) to determine which privileges a program requires. +.SH SEE ALSO +.BR mdb (1), +.BR ppriv (1), +.BR Intro (2), +.BR access (2), +.BR acct (2), +.BR acl (2), +.BR adjtime (2), +.BR audit (2), +.BR auditon (2), +.BR chmod (2), +.BR chown (2), +.BR chroot (2), +.BR creat (2), +.BR exec (2), +.BR fcntl (2), +.BR fork (2), +.BR fpathconf (2), +.BR getacct (2), +.BR getpflags (2), +.BR getppriv (2), +.BR getsid (2), +.BR kill (2), +.BR link (2), +.BR memcntl (2), +.BR mknod (2), +.BR mount (2), +.BR msgctl (2), +.BR nice (2), +.BR ntp_adjtime (2), +.BR open (2), +.BR p_online (2), +.BR priocntl (2), +.BR priocntlset (2), +.BR processor_bind (2), +.BR pset_bind (2), +.BR pset_create (2), +.BR readlink (2), +.BR resolvepath (2), +.BR rmdir (2), +.BR semctl (2), +.BR setauid (2), +.BR setegid (2), +.BR seteuid (2), +.BR setgid (2), +.BR setgroups (2), +.BR setpflags (2), +.BR setppriv (2), +.BR setrctl (2), +.BR setregid (2), +.BR setreuid (2), +.BR setrlimit (2), +.BR settaskid (2), +.BR setuid (2), +.BR shmctl (2), +.BR shmget (2), +.BR shmop (2), +.BR sigsend (2), +.BR stat (2), +.BR statvfs (2), +.BR stime (2), +.BR swapctl (2), +.BR sysinfo (2), +.BR uadmin (2), +.BR ulimit (2), +.BR umount (2), +.BR unlink (2), +.BR utime (2), +.BR utimes (2), +.BR door_ucred (3C), +.BR priv_addset (3C), +.BR priv_getbyname (3C), +.BR priv_getbynum (3C), +.BR priv_set (3C), +.BR priv_set_to_str (3C), +.BR priv_str_to_set (3C), +.BR timer_create (3C), +.BR ucred_get (3C), +.BR t_bind (3NSL), +.BR bind (3SOCKET), +.BR socket (3SOCKET), +.BR exec_attr (5), +.BR proc (5), +.BR system (5), +.BR user_attr (5), +.BR xVM (7), +.BR add_drv (8), +.BR ifconfig (8), +.BR lockd (8), +.BR nfsd (8), +.BR pppd (8), +.BR rem_drv (8), +.BR smbd (8), +.BR sppptun (8), +.BR update_drv (8), +.BR ddi_cred (9F), +.BR drv_priv (9F), +.BR priv_getbyname (9F), +.BR priv_policy (9F), +.BR priv_policy_choice (9F), +.BR priv_policy_only (9F) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man7/prof.7 b/usr/src/man/man7/prof.7 new file mode 100644 index 0000000000..966f7fe37c --- /dev/null +++ b/usr/src/man/man7/prof.7 @@ -0,0 +1,73 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 PROF 7 "Jul 3, 1990" +.SH NAME +prof \- profile within a function +.SH SYNOPSIS +.LP +.nf +#define MARK +#include <prof.h> + +\fBvoid\fR \fBMARK\fR(\fB\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBMARK\fR introduces a mark called \fIname\fR that is treated the same as a +function entry point. Execution of the mark adds to a counter for that mark, +and program-counter time spent is accounted to the immediately preceding mark +or to the function if there are no preceding marks within the active function. +.sp +.LP +\fIname\fR may be any combination of letters, numbers, or underscores. Each +\fIname\fR in a single compilation must be unique, but may be the same as any +ordinary program symbol. +.sp +.LP +For marks to be effective, the symbol \fBMARK\fR must be defined before the +header \fBprof.h\fR is included, either by a preprocessor directive as in the +synopsis, or by a command line argument: +.sp +.LP +\fBcc -p -DMARK work.c\fR +.sp +.LP +If \fBMARK\fR is not defined, the \fBMARK(\fR\fIname\fR\fB)\fR statements may +be left in the source files containing them and are ignored. \fBprof -g\fR +must be used to get information on all labels. +.SH EXAMPLES +.sp +.LP +In this example, marks can be used to determine how much time is spent in each +loop. Unless this example is compiled with \fBMARK\fR defined on the command +line, the marks are ignored. +.sp +.in +2 +.nf +#include <prof.h> +work( ) +{ + int i, j; + ... + MARK(loop1); + for (i = 0; i < 2000; i++) { + ... + } + MARK(loop2); + for (j = 0; j < 2000; j++) { + ... + } +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +.BR profil (2), +.BR monitor (3C) diff --git a/usr/src/man/man7/pxeboot.7 b/usr/src/man/man7/pxeboot.7 new file mode 100644 index 0000000000..4c58c4de8c --- /dev/null +++ b/usr/src/man/man7/pxeboot.7 @@ -0,0 +1,148 @@ +.\" Copyright (c) 1999 Doug White +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Copyright 2018 OmniOS Community Edition (OmniOSce) Association. +.\" +.Dd Apr 13, 2018 +.Dt PXEBOOT 7 +.Os +.Sh NAME +.Nm pxeboot +.Nd Preboot Execution Environment (PXE) bootloader +.Sh DESCRIPTION +The +.Nm +bootloader is a modified version of the system third-stage bootstrap +.Xr loader 7 +configured to run under Intel's Preboot Execution Environment (PXE) system. +PXE is a form of smart boot ROM, built into Ethernet cards, and +Ethernet-equipped motherboards. +PXE supports DHCP configuration and provides low-level NIC access services. +.Pp +The DHCP client will set a DHCP user class named +.Va illumos +to allow flexible configuration of the DHCP server. +.Pp +The +.Nm +bootloader retrieves the kernel, modules, +and other files either via NFS over UDP or by TFTP, +selectable through DHCP options. +.Pp +The +.Nm +binary is loaded just like any other boot file, +by specifying it in the DHCP server's configuration file. +Below is a sample configuration for the ISC DHCP server: +.Bd -literal -offset indent +option domain-name "example.com"; +option routers 10.0.0.1; +option subnet-mask 255.255.255.0; +option broadcast-address 10.0.0.255; +option domain-name-servers 10.0.0.1; +server-name "DHCPserver"; +server-identifier 10.0.0.1; + +default-lease-time 120; +max-lease-time 120; + +subnet 10.0.0.0 netmask 255.255.255.0 { + filename "pxeboot"; + range 10.0.0.10 10.0.0.254; + if exists user-class and option user-class ~~ "illumos" { + option root-path "tftp://10.0.0.1/illumos"; + } +} + +.Ed +.Pp +.Nm +recognizes +.Va next-server +and +.Va option root-path +directives as the server and path to NFS mount for file requests, +respectively, or the server to make TFTP requests to. +Note that +.Nm +expects to fetch +.Pa /boot/loader.rc +from the specified server before loading any other files. +.Pp +Valid +.Cm option Va root-path +syntax is +.Bd -literal -offset indent +[<scheme>://][<ip-address>/]<path> +.Ed +.Pp +\&...where +.Qq scheme +is either +.Qq nfs +or +.Qq tftp , +.Qq ip-address +is the address of the server, and +.Qq path +is the path to the root filesystem on the server. +If +.Qq scheme +is not specified, +.Nm +defaults to using NFS if the +.Va root-path +variable is in the +.Qq Pa ip-address Ns :/ Ns Pa path +form, otherwise TFTP is used. +If no +.Va root-path +option is set in the DHCP response, +.Nm +defaults to using TFTP. +.Pp +.Nm +defaults to a conservative 1024 byte NFS data packet size. +This may be changed by setting the +.Va nfs.read_size +variable in +.Pa /boot/loader.conf . +Valid values range from 1024 to 16384 bytes. +.Pp +TFTP block size can be controlled by setting the +.Va tftp.blksize +variable in +.Pa /boot/loader.conf . +Valid values range from 8 to 9008 bytes. +.Pp +In all other respects, +.Nm +acts just like +.Xr loader 7 . +.Pp +For further information on Intel's PXE specifications and Wired for +Management (WfM) systems, see +.Li http://www.intel.com/design/archives/wfm/ . +.Sh SEE ALSO +.Xr loader 7 diff --git a/usr/src/man/man7/rbac.7 b/usr/src/man/man7/rbac.7 new file mode 100644 index 0000000000..3e7f72e666 --- /dev/null +++ b/usr/src/man/man7/rbac.7 @@ -0,0 +1,242 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH RBAC 7 "Jul 15, 2003" +.SH NAME +rbac, RBAC \- role-based access control +.SH DESCRIPTION +.sp +.LP +The addition of role-based access control (RBAC) to the Solaris operating +environment gives developers the opportunity to deliver fine-grained security +in new and modified applications. RBAC is an alternative to the all-or-nothing +security model of traditional superuser-based systems. With RBAC, an +administrator can assign privileged functions to specific user accounts (or +special accounts called roles). +.sp +.LP +There are two ways to give applications privileges: +.RS +4 +.TP +1. +Administrators can assign special attributes such as setUID to application +binaries (executable files). +.RE +.RS +4 +.TP +2. +Administrators can assign special attributes such as setUID to applications +using execution profiles. +.RE +.sp +.LP +Special attribute assignment along with the theory behind RBAC is discussed in +detail in "Role Based Access Control" chapter of the \fISystem Administration +Guide: Security Services\fR. This chapter describes what authorizations are and +how to code for them. +.SS "Authorizations" +.sp +.LP +An authorization is a unique string that represents a user's right to perform +some operation or class of operations. Authorization definitions are stored in +a database called \fBauth_attr\fR(5). For programming authorization checks, +only the authorization name is significant. +.sp +.LP +Some typical values in an \fBauth_attr\fR database are shown below. +.sp +.in +2 +.nf +solaris.jobs.:::Cron and At Jobs::help=JobHeader.html +solaris.jobs.grant:::Delegate Cron & At \e + Administration::help=JobsGrant.html +solaris.jobs.admin:::Manage All Jobs::help=AuthJobsAdmin.html +solaris.jobs.user:::Cron & At User::help=JobsUser.html +.fi +.in -2 + +.sp +.LP +Authorization name strings ending with the \fBgrant\fR suffix are special +authorizations that give a user the ability to delegate authorizations with the +same prefix and functional area to other users. +.SS "Creating Authorization Checks" +.sp +.LP +To check authorizations, use the \fBchkauthattr\fR(3SECDB) library function, +which verifies whether or not a user has a given authorization. The synopsis +is: +.sp +.in +2 +.nf +int chkauthattr(const char *authname, const char *username); +.fi +.in -2 + +.sp +.LP +The \fBchkauthattr()\fR function checks the \fBpolicy.conf\fR(5), +\fBuser_attr\fR(5), and \fBprof_attr\fR(5) databases in order for a match to +the given authorization. +.sp +.LP +If you are modifying existing code that tests for root UID, you should find the +test in the code and replace it with the \fBchkauthattr()\fR function. A +typical root UID check is shown in the first code segment below. An +authorization check replacing it is shown in the second code segment; it uses +the \fBsolaris.jobs.admin\fR authorization and a variable called +\fBreal_login\fR representing the user. +.LP +\fBExample 1 \fRStandard root check +.sp +.in +2 +.nf +ruid = getuid(); + +if ((eflag || lflag || rflag) && argc == 1) { + if ((pwp = getpwnam(*argv)) == NULL) + crabort(INVALIDUSER); + + if (ruid != 0) { + if (pwp->pw_uid != ruid) + crabort(NOTROOT); + else + pp = getuser(ruid); + } else + pp = *argv++; +} else { +.fi +.in -2 + +.LP +\fBExample 2 \fRAuthorization check +.sp +.in +2 +.nf +ruid = getuid(); +if ((pwp = getpwuid(ruid)) == NULL) + crabort(INVALIDUSER); + +strcpy(real_login, pwp->pw_name); + +if ((eflag || lflag || rflag) && argc == 1) { + if ((pwp = getpwnam(*argv)) == NULL) + crabort(INVALIDUSER); + + if (!chkauthattr("solaris.jobs.admin", real_login)) { + if (pwp->pw_uid != ruid) + crabort(NOTROOT); + else + pp = getuser(ruid); + } else + pp = *argv++; +} else { +.fi +.in -2 + +.sp +.LP +For new applications, find an appropriate location for the test and use +\fBchkauthattr()\fR as shown above. Typically the authorization check makes an +access decision based on the identity of the calling user to determine if a +privileged action (for example, a system call) should be taken on behalf of +that user. +.sp +.LP +Applications that perform a test to restrict who can perform their +security-relevant functionality are generally \fBsetuid\fR to root. Programs +that were written prior to RBAC and that are only available to the root user +may not have such checks. In most cases, the kernel requires an effective user +\fBID\fR of root to override policy enforcement. Therefore, authorization +checking is most useful in programs that are \fBsetuid\fR to root. +.sp +.LP +For instance, if you want to write a program that allows authorized users to +set the system date, the command must be run with an effective user \fBID\fR of +root. Typically, this means that the file modes for the file would be +\fB-rwsr-xr-x\fR with root ownership. +.sp +.LP +Use caution, though, when making programs \fBsetuid\fR to root. For example, +the effective \fBUID\fR should be set to the real \fBUID\fR as early as +possible in the program's initialization function. The effective \fBUID\fR can +then be set back to root after the authorization check is performed and before +the system call is made. On return from the system call, the effective UID +should be set back to the real \fBUID\fR again to adhere to the principle of +least privilege. +.sp +.LP +Another consideration is that \fBLD_LIBRARY\fR path is ignored for setuid +programs (see SECURITY section in \fBld.so.1\fR(1)) and that shell scripts must +be modified to work properly when the effective and real \fBUID\fRs are +different. For example, the \fB-p\fR flag in Bourne shell is required to avoid +resetting the effective \fBUID\fR back to the real \fBUID\fR. +.sp +.LP +Using an effective \fBUID\fR of root instead of the real \fBUID\fR requires +extra care when writing shell scripts. For example, many shell scripts check to +see if the user is root before executing their functionality. With RBAC, these +shell scripts may be running with the effective \fBUID\fR of root and with a +real \fBUID\fR of a user or role. Thus, the shell script should check +\fBeuid\fR instead of \fBuid\fR. For example, +.sp +.in +2 +.nf +WHO=`id | cut -f1 -d" "` +if [ ! "$WHO" = "uid=0(root)" ] +then + echo "$PROG: ERROR: you must be super-user to run this script." + exit 1 +fi +.fi +.in -2 + +.sp +.LP +should be changed to +.sp +.in +2 +.nf +WHO=`/usr/xpg4/bin/id -n -u` +if [ ! "$WHO" = "root" ] +then + echo "$PROG: ERROR: you are not authorized to run this script." + exit 1 +fi +.fi +.in -2 + +.sp +.LP +Authorizations can be explicitly checked in shell scripts by checking the +output of the \fBauths\fR(1) utility. For example, +.sp +.in +2 +.nf +for auth in `auths | tr , " "` NOTFOUND +do + [ "$auth" = "solaris.date" ] && break # authorization found +done + +if [ "$auth" != "solaris.date" ] +then + echo >&2 "$PROG: ERROR: you are not authorized to set the date" + exit 1 +fi +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +.BR ld.so.1 (1), +.BR chkauthattr (3SECDB), +.BR auth_attr (5), +.BR policy.conf (5), +.BR prof_attr (5), +.BR user_attr (5) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man7/regex.7 b/usr/src/man/man7/regex.7 new file mode 100644 index 0000000000..99dd14afad --- /dev/null +++ b/usr/src/man/man7/regex.7 @@ -0,0 +1,1040 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Portions Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 2017 Nexenta Systems, Inc. +.\" +.Dd August 14, 2020 +.Dt REGEX 7 +.Os +.Sh NAME +.Nm regex +.Nd internationalized basic and extended regular expression matching +.Sh DESCRIPTION +Regular Expressions +.Pq REs +provide a mechanism to select specific strings from a set of character strings. +The Internationalized Regular Expressions described below differ from the Simple +Regular Expressions described on the +.Xr regexp 7 +manual page in the following ways: +.Bl -bullet +.It +both Basic and Extended Regular Expressions are supported +.It +the Internationalization features -- character class, equivalence class, and +multi-character collation -- are supported. +.El +.Pp +The Basic Regular Expression +.Pq BRE +notation and construction rules described in the +.Sx BASIC REGULAR EXPRESSIONS +section apply to most utilities supporting regular expressions. +Some utilities, instead, support the Extended Regular Expressions +.Pq ERE +described in the +.Sx EXTENDED REGULAR EXPRESSIONS +section; any exceptions for both cases are noted in the descriptions of the +specific utilities using regular expressions. +Both BREs and EREs are supported by the Regular Expression Matching interfaces +.Xr regcomp 3C +and +.Xr regexec 3C . +.Sh BASIC REGULAR EXPRESSIONS +.Ss BREs Matching a Single Character +A BRE ordinary character, a special character preceded by a backslash, or a +period matches a single character. +A bracket expression matches a single character or a single collating element. +See +.Sx RE Bracket Expression , +below. +.Ss BRE Ordinary Characters +An ordinary character is a BRE that matches itself: any character in the +supported character set, except for the BRE special characters listed in +.Sx BRE Special Characters , +below. +.Pp +The interpretation of an ordinary character preceded by a backslash +.Pq Qq \e +is undefined, except for: +.Bl -enum +.It +the characters +.Qq \&) , +.Qq \&( , +.Qq { , +and +.Qq } +.It +the digits 1 to 9 inclusive +.Po see +.Sx BREs Matching Multiple Characters , +below +.Pc +.It +a character inside a bracket expression. +.El +.Ss BRE Special Characters +A BRE special character has special properties in certain contexts. +Outside those contexts, or when preceded by a backslash, such a character will +be a BRE that matches the special character itself. +The BRE special characters and the contexts in which they have their special +meaning are: +.Bl -tag -width Ds +.It Sy \&. \&[ \&\e +The period, left-bracket, and backslash are special except when used in a +bracket expression +.Po see +.Sx RE Bracket Expression , +below +.Pc . +An expression containing a +.Qq \&[ +that is not preceded by a backslash and is not part of a bracket expression +produces undefined results. +.It Sy * +The asterisk is special except when used: +.Bl -bullet +.It +in a bracket expression +.It +as the first character of an entire BRE +.Po after an initial +.Qq ^ , +if any +.Pc +.It +as the first character of a subexpression +.Po after an initial +.Qq ^ , +if any; see +.Sx BREs Matching Multiple Characters , +below +.Pc . +.El +.It Sy ^ +The circumflex is special when used: +.Bl -bullet +.It +as an anchor +.Po see +.Sx BRE Expression Anchoring , +below +.Pc . +.It +as the first character of a bracket expression +.Po see +.Sx RE Bracket Expression , +below +.Pc . +.El +.It Sy $ +The dollar sign is special when used as an anchor. +.El +.Ss Periods in BREs +A period +.Pq Qq \&. , +when used outside a bracket expression, is a BRE that matches any character in +the supported character set except NUL. +.Ss RE Bracket Expression +A bracket expression +.Po an expression enclosed in square brackets, +.Qq [] +.Pc +is an RE that matches a single collating element contained in the non-empty set +of collating elements represented by the bracket expression. +.Pp +The following rules and definitions apply to bracket expressions: +.Bl -enum +.It +A +.Em bracket expression +is either a matching list expression or a non-matching list expression. +It consists of one or more expressions: collating elements, collating symbols, +equivalence classes, character classes, or range expressions +.Pq see rule 7 below . +Portable applications must not use range expressions, even though all +implementations support them. +The right-bracket +.Pq Qq \&] +loses its special meaning and represents itself in a bracket expression if it +occurs first in the list +.Po after an initial circumflex +.Pq Qq ^ , +if any +.Pc . +Otherwise, it terminates the bracket expression, unless it appears in a +collating symbol +.Po such as +.Qq [.].] +.Pc +or is the ending right-bracket for a collating symbol, equivalence class, or +character class. +.Pp +The special characters +.Qq \&. , +.Qq * , +.Qq \&[ , +.Qq \&\e +.Pq period, asterisk, left-bracket and backslash, respectively +lose their special meaning within a bracket expression. +.Pp +The character sequences +.Qq [. , +.Qq [= , +.Qq [: +.Pq left-bracket followed by a period, equals-sign, or colon +are special inside a bracket expression and are used to delimit collating +symbols, equivalence class expressions, and character class expressions. +These symbols must be followed by a valid expression and the matching +terminating sequence +.Qq .] , +.Qq =] +or +.Qq :] , +as described in the following items. +.It +A +.Em matching list expression +specifies a list that matches any one of the expressions represented in the +list. +The first character in the list must not be the circumflex. +For example, +.Qq [abc] +is an RE that matches any of the characters +.Qq a , +.Qq b +or +.Qq c . +.It +A +.Em non-matching list expression +begins with a circumflex +.Pq Qq ^ , +and specifies a list that matches any character or collating element except for +the expressions represented in the list after the leading circumflex. +For example, +.Qq [^abc] +is an RE that matches any character or collating element except the characters +.Qq a , +.Qq b , +or +.Qq c . +The circumflex will have this special meaning only when it occurs first in the +list, immediately following the left-bracket. +.It +A +.Em collating symbol +is a collating element enclosed within bracket-period +.Pq Qq [..] +delimiters. +Multi-character collating elements must be represented as collating symbols when +it is necessary to distinguish them from a list of the individual characters +that make up the multi-character collating element. +For example, if the string +.Qq ch +is a collating element in the current collation sequence with the associated +collating symbol +.Qq Aq ch , +the expression +.Qq [[.ch.]] +will be treated as an RE matching the character sequence +.Qq ch , +while +.Qq [ch] +will be treated as an RE matching +.Qq c +or +.Qq h . +Collating symbols will be recognized only inside bracket expressions. +This implies that the RE +.Qq [[.ch.]]*c +matches the first to fifth character in the string +.Qq chchch. +If the string is not a collating element in the current collating sequence +definition, or if the collating element has no characters associated with it, +the symbol will be treated as an invalid expression. +.It +An +.Em equivalence class expression +represents the set of collating elements belonging to an equivalence class. +Only primary equivalence classes will be recognised. +The class is expressed by enclosing any one of the collating elements in the +equivalence class within bracket-equal +.Pq Qq [==] +delimiters. +For example, if +.Qq a +and +.Qq b +belong to the same equivalence class, then +.Qq [[=a=]b] , +.Qq [[==]a] +and +.Qq [[==]b] +will each be equivalent to +.Qq [ab] . +If the collating element does not belong to an equivalence class, the +equivalence class expression will be treated as a +.Em collating symbol . +.It +A +.Em character class expression +represents the set of characters belonging to a character class, as defined in +the +.Ev LC_CTYPE +category in the current locale. +All character classes specified in the current locale will be recognized. +A character class expression is expressed as a character class name enclosed +within bracket-colon +.Pq Qq [::] +delimiters. +.Pp +The following character class expressions are supported in all locales: +.Bl -column "[:alnum:]" "[:cntrl:]" "[:lower:]" "[:xdigit:]" +.It [:alnum:] Ta [:cntrl:] Ta [:lower:] Ta [:space:] +.It [:alpha:] Ta [:digit:] Ta [:print:] Ta [:upper:] +.It [:blank:] Ta [:graph:] Ta [:punct:] Ta [:xdigit:] +.El +.Pp +In addition, character class expressions of the form +.Qq [:name:] +are recognized in those locales where the +.Em name +keyword has been given a +.Em charclass +definition in the +.Ev LC_CTYPE +category. +.It +A +.Em range expression +represents the set of collating elements that fall between two elements in the +current collation sequence, inclusively. +It is expressed as the starting point and the ending point separated by a hyphen +.Pq Qq - . +.Pp +Range expressions must not be used in portable applications because their +behavior is dependent on the collating sequence. +Ranges will be treated according to the current collating sequence, and include +such characters that fall within the range based on that collating sequence, +regardless of character values. +This, however, means that the interpretation will differ depending on collating +sequence. +If, for instance, one collating sequence defines as a variant of +.Qq a , +while another defines it as a letter following +.Qq z , +then the expression +.Qq [-z] +is valid in the first language and invalid in the second. +.sp +In the following, all examples assume the collation sequence specified for the +POSIX locale, unless another collation sequence is specifically defined. +.Pp +The starting range point and the ending range point must be a collating element +or collating symbol. +An equivalence class expression used as a starting or ending point of a range +expression produces unspecified results. +An equivalence class can be used portably within a bracket expression, but only +outside the range. +For example, the unspecified expression +.Qq [[=e=]-f] +should be given as +.Qq [[=e=]e-f] . +The ending range point must collate equal to or higher than the starting range +point; otherwise, the expression will be treated as invalid. +The order used is the order in which the collating elements are specified in the +current collation definition. +One-to-many mappings +.Po see +.Xr locale 7 +.Pc +will not be performed. +For example, assuming that the character +.Qq eszet +is placed in the collation sequence after +.Qq r +and +.Qq s , +but before +.Qq t , +and that it maps to the sequence +.Qq ss +for collation purposes, then the expression +.Qq [r-s] +matches only +.Qq r +and +.Qq s , +but the expression +.Qq [s-t] +matches +.Qq s , +.Qq beta , +or +.Qq t . +.Pp +The interpretation of range expressions where the ending range point is also +the starting range point of a subsequent range expression +.Po for instance +.Qq [a-m-o] +.Pc +is undefined. +.Pp +The hyphen character will be treated as itself if it occurs first +.Po after an initial +.Qq ^ , +if any +.Pc +or last in the list, or as an ending range point in a range expression. +As examples, the expressions +.Qq [-ac] +and +.Qq [ac-] +are equivalent and match any of the characters +.Qq a , +.Qq c , +or +.Qq -; +.Qq [^-ac] +and +.Qq [^ac-] +are equivalent and match any characters except +.Qq a , +.Qq c , +or +.Qq -; +the expression +.Qq [%--] +matches any of the characters between +.Qq % +and +.Qq - +inclusive; the expression +.Qq [--@] +matches any of the characters between +.Qq - +and +.Qq @ +inclusive; and the expression +.Qq [a--@] +is invalid, because the letter +.Qq a +follows the symbol +.Qq - +in the POSIX locale. +To use a hyphen as the starting range point, it must either come first in the +bracket expression or be specified as a collating symbol, for example: +.Qq [][.-.]-0] , +which matches either a right bracket or any character or collating element that +collates between hyphen and 0, inclusive. +.Pp +If a bracket expression must specify both +.Qq - +and +.Qq \&] , +the +.Qq \&] +must be placed first +.Po after the +.Qq ^ , +if any +.Pc +and the +.Qq - +last within the bracket expression. +.El +.Pp +Note: Latin-1 characters such as +.Qq \(ga +or +.Qq ^ +are not printable in some locales, for example, the +.Em ja +locale. +.Ss BREs Matching Multiple Characters +The following rules can be used to construct BREs matching multiple characters +from BREs matching a single character: +.Bl -enum +.It +The concatenation of BREs matches the concatenation of the strings matched +by each component of the BRE. +.It +A +.Em subexpression +can be defined within a BRE by enclosing it between the character pairs +.Qq \e( +and +.Qq \e) . +Such a subexpression matches whatever it would have matched without the +.Qq \e( +and +.Qq \e) , +except that anchoring within subexpressions is optional behavior; see +.Sx BRE Expression Anchoring , +below. +Subexpressions can be arbitrarily nested. +.It +The +.Em back-reference +expression +.Qq \e Ns Em n +matches the same +.Pq possibly empty +string of characters as was matched by a subexpression enclosed between +.Qq \e( +and +.Qq \e) +preceding the +.Qq \e Ns Em n . +The character +.Qq Em n +must be a digit from 1 to 9 inclusive, +.Em n Ns th +subexpression +.Po the one that begins with the +.Em n Ns th +.Qq \e( +and ends with the corresponding paired +.Qq \e) +.Pc . +The expression is invalid if less than +.Em n +subexpressions precede the +.Qq \e Ns Em n . +For example, the expression +.Qq ^\e(.*\e)\e1$ +matches a line consisting of two adjacent appearances of the same string, and +the expression +.Qq \e(a\e)*\e1 +fails to match +.Qq a . +The limit of nine back-references to subexpressions in the RE is based on the +use of a single digit identifier. +This does not imply that only nine subexpressions are allowed in REs. +.It +When a BRE matching a single character, a subexpression or a back-reference is +followed by the special character asterisk +.Pq Qq * , +together with that asterisk it matches what zero or more consecutive occurrences +of the BRE would match. +For example, +.Qq [ab]* +and +.Qq [ab][ab] +are equivalent when matching the string +.Qq ab . +.It +When a BRE matching a single character, a subexpression, or a back-reference +is followed by an +.Em interval expression +of the format +.Qq \e{ Ns Em m Ns \e} , +.Qq \e{ Ns Em m Ns ,\e} +or +.Qq \e{ Ns Em m Ns \&, Ns Em n Ns \e} , +together with that interval expression it matches what repeated consecutive +occurrences of the BRE would match. +The values of +.Em m +and +.Em n +will be decimal integers in the range 0 <= +.Em m +<= +.Em n +<= +.Dv BRE_DUP_MAX , +where +.Em m +specifies the exact or minimum number of occurrences and +.Em n +specifies the maximum number of occurrences. +The expression +.Qq \e{ Ns Em m Ns \e} +matches exactly +.Em m +occurrences of the preceding BRE, +.Qq \e{ Ns Em m Ns ,\e} +matches at least +.Em m +occurrences and +.Qq \e{ Ns Em m Ns \&, Ns Em n Ns \e} +matches any number of occurrences between +.Em m +and +.Em n , +inclusive. +.Pp +For example, in the string +.Qq abababccccccd , +the BRE +.Qq c\e{3\e} +is matched by characters seven to nine, the BRE +.Qq \e(ab\e)\e{4,\e} +is not matched at all and the BRE +.Qq c\e{1,3\e}d +is matched by characters ten to thirteen. +.El +.Pp +The behavior of multiple adjacent duplication symbols +.Po Qq * +and intervals +.Pc +produces undefined results. +.Ss BRE Precedence +The order of precedence is as shown in the following table: +.Bl -column "BRE Precedence (from high to low)" "" +.It Sy BRE Precedence (from high to low) Ta +.It collation-related bracket symbols Ta [= =] [: :] [. .] +.It escaped characters Ta \e< Ns Em special character Ns > +.It bracket expression Ta [ ] +.It subexpressions/back-references Ta \e( \e) \e Ns Em n +.It single-character-BRE duplication Ta * \e{ Ns Em m Ns \&, Ns Em n Ns \e} +.It concatenation Ta +.It anchoring Ta ^ $ +.El +.Ss BRE Expression Anchoring +A BRE can be limited to matching strings that begin or end a line; this is +called +.Em anchoring . +The circumflex and dollar sign special characters will be considered BRE anchors +in the following contexts: +.Bl -enum +.It +A circumflex +.Pq Qq ^ +is an anchor when used as the first character of an entire BRE. +The implementation may treat circumflex as an anchor when used as the first +character of a subexpression. +The circumflex will anchor the expression to the beginning of a string; +only sequences starting at the first character of a string will be matched by +the BRE. +For example, the BRE +.Qq ^ab +matches +.Qq ab +in the string +.Qq abcdef , +but fails to match in the string +.Qq cdefab . +A portable BRE must escape a leading circumflex in a subexpression to match a +literal circumflex. +.It +A dollar sign +.Pq Qq $ +is an anchor when used as the last character of an entire BRE. +The implementation may treat a dollar sign as an anchor when used as the last +character of a subexpression. +The dollar sign will anchor the expression to the end of the string being +matched; the dollar sign can be said to match the end-of-string following the +last character. +.It +A BRE anchored by both +.Qq ^ +and +.Qq $ +matches only an entire string. +For example, the BRE +^abcdef$ +matches strings consisting only of +.Qq abcdef . +.It +.Qq ^ +and +.Qq $ +are not special in subexpressions. +.El +.Pp +Note: The Solaris implementation does not support anchoring in BRE +subexpressions. +.Sh EXTENDED REGULAR EXPRESSIONS +The rules specified for BREs apply to Extended Regular Expressions +.Pq EREs +with the following exceptions: +.Bl -bullet +.It +The characters +.Qq | , +.Qq + , +and +.Qq \&? +have special meaning, as defined below. +.It +The +.Qq { +and +.Qq } +characters, when used as the duplication operator, are not preceded by +backslashes. +The constructs +.Qq \e{ +and +.Qq \e} +simply match the characters +.Qq { +and +.Qq }, respectively. +.It +The back reference operator is not supported. +.It +Anchoring +.Pq Qq ^$ +is supported in subexpressions. +.El +.Ss EREs Matching a Single Character +An ERE ordinary character, a special character preceded by a backslash, or a +period matches a single character. +A bracket expression matches a single character or a single collating element. +An +.Em ERE matching a single character +enclosed in parentheses matches the same as the ERE without parentheses would +have matched. +.Ss ERE Ordinary Characters +An +.Em ordinary character +is an ERE that matches itself. +An ordinary character is any character in the supported character set, except +for the ERE special characters listed in +.Sx ERE Special Characters +below. +The interpretation of an ordinary character preceded by a backslash +.Pq Qq \&\e +is undefined. +.Ss ERE Special Characters +An +.Em ERE special character +has special properties in certain contexts. +Outside those contexts, or when preceded by a backslash, such a character is an +ERE that matches the special character itself. +The extended regular expression special characters and the contexts in which +they have their special meaning are: +.Bl -tag -width Ds +.It Sy \&. \&[ \&\e \&( +The period, left-bracket, backslash, and left-parenthesis are special except +when used in a bracket expression +.Po see +.Sx RE Bracket Expression , +above +.Pc . +Outside a bracket expression, a left-parenthesis immediately followed by a +right-parenthesis produces undefined results. +.It Sy \&) +The right-parenthesis is special when matched with a preceding +left-parenthesis, both outside a bracket expression. +.It Sy * + \&? { +The asterisk, plus-sign, question-mark, and left-brace are special except when +used in a bracket expression +.Po see +.Sx RE Bracket Expression , +above +.Pc . +Any of the following uses produce undefined results: +.Bl -bullet +.It +if these characters appear first in an ERE, or immediately following a +vertical-line, circumflex or left-parenthesis +.It +if a left-brace is not part of a valid interval expression. +.El +.It Sy \&| +The vertical-line is special except when used in a bracket expression +.Po see +.Sx RE Bracket Expression , +above +.Pc . +A vertical-line appearing first or last in an ERE, or immediately following a +vertical-line or a left-parenthesis, or immediately preceding a +right-parenthesis, produces undefined results. +.It Sy ^ +The circumflex is special when used: +.Bl -bullet +.It +as an anchor +.Po see +.Sx ERE Expression Anchoring , +below +.Pc . +.It +as the first character of a bracket expression +.Po see +.Sx RE Bracket Expression , +above +.Pc . +.El +.It Sy $ +The dollar sign is special when used as an anchor. +.El +.Ss Periods in EREs +A period +.Pq Qq \&. , +when used outside a bracket expression, is an ERE that matches any character in +the supported character set except NUL. +.Ss ERE Bracket Expression +The rules for ERE Bracket Expressions are the same as for Basic Regular +Expressions; see +.Sx RE Bracket Expression , +above. +.Ss EREs Matching Multiple Characters +The following rules will be used to construct EREs matching multiple characters +from EREs matching a single character: +.Bl -enum +.It +A +.Em concatenation of EREs +matches the concatenation of the character sequences matched by each component +of the ERE. +A concatenation of EREs enclosed in parentheses matches whatever the +concatenation without the parentheses matches. +For example, both the ERE +.Qq cd +and the ERE +.Qq (cd) +are matched by the third and fourth character of the string +.Qq abcdefabcdef . +.It +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by the special character plus-sign +.Pq Qq + , +together with that plus-sign it matches what one or more consecutive occurrences +of the ERE would match. +For example, the ERE +.Qq b+(bc) +matches the fourth to seventh characters in the string +.Qq acabbbcde ; +.Qq [ab]+ +and +.Qq [ab][ab]* +are equivalent. +.It +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by the special character asterisk +.Pq Qq * , +together with that asterisk it matches what zero or more consecutive occurrences +of the ERE would match. +For example, the ERE +.Qq b*c +matches the first character in the string +.Qq cabbbcde , +and the ERE +.Qq b*cd +matches the third to seventh characters in the string +.Qq cabbbcdebbbbbbcdbc . +And, +.Qq [ab]* +and +.Qq [ab][ab] +are equivalent when matching the string +.Qq ab . +.It +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by the special character question-mark +.Pq Qq \&? , +together with that question-mark it matches what zero or one consecutive +occurrences of the ERE would match. +For example, the ERE +.Qq b?c +matches the second character in the string +.Qq acabbbcde . +.It +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by an +.Em interval expression +of the format +.Qq { Ns Em m Ns } , +.Qq { Ns Em m Ns ,} +or +.Qq { Ns Em m Ns \&, Ns Em n Ns } , +together with that interval expression it matches what repeated consecutive +occurrences of the ERE would match. +The values of +.Em m +and +.Em n +will be decimal integers in the range 0 <= +.Em m +<= +.Em n +<= +.Dv RE_DUP_MAX , +where +.Em m +specifies the exact or minimum number of occurrences and +.Em n +specifies the maximum number of occurrences. +The expression +.Qq { Ns Em m Ns } +matches exactly +.Em m +occurrences of the preceding ERE, +.Qq { Ns Em m Ns ,} +matches at least +.Em m +occurrences and +.Qq { Ns m Ns \&, Ns Em n Ns } +matches any number of occurrences between +.Em m +and +.Em n , +inclusive. +.El +.Pp +For example, in the string +.Qq abababccccccd +the ERE +.Qq c{3} +is matched by characters seven to nine and the ERE +.Qq (ab){2,} +is matched by characters one to six. +.Pp +The behavior of multiple adjacent duplication symbols +.Po +.Qq + , +.Qq * , +.Qq \&? +and intervals +.Pc +produces undefined results. +.Ss ERE Alternation +Two EREs separated by the special character vertical-line +.Pq Qq | +match a string that is matched by either. +For example, the ERE +.Qq a((bc)|d) +matches the string +.Qq abc +and the string +.Qq ad . +Single characters, or expressions matching single characters, separated by the +vertical bar and enclosed in parentheses, will be treated as an ERE matching a +single character. +.Ss ERE Precedence +The order of precedence will be as shown in the following table: +.Bl -column "ERE Precedence (from high to low)" "" +.It Sy ERE Precedence (from high to low) Ta +.It collation-related bracket symbols Ta [= =] [: :] [. .] +.It escaped characters Ta \e< Ns Em special character Ns > +.It bracket expression Ta \&[ \&] +.It grouping Ta \&( \&) +.It single-character-ERE duplication Ta * + \&? { Ns Em m Ns \&, Ns Em n Ns} +.It concatenation Ta +.It anchoring Ta ^ $ +.It alternation Ta | +.El +.Pp +For example, the ERE +.Qq abba|cde +matches either the string +.Qq abba +or the string +.Qq cde +.Po rather than the string +.Qq abbade +or +.Qq abbcde , +because concatenation has a higher order of precedence than alternation +.Pc . +.Ss ERE Expression Anchoring +An ERE can be limited to matching strings that begin or end a line; this is +called +.Em anchoring . +The circumflex and dollar sign special characters are considered ERE anchors +when used anywhere outside a bracket expression. +This has the following effects: +.Bl -enum +.It +A circumflex +.Pq Qq ^ +outside a bracket expression anchors the expression or subexpression it begins +to the beginning of a string; such an expression or subexpression can match only +a sequence starting at the first character of a string. +For example, the EREs +.Qq ^ab +and +.Qq (^ab) +match +.Qq ab +in the string +.Qq abcdef , +but fail to match in the string +.Qq cdefab , +and the ERE +.Qq a^b +is valid, but can never match because the +.Qq a +prevents the expression +.Qq ^b +from matching starting at the first character. +.It +A dollar sign +.Pq Qq $ +outside a bracket expression anchors the expression or subexpression it ends to +the end of a string; such an expression or subexpression can match only a +sequence ending at the last character of a string. +For example, the EREs +.Qq ef$ +and +.Qq (ef$) +match +.Qq ef +in the string +.Qq abcdef , +but fail to match in the string +.Qq cdefab , +and the ERE +.Qq e$f +is valid, but can never match because the +.Qq f +prevents the expression +.Qq e$ +from matching ending at the last character. +.El +.Sh SEE ALSO +.Xr localedef 1 , +.Xr regcomp 3C , +.Xr attributes 7 , +.Xr environ 7 , +.Xr locale 7 , +.Xr regexp 7 diff --git a/usr/src/man/man7/regexp.7 b/usr/src/man/man7/regexp.7 new file mode 100644 index 0000000000..337b6592a5 --- /dev/null +++ b/usr/src/man/man7/regexp.7 @@ -0,0 +1,750 @@ +.\" +.\" 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 SunOS 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 and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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] +.\" +.\" +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" +.TH REGEXP 7 "May 20, 2002" +.SH NAME +regexp, compile, step, advance \- simple regular expression compile and match +routines +.SH SYNOPSIS +.LP +.nf +#define INIT \fIdeclarations\fR +#define GETC(void) \fIgetc code\fR +#define PEEKC(void) \fIpeekc code\fR +#define UNGETC(void) \fIungetc code\fR +#define RETURN(\fIptr\fR) \fIreturn code\fR +#define ERROR(\fIval\fR) \fIerror code\fR + +extern char *\fIloc1\fR, *\fIloc2\fR, *\fIlocs\fR; + +#include <regexp.h> + +\fBchar *\fR\fBcompile\fR(\fBchar *\fR\fIinstring\fR, \fBchar *\fR\fIexpbuf\fR, \fBconst char *\fR\fIendfug\fR, \fBint\fR \fIeof\fR); +.fi + +.LP +.nf +\fBint\fR \fBstep\fR(\fBconst char *\fR\fIstring\fR, \fBconst char *\fR\fIexpbuf\fR); +.fi + +.LP +.nf +\fBint\fR \fBadvance\fR(\fBconst char *\fR\fIstring\fR, \fBconst char *\fR\fIexpbuf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Regular Expressions (REs) provide a mechanism to select specific strings from a +set of character strings. The Simple Regular Expressions described below differ +from the Internationalized Regular Expressions described on the +\fBregex\fR(7) manual page in the following ways: +.RS +4 +.TP +.ie t \(bu +.el o +only Basic Regular Expressions are supported +.RE +.RS +4 +.TP +.ie t \(bu +.el o +the Internationalization features\(emcharacter class, equivalence class, and +multi-character collation\(emare not supported. +.RE +.sp +.LP +The functions \fBstep()\fR, \fBadvance()\fR, and \fBcompile()\fR are general +purpose regular expression matching routines to be used in programs that +perform regular expression matching. These functions are defined by the +\fB<regexp.h>\fR header. +.sp +.LP +The functions \fBstep()\fR and \fBadvance()\fR do pattern matching given a +character string and a compiled regular expression as input. +.sp +.LP +The function \fBcompile()\fR takes as input a regular expression as defined +below and produces a compiled expression that can be used with \fBstep()\fR or +\fBadvance()\fR. +.SS "Basic Regular Expressions" +.sp +.LP +A regular expression specifies a set of character strings. A member of this set +of strings is said to be matched by the regular expression. Some characters +have special meaning when used in a regular expression; other characters stand +for themselves. +.sp +.LP +The following \fIone-character\fR \fIRE\fRs match a \fIsingle\fR character: +.sp +.ne 2 +.na +\fB1.1\fR +.ad +.RS 7n +An ordinary character ( \fInot\fR one of those discussed in 1.2 below) is a +one-character RE that matches itself. +.RE + +.sp +.ne 2 +.na +\fB1.2\fR +.ad +.RS 7n +A backslash (\fB\|\e\fR\|) followed by any special character is a one-character +RE that matches the special character itself. The special characters are: +.sp +.ne 2 +.na +\fBa.\fR +.ad +.RS 6n +\fB\&.\fR, \fB*\fR, \fB[\fR\|, and \fB\e\fR (period, asterisk, left square +bracket, and backslash, respectively), which are always special, \fIexcept\fR +when they appear within square brackets (\fB[\|]\fR; see 1.4 below). +.RE + +.sp +.ne 2 +.na +\fBb.\fR +.ad +.RS 6n +^ (caret or circumflex), which is special at the \fIbeginning\fR of an +\fIentire\fR RE (see 4.1 and 4.3 below), or when it immediately follows the +left of a pair of square brackets (\fB[\|]\fR) (see 1.4 below). +.RE + +.sp +.ne 2 +.na +\fBc.\fR +.ad +.RS 6n +\fB$\fR (dollar sign), which is special at the \fBend\fR of an \fIentire\fR RE +(see 4.2 below). +.RE + +.sp +.ne 2 +.na +\fBd.\fR +.ad +.RS 6n +The character used to bound (that is, delimit) an entire RE, which is special +for that RE (for example, see how slash (\fB/\fR) is used in the \fBg\fR +command, below.) +.RE + +.RE + +.sp +.ne 2 +.na +\fB1.3\fR +.ad +.RS 7n +A period (\fB\&.\fR) is a one-character RE that matches any character except +new-line. +.RE + +.sp +.ne 2 +.na +\fB1.4\fR +.ad +.RS 7n +A non-empty string of characters enclosed in square brackets (\fB[\|]\fR) is a +one-character RE that matches \fIany one\fR character in that string. If, +however, the first character of the string is a circumflex (^), the +one-character RE matches any character \fIexcept\fR new-line and the remaining +characters in the string. The ^ has this special meaning \fIonly\fR if it +occurs first in the string. The minus (\fB-\fR) may be used to indicate a range +of consecutive characters; for example, \fB[0-9]\fR is equivalent to +\fB[0123456789]\fR. The \fB-\fR loses this special meaning if it occurs first +(after an initial ^, if any) or last in the string. The right square bracket +(\fB]\fR) does not terminate such a string when it is the first character +within it (after an initial ^, if any); for example, \fB[\|]a-f]\fR matches +either a right square bracket (\fB]\fR) or one of the \fBASCII\fR letters +\fBa\fR through \fBf\fR inclusive. The four characters listed in 1.2.a above +stand for themselves within such a string of characters. +.RE + +.sp +.LP +The following rules may be used to construct REs from one-character REs: +.sp +.ne 2 +.na +\fB2.1\fR +.ad +.RS 7n +A one-character RE is a RE that matches whatever the one-character RE matches. +.RE + +.sp +.ne 2 +.na +\fB2.2\fR +.ad +.RS 7n +A one-character RE followed by an asterisk (\fB*\fR) is a RE that matches +\fB0\fR or more occurrences of the one-character RE. If there is any choice, +the longest leftmost string that permits a match is chosen. +.RE + +.sp +.ne 2 +.na +\fB2.3\fR +.ad +.RS 7n +A one-character RE followed by \fB\e{\fR\fIm\fR\fB\e}\fR, +\fB\e{\fR\fIm,\fR\fB\e}\fR, or \fB\e{\fR\fIm,n\fR\fB\e}\fR is a RE that matches +a \fIrange\fR of occurrences of the one-character RE. The values of \fIm\fR and +\fIn\fR must be non-negative integers less than 256; \fB\e{\fR\fIm\fR\fB\e}\fR +matches \fIexactly\fR \fIm\fR occurrences; \fB\e{\fR\fIm,\fR\fB\e}\fR matches +\fIat least\fR \fIm\fR occurrences; \fB\e{\fR\fIm,n\fR\fB\e}\fR matches \fIany +number\fR of occurrences \fIbetween\fR \fIm\fR and \fIn\fR inclusive. Whenever +a choice exists, the RE matches as many occurrences as possible. +.RE + +.sp +.ne 2 +.na +\fB2.4\fR +.ad +.RS 7n +The concatenation of REs is a RE that matches the concatenation of the strings +matched by each component of the RE. +.RE + +.sp +.ne 2 +.na +\fB2.5\fR +.ad +.RS 7n +A RE enclosed between the character sequences \fB\e\|(\fR and \fB\e\|)\fR is a +RE that matches whatever the unadorned RE matches. +.RE + +.sp +.ne 2 +.na +\fB2.6\fR +.ad +.RS 7n +The expression \fB\e\|\fR\fIn\fR matches the same string of characters as was +matched by an expression enclosed between \fB\e\|(\fR and \fB\e\|)\fR +\fIearlier\fR in the same RE. Here \fIn\fR is a digit; the sub-expression +specified is that beginning with the \fIn\fR-th occurrence of \fB\|\e\|(\fR +counting from the left. For example, the expression +^\|\fB\e\|(\|.\|*\|\e\|)\|\e\|1\|$\fR matches a line consisting of two repeated +appearances of the same string. +.RE + +.sp +.LP +An RE may be constrained to match words. +.sp +.ne 2 +.na +\fB3.1\fR +.ad +.RS 7n +\fB\e\|<\fR constrains a RE to match the beginning of a string or to follow a +character that is not a digit, underscore, or letter. The first character +matching the RE must be a digit, underscore, or letter. +.RE + +.sp +.ne 2 +.na +\fB3.2\fR +.ad +.RS 7n +\fB\e\|>\fR constrains a RE to match the end of a string or to precede a +character that is not a digit, underscore, or letter. +.RE + +.sp +.LP +An \fIentire\fR \fIRE\fR may be constrained to match only an initial segment or +final segment of a line (or both). +.sp +.ne 2 +.na +\fB4.1\fR +.ad +.RS 7n +A circumflex (^) at the beginning of an entire RE constrains that RE to match +an \fIinitial\fR segment of a line. +.RE + +.sp +.ne 2 +.na +\fB4.2\fR +.ad +.RS 7n +A dollar sign (\fB$\fR) at the end of an entire RE constrains that RE to match +a \fIfinal\fR segment of a line. +.RE + +.sp +.ne 2 +.na +\fB4.3\fR +.ad +.RS 7n +The construction ^\fIentire RE\fR\|\fB$\fR constrains the entire RE to match +the entire line. +.RE + +.sp +.LP +The null RE (for example, \fB//\|\fR) is equivalent to the last RE encountered. +.SS "Addressing with REs" +.sp +.LP +Addresses are constructed as follows: +.RS +4 +.TP +1. +The character "\fB\&.\fR" addresses the current line. +.RE +.RS +4 +.TP +2. +The character "\fB$\fR" addresses the last line of the buffer. +.RE +.RS +4 +.TP +3. +A decimal number \fIn\fR addresses the \fIn\fR-th line of the buffer. +.RE +.RS +4 +.TP +4. +\fI\&'x\fR addresses the line marked with the mark name character \fIx\fR, +which must be an ASCII lower-case letter (\fBa\fR-\fBz\fR). Lines are marked +with the \fBk\fR command described below. +.RE +.RS +4 +.TP +5. +A RE enclosed by slashes (\fB/\fR) addresses the first line found by +searching \fIforward\fR from the line \fIfollowing\fR the current line toward +the end of the buffer and stopping at the first line containing a string +matching the RE. If necessary, the search wraps around to the beginning of the +buffer and continues up to and including the current line, so that the entire +buffer is searched. +.RE +.RS +4 +.TP +6. +A RE enclosed in question marks (\fB?\fR) addresses the first line found by +searching \fIbackward\fR from the line \fIpreceding\fR the current line toward +the beginning of the buffer and stopping at the first line containing a string +matching the RE. If necessary, the search wraps around to the end of the buffer +and continues up to and including the current line. +.RE +.RS +4 +.TP +7. +An address followed by a plus sign (\fB+\fR) or a minus sign (\fB-\fR) +followed by a decimal number specifies that address plus (respectively minus) +the indicated number of lines. A shorthand for .+5 is .5. +.RE +.RS +4 +.TP +8. +If an address begins with \fB+\fR or \fB-\fR, the addition or subtraction is +taken with respect to the current line; for example, \fB-5\fR is understood to +mean \fB\&.-5\fR. +.RE +.RS +4 +.TP +9. +If an address ends with \fB+\fR or \fB-\fR, then 1 is added to or subtracted +from the address, respectively. As a consequence of this rule and of Rule 8, +immediately above, the address \fB-\fR refers to the line preceding the current +line. (To maintain compatibility with earlier versions of the editor, the +character ^ in addresses is entirely equivalent to \fB-\fR\&.) Moreover, +trailing \fB+\fR and \fB-\fR characters have a cumulative effect, so \fB--\fR +refers to the current line less 2. +.RE +.RS +4 +.TP +10. +For convenience, a comma (\fB,\fR) stands for the address pair \fB1,$\fR, +while a semicolon (\fB;\fR) stands for the pair \fB\&.,$\fR. +.RE +.SS "Characters With Special Meaning" +.sp +.LP +Characters that have special meaning except when they appear within square +brackets (\fB[\|]\fR) or are preceded by \fB\e\fR are: \fB\&.\fR, \fB*\fR, +\fB[\|\fR, \fB\e\fR\|. Other special characters, such as \fB$\fR have special +meaning in more restricted contexts. +.sp +.LP +The character \fB^\fR at the beginning of an expression permits a successful +match only immediately after a newline, and the character \fB$\fR at the end of +an expression requires a trailing newline. +.sp +.LP +Two characters have special meaning only when used within square brackets. The +character \fB-\fR denotes a range, \fB[\|\fR\fIc\fR\fB-\fR\fIc\fR\fB]\fR, +unless it is just after the open bracket or before the closing bracket, +\fB[\|-\fR\fIc\fR\fB]\fR or \fB[\|\fR\fIc\fR\fB-]\fR in which case it has no +special meaning. When used within brackets, the character \fB^\fR has the +meaning \fIcomplement of\fR if it immediately follows the open bracket +(example: \fB[^\fR\fIc\fR\fB]\|\fR); elsewhere between brackets (example: +\fB[\fR\fIc\fR\fB^]\|\fR) it stands for the ordinary character \fB^\fR. +.sp +.LP +The special meaning of the \fB\e\fR operator can be escaped only by preceding +it with another \fB\e\fR\|, for example \fB\e\e\fR\|. +.SS "Macros" +.sp +.LP +Programs must have the following five macros declared before the \fB#include +<regexp.h>\fR statement. These macros are used by the \fBcompile()\fR routine. +The macros \fBGETC\fR, \fBPEEKC\fR, and \fBUNGETC\fR operate on the regular +expression given as input to \fBcompile()\fR. +.sp +.ne 2 +.na +\fB\fBGETC\fR\fR +.ad +.RS 15n +This macro returns the value of the next character (byte) in the regular +expression pattern. Successive calls to \fBGETC\fR should return successive +characters of the regular expression. +.RE + +.sp +.ne 2 +.na +\fB\fBPEEKC\fR\fR +.ad +.RS 15n +This macro returns the next character (byte) in the regular expression. +Immediately successive calls to \fBPEEKC\fR should return the same character, +which should also be the next character returned by \fBGETC\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBUNGETC\fR\fR +.ad +.RS 15n +This macro causes the argument \fBc\fR to be returned by the next call to +\fBGETC\fR and \fBPEEKC\fR. No more than one character of pushback is ever +needed and this character is guaranteed to be the last character read by +\fBGETC\fR. The return value of the macro \fBUNGETC(c)\fR is always ignored. +.RE + +.sp +.ne 2 +.na +\fB\fBRETURN(\fR\fIptr\fR\fB)\fR\fR +.ad +.RS 15n +This macro is used on normal exit of the \fBcompile()\fR routine. The value of +the argument \fIptr\fR is a pointer to the character after the last character +of the compiled regular expression. This is useful to programs which have +memory allocation to manage. +.RE + +.sp +.ne 2 +.na +\fB\fBERROR(\fR\fIval\fR\fB)\fR\fR +.ad +.RS 15n +This macro is the abnormal return from the \fBcompile()\fR routine. The +argument \fIval\fR is an error number (see \fBERRORS\fR below for meanings). +This call should never return. +.RE + +.SS "\fBcompile()\fR" +.sp +.LP +The syntax of the \fBcompile()\fR routine is as follows: +.sp +.in +2 +.nf +\fBcompile(\fR\fIinstring\fR\fB,\fR \fIexpbuf\fR\fB,\fR \fIendbuf\fR\fB,\fR \fIeof\fR\fB)\fR +.fi +.in -2 +.sp + +.sp +.LP +The first parameter, \fIinstring\fR, is never used explicitly by the +\fBcompile()\fR routine but is useful for programs that pass down different +pointers to input characters. It is sometimes used in the \fBINIT\fR +declaration (see below). Programs which call functions to input characters or +have characters in an external array can pass down a value of \fB(char *)0\fR +for this parameter. +.sp +.LP +The next parameter, \fIexpbuf\fR, is a character pointer. It points to the +place where the compiled regular expression will be placed. +.sp +.LP +The parameter \fIendbuf\fR is one more than the highest address where the +compiled regular expression may be placed. If the compiled expression cannot +fit in \fB(endbuf-expbuf)\fR bytes, a call to \fBERROR(50)\fR is made. +.sp +.LP +The parameter \fIeof\fR is the character which marks the end of the regular +expression. This character is usually a \fB/\fR. +.sp +.LP +Each program that includes the \fB<regexp.h>\fR header file must have a +\fB#define\fR statement for \fBINIT\fR. It is used for dependent declarations +and initializations. Most often it is used to set a register variable to point +to the beginning of the regular expression so that this register variable can +be used in the declarations for \fBGETC\fR, \fBPEEKC\fR, and \fBUNGETC\fR. +Otherwise it can be used to declare external variables that might be used by +\fBGETC\fR, \fBPEEKC\fR and \fBUNGETC\fR. (See \fBEXAMPLES\fR below.) +.SS "step(\|), advance(\|)" +.sp +.LP +The first parameter to the \fBstep()\fR and \fBadvance()\fR functions is a +pointer to a string of characters to be checked for a match. This string should +be null terminated. +.sp +.LP +The second parameter, \fIexpbuf\fR, is the compiled regular expression which +was obtained by a call to the function \fBcompile()\fR. +.sp +.LP +The function \fBstep()\fR returns non-zero if some substring of \fIstring\fR +matches the regular expression in \fIexpbuf\fR and \fB0\fR if there is no +match. If there is a match, two external character pointers are set as a side +effect to the call to \fBstep()\fR. The variable \fBloc1\fR points to the first +character that matched the regular expression; the variable \fBloc2\fR points +to the character after the last character that matches the regular expression. +Thus if the regular expression matches the entire input string, \fBloc1\fR will +point to the first character of \fIstring\fR and \fBloc2\fR will point to the +null at the end of \fIstring\fR. +.sp +.LP +The function \fBadvance()\fR returns non-zero if the initial substring of +\fIstring\fR matches the regular expression in \fIexpbuf\fR. If there is a +match, an external character pointer, \fBloc2\fR, is set as a side effect. The +variable \fBloc2\fR points to the next character in \fIstring\fR after the last +character that matched. +.sp +.LP +When \fBadvance()\fR encounters a \fB*\fR or \fB\e{ \e}\fR sequence in the +regular expression, it will advance its pointer to the string to be matched as +far as possible and will recursively call itself trying to match the rest of +the string to the rest of the regular expression. As long as there is no match, +\fBadvance()\fR will back up along the string until it finds a match or reaches +the point in the string that initially matched the \fB*\fR or \fB\e{ \e}\fR\&. +It is sometimes desirable to stop this backing up before the initial point in +the string is reached. If the external character pointer \fBlocs\fR is equal to +the point in the string at sometime during the backing up process, +\fBadvance()\fR will break out of the loop that backs up and will return zero. +.sp +.LP +The external variables \fBcircf\fR, \fBsed\fR, and \fBnbra\fR are reserved. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing Regular Expression Macros and Calls +.sp +.LP +The following is an example of how the regular expression macros and calls +might be defined by an application program: + +.sp +.in +2 +.nf +#define INIT register char *sp = instring; +#define GETC() (*sp++) +#define PEEKC() (*sp) +#define UNGETC(c) (--sp) +#define RETURN(c) return; +#define ERROR(c) regerr() + +#include <regexp.h> +\&... + (void) compile(*argv, expbuf, &expbuf[ESIZE],'\e0'); +\&... + if (step(linebuf, expbuf)) + succeed; +.fi +.in -2 +.sp + +.SH DIAGNOSTICS +.sp +.LP +The function \fBcompile()\fR uses the macro \fBRETURN\fR on success and the +macro \fBERROR\fR on failure (see above). The functions \fBstep()\fR and +\fBadvance()\fR return non-zero on a successful match and zero if there is no +match. Errors are: +.sp +.ne 2 +.na +\fB11\fR +.ad +.RS 6n +range endpoint too large. +.RE + +.sp +.ne 2 +.na +\fB16\fR +.ad +.RS 6n +bad number. +.RE + +.sp +.ne 2 +.na +\fB25\fR +.ad +.RS 6n +\fB\e\fR \fIdigit\fR out of range. +.RE + +.sp +.ne 2 +.na +\fB36\fR +.ad +.RS 6n +illegal or missing delimiter. +.RE + +.sp +.ne 2 +.na +\fB41\fR +.ad +.RS 6n +no remembered search string. +.RE + +.sp +.ne 2 +.na +\fB42\fR +.ad +.RS 6n +\fB\e( \e)\fR imbalance. +.RE + +.sp +.ne 2 +.na +\fB43\fR +.ad +.RS 6n +too many \fB\e(\fR\&. +.RE + +.sp +.ne 2 +.na +\fB44\fR +.ad +.RS 6n +more than 2 numbers given in \fB\e{ \e}\fR\&. +.RE + +.sp +.ne 2 +.na +\fB45\fR +.ad +.RS 6n +\fB}\fR expected after \fB\e\fR\&. +.RE + +.sp +.ne 2 +.na +\fB46\fR +.ad +.RS 6n +first number exceeds second in \fB\e{ \e}\fR\&. +.RE + +.sp +.ne 2 +.na +\fB49\fR +.ad +.RS 6n +\fB[ ]\fR imbalance. +.RE + +.sp +.ne 2 +.na +\fB50\fR +.ad +.RS 6n +regular expression overflow. +.RE + +.SH SEE ALSO +.sp +.LP +.BR regex (7) diff --git a/usr/src/man/man7/resource_controls.7 b/usr/src/man/man7/resource_controls.7 new file mode 100644 index 0000000000..e9928399aa --- /dev/null +++ b/usr/src/man/man7/resource_controls.7 @@ -0,0 +1,1043 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association. +.\" 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 7 "Jan 23, 2021" +.SH NAME +resource_controls \- resource controls available through project database +.SH DESCRIPTION +The resource controls facility is configured through the project database. See +\fBproject\fR(5). You can set and modify resource controls through the +following utilities: +.RS +4 +.TP +.ie t \(bu +.el o +.BR prctl (1) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +.BR projadd (8) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +.BR projmod (8) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +.BR rctladm (8) +.RE +.sp +.LP +In a program, you use \fBsetrctl\fR(2) to set resource control values. +.sp +.LP +In addition to the preceding resource controls, there are resource pools, +accessible through the \fBpooladm\fR(8) and \fBpoolcfg\fR(8) utilities. In a +program, resource pools can be manipulated through the \fBlibpool\fR(3LIB) +library. +.sp +.LP +The following are the resource controls are available: +.sp +.ne 2 +.na +\fBprocess.max-address-space\fR +.ad +.sp .6 +.RS 4n +Maximum amount of address space, as summed over segment sizes, that is +available to this process, expressed as a number of bytes. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-core-size\fR +.ad +.sp .6 +.RS 4n +Maximum size of a core file created by this process, expressed as a number of +bytes. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-cpu-time\fR +.ad +.sp .6 +.RS 4n +Maximum CPU time that is available to this process, expressed as a number of +seconds. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-data-size\fR +.ad +.sp .6 +.RS 4n +Maximum heap memory available to this process, expressed as a number of bytes. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-file-descriptor\fR +.ad +.sp .6 +.RS 4n +Maximum file descriptor index available to this process, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-file-size\fR +.ad +.sp .6 +.RS 4n +Maximum file offset available for writing by this process, expressed as a +number of bytes. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-locked-memory\fR +.ad +.sp .6 +.RS 4n +Total amount of physical memory that can be locked by this process, expressed +as a number of bytes. This limit is not enforced for a process with the +\fBPRIV_PROC_LOCK_MEMORY\fR privilege. Because the ability to lock memory +is controlled by the \fBPRIV_PROC_LOCK_MEMORY\fR privilege within native +zones, this resource control is only useful within branded zones which might +support a different policy for locking memory. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-msg-messages\fR +.ad +.sp .6 +.RS 4n +Maximum number of messages on a message queue (value copied from the resource +control at \fBmsgget()\fR time), expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-msg-qbytes\fR +.ad +.sp .6 +.RS 4n +Maximum number of bytes of messages on a message queue (value copied from the +resource control at \fBmsgget()\fR time), expressed as a number of bytes. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-port-events\fR +.ad +.sp .6 +.RS 4n +Maximum allowable number of events per event port, expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-sem-nsems\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphores allowed per semaphore set, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-sem-ops\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphore operations allowed per \fBsemop\fR call (value +copied from the resource control at \fBsemget()\fR time). Expressed as an +integer, specifying the number of operations. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-sigqueue-size\fR +.ad +.sp .6 +.RS 4n +Maximum number of outstanding queued signals. +.RE + +.sp +.ne 2 +.na +\fBprocess.max-stack-size\fR +.ad +.sp .6 +.RS 4n +Maximum stack memory segment available to this process, expressed as a number +of bytes. +.RE + +.sp +.ne 2 +.na +\fBproject.cpu-cap\fR +.ad +.sp .6 +.RS 4n +Maximum amount of CPU resources that a project can use. The unit used is the +percentage of a single CPU that can be used by all user threads in a project. +Expressed as an integer. The cap does not apply to threads running in real-time +scheduling class. This resource control does not support the \fBsyslog\fR +action. +.RE + +.sp +.ne 2 +.na +\fBproject.cpu-shares\fR +.ad +.sp .6 +.RS 4n +Number of CPU shares granted to a project for use with the fair share scheduler +(see \fBFSS\fR(4)). The unit used is the number of shares (an integer). This +resource control does not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na +\fBproject.max-contracts\fR +.ad +.sp .6 +.RS 4n +Maximum number of contracts allowed in a project, expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-crypto-memory\fR +.ad +.sp .6 +.RS 4n +Maximum amount of kernel memory that can be used for crypto operations. +Allocations in the kernel for buffers and session-related structures are +charged against this resource control. +.RE + +.sp +.ne 2 +.na +\fBproject.max-locked-memory\fR +.ad +.sp .6 +.RS 4n +Total amount of physical memory locked by device drivers and user processes +(including D/ISM), expressed as a number of bytes. +.RE + +.sp +.ne 2 +.na +\fBproject.max-lwps\fR +.ad +.sp .6 +.RS 4n +Maximum number of LWPs simultaneously available to a project, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-msg-ids\fR +.ad +.sp .6 +.RS 4n +Maximum number of message queue IDs allowed for a project, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-processes\fR +.ad +.sp .6 +.RS 4n +Maximum number of processes simultaneously available to a project, expressed as +an integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-port-ids\fR +.ad +.sp .6 +.RS 4n +Maximum allowable number of event ports, expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-sem-ids\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphore IDs allowed for a project, expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-shm-ids\fR +.ad +.sp .6 +.RS 4n +Maximum number of shared memory IDs allowed for a project, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBproject.max-shm-memory\fR +.ad +.sp .6 +.RS 4n +Total amount of shared memory allowed for a project, expressed as a number of +bytes. +.RE + +.sp +.ne 2 +.na +\fBproject.max-tasks\fR +.ad +.sp .6 +.RS 4n +Maximum number of tasks allowable in a project, expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBproject.pool\fR +.ad +.sp .6 +.RS 4n +Binds a specified resource pool with a project. +.RE + +.sp +.ne 2 +.na +\fBrcap.max-rss\fR +.ad +.sp .6 +.RS 4n +The total amount of physical memory, in bytes, that is available to processes +in a project. +.RE + +.sp +.ne 2 +.na +\fBtask.max-cpu-time\fR +.ad +.sp .6 +.RS 4n +Maximum CPU time that is available to this task's processes, expressed as a +number of seconds. +.RE + +.sp +.ne 2 +.na +\fBtask.max-lwps\fR +.ad +.sp .6 +.RS 4n +Maximum number of LWPs simultaneously available to this task's processes, +expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBtask.max-processes\fR +.ad +.sp .6 +.RS 4n +Maximum number of processes simultaneously available to this task, +expressed as an integer. +.RE + +.sp +.LP +The following zone-wide resource controls are available: +.sp +.ne 2 +.na +\fBzone.cpu-cap\fR +.ad +.sp .6 +.RS 4n +Sets a limit on the amount of CPU time that can be used by a zone. The unit +used is the percentage of a single CPU that can be used by all user threads in +a zone. Expressed as an integer. When projects within the capped zone have +their own caps, the minimum value takes precedence. This resource control does +not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na +\fBzone.cpu-shares\fR +.ad +.sp .6 +.RS 4n +Sets a limit 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 +\fBsyslog\fR action. +.RE + +.sp +.ne 2 +.na +\fBzone.max-locked-memory\fR +.ad +.sp .6 +.RS 4n +Total amount of physical locked memory available to a zone. +.RE + +.sp +.ne 2 +.na +\fBzone.max-lwps\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 by using \fBproject.max-lwps\fR entries. Expressed as +an integer. +.RE + +.sp +.ne 2 +.na +\fBzone.max-msg-ids\fR +.ad +.sp .6 +.RS 4n +Maximum number of message queue IDs allowed for a zone, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBzone.max-processes\fR +.ad +.sp .6 +.RS 4n +Enhances resource isolation by preventing too many processes in one zone from +affecting other zones. A zone's total processes can be further subdivided among +projects within the zone by using \fBproject.max-processes\fR entries. +Expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBzone.max-sem-ids\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphore IDs allowed for a zone, expressed as an integer. +.RE + +.sp +.ne 2 +.na +\fBzone.max-shm-ids\fR +.ad +.sp .6 +.RS 4n +Maximum number of shared memory IDs allowed for a zone, expressed as an +integer. +.RE + +.sp +.ne 2 +.na +\fBzone.max-shm-memory\fR +.ad +.sp .6 +.RS 4n +Total amount of shared memory allowed for a zone, expressed as a number of +bytes. +.RE + +.sp +.ne 2 +.na +\fBzone.max-swap\fR +.ad +.sp .6 +.RS 4n +Total amount of swap that can be consumed by user process address space +mappings and \fBtmpfs\fR mounts for this zone. +.RE + +.sp +.LP +See \fBzones\fR(7). +.SS "Units Used in Resource Controls" +Resource controls can be expressed as in units of size (bytes), time (seconds), +or as a count (integer). These units use the strings specified below. +.sp +.in +2 +.nf +Category Res Ctrl Modifier Scale + Type String +----------- ----------- -------- ----- +Size bytes B 1 + KB 2^10 + MB 2^20 + GB 2^30 + TB 2^40 + PB 2^50 + EB 2^60 + +Time seconds s 1 + Ks 10^3 + Ms 10^6 + Gs 10^9 + Ts 10^12 + Ps 10^15 + Es 10^18 + +Count integer none 1 + K 10^3 + M 10^6 + G 10^9 + T 10^12 + P 10^15 + Es 10^18 +.fi +.in -2 + +.sp +.LP +Scaled values can be used with resource controls. The following example shows a +scaled threshold value: +.sp +.in +2 +.nf +task.max-lwps=(priv,1K,deny) +.fi +.in -2 + +.sp +.LP +In the \fBproject\fR file, the value \fB1K\fR is expanded to \fB1000\fR: +.sp +.in +2 +.nf +task.max-lwps=(priv,1000,deny) +.fi +.in -2 + +.sp +.LP +A second example uses a larger scaled value: +.sp +.in +2 +.nf +process.max-file-size=(priv,5G,deny) +.fi +.in -2 + +.sp +.LP +In the \fBproject\fR file, the value \fB5G\fR is expanded to \fB5368709120\fR: +.sp +.in +2 +.nf +process.max-file-size=(priv,5368709120,deny) +.fi +.in -2 + +.sp +.LP +The preceding examples use the scaling factors specified in the table above. +.sp +.LP +Note that unit modifiers (for example, \fB5G\fR) are accepted by the +\fBprctl\fR(1), \fBprojadd\fR(8), and \fBprojmod\fR(8) commands. You cannot +use unit modifiers in the project database itself. +.SS "Resource Control Values and Privilege Levels" +A threshold value on a resource control constitutes a point at which local +actions can be triggered or global actions, such as logging, can occur. +.sp +.LP +Each threshold value on a resource control must be associated with a privilege +level. The privilege level must be one of the following three types: +.sp +.ne 2 +.na +\fBbasic\fR +.ad +.sp .6 +.RS 4n +Can be modified by the owner of the calling process. +.RE + +.sp +.ne 2 +.na +\fBprivileged\fR +.ad +.sp .6 +.RS 4n +Can be modified by the current process (requiring \fBsys_resource\fR privilege) +or by \fBprctl\fR(1) (requiring \fBproc_owner\fR privilege). +.RE + +.sp +.ne 2 +.na +\fBsystem\fR +.ad +.sp .6 +.RS 4n +Fixed for the duration of the operating system instance. +.RE + +.sp +.LP +A resource control is guaranteed to have one \fBsystem\fR value, which is +defined by the system, or resource provider. The \fBsystem\fR value represents +how much of the resource the current implementation of the operating system is +capable of providing. +.sp +.LP +Any number of privileged values can be defined, and only one basic value is +allowed. Operations that are performed without specifying a privilege value are +assigned a basic privilege by default. +.sp +.LP +The privilege level for a resource control value is defined in the privilege +field of the resource control block as \fBRCTL_BASIC\fR, \fBRCTL_PRIVILEGED\fR, +or \fBRCTL_SYSTEM\fR. See \fBsetrctl\fR(2) for more information. You can use +the \fBprctl\fR command to modify values that are associated with basic and +privileged levels. +.sp +.LP +In specifying the privilege level of \fBprivileged\fR, you can use the +abbreviation \fBpriv\fR. For example: +.sp +.in +2 +.nf +task.max-lwps=(priv,1K,deny) +.fi +.in -2 + +.SS "Global and Local Actions on Resource Control Values" +There are two categories of actions on resource control values: global and +local. +.sp +.LP +Global actions apply to resource control values for every resource control on +the system. You can use \fBrctladm\fR(8) to perform the following actions: +.RS +4 +.TP +.ie t \(bu +.el o +Display the global state of active system resource controls. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Set global logging actions. +.RE +.sp +.LP +You can disable or enable the global logging action on resource controls. You +can set the \fBsyslog\fR action to a specific degree by assigning a severity +level, \fBsyslog=\fR\fIlevel\fR. The possible settings for \fIlevel\fR are as +follows: +.RS +4 +.TP +.ie t \(bu +.el o +\fBdebug\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBinfo\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBnotice\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBwarning\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBerr\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBcrit\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBalert\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBemerg\fR +.RE +.sp +.LP +By default, there is no global logging of resource control violations. +.sp +.LP +Local actions are taken on a process that attempts to exceed the control value. +For each threshold value that is placed on a resource control, you can +associate one or more actions. There are three types of local actions: +\fBnone\fR, \fBdeny\fR, and \fBsignal=\fR. These three actions are used as +follows: +.sp +.ne 2 +.na +\fBnone\fR +.ad +.sp .6 +.RS 4n +No action is taken on resource requests for an amount that is greater than the +threshold. This action is useful for monitoring resource usage without +affecting the progress of applications. You can also enable a global message +that displays when the resource control is exceeded, while, at the same time, +the process exceeding the threshold is not affected. +.RE + +.sp +.ne 2 +.na +\fBdeny\fR +.ad +.sp .6 +.RS 4n +You can deny resource requests for an amount that is greater than the +threshold. For example, a \fBtask.max-lwps\fR resource control with action deny +causes a \fBfork()\fR system call to fail if the new process would exceed the +control value. See the \fBfork\fR(2). +.RE + +.sp +.ne 2 +.na +\fBsignal=\fR +.ad +.sp .6 +.RS 4n +You can enable a global signal message action when the resource control is +exceeded. A signal is sent to the process when the threshold value is exceeded. +Additional signals are not sent if the process consumes additional resources. +Available signals are listed below. +.RE + +.sp +.LP +Not all of the actions can be applied to every resource control. For example, a +process cannot exceed the number of CPU shares assigned to the project of which +it is a member. Therefore, a deny action is not allowed on the +\fBproject.cpu-shares\fR resource control. +.sp +.LP +Due to implementation restrictions, the global properties of each control can +restrict the range of available actions that can be set on the threshold value. +(See \fBrctladm\fR(8).) A list of available signal actions is presented in the +following list. For additional information about signals, see +\fBsignal\fR(3HEAD). +.sp +.LP +The following are the signals available to resource control values: +.sp +.ne 2 +.na +\fBSIGABRT\fR +.ad +.sp .6 +.RS 4n +Terminate the process. +.RE + +.sp +.ne 2 +.na +\fBSIGHUP\fR +.ad +.sp .6 +.RS 4n +Send a hangup signal. Occurs when carrier drops on an open line. Signal sent to +the process group that controls the terminal. +.RE + +.sp +.ne 2 +.na +\fBSIGTERM\fR +.ad +.sp .6 +.RS 4n +Terminate the process. Termination signal sent by software. +.RE + +.sp +.ne 2 +.na +\fBSIGKILL\fR +.ad +.sp .6 +.RS 4n +Terminate the process and kill the program. +.RE + +.sp +.ne 2 +.na +\fBSIGSTOP\fR +.ad +.sp .6 +.RS 4n +Stop the process. Job control signal. +.RE + +.sp +.ne 2 +.na +\fBSIGXRES\fR +.ad +.sp .6 +.RS 4n +Resource control limit exceeded. Generated by resource control facility. +.RE + +.sp +.ne 2 +.na +\fBSIGXFSZ\fR +.ad +.sp .6 +.RS 4n +Terminate the process. File size limit exceeded. Available only to resource +controls with the \fBRCTL_GLOBAL_FILE_SIZE\fR property +(\fBprocess.max-file-size\fR). See \fBrctlblk_set_value\fR(3C). +.RE + +.sp +.ne 2 +.na +\fBSIGXCPU\fR +.ad +.sp .6 +.RS 4n +Terminate the process. CPU time limit exceeded. Available only to resource +controls with the \fBRCTL_GLOBAL_CPUTIME\fR property +(\fBprocess.max-cpu-time\fR). See \fBrctlblk_set_value\fR(3C). +.RE + +.SS "Resource Control Flags and Properties" +Each resource control on the system has a certain set of associated properties. +This set of properties is defined as a set of flags, which are associated with +all controlled instances of that resource. Global flags cannot be modified, but +the flags can be retrieved by using either \fBrctladm\fR(8) or the +\fBsetrctl\fR(2) system call. +.sp +.LP +Local flags define the default behavior and configuration for a specific +threshold value of that resource control on a specific process or process +collective. The local flags for one threshold value do not affect the behavior +of other defined threshold values for the same resource control. However, the +global flags affect the behavior for every value associated with a particular +control. Local flags can be modified, within the constraints supplied by their +corresponding global flags, by the \fBprctl\fR command or the \fBsetrctl\fR +system call. See \fBsetrctl\fR(2). +.sp +.LP +For the complete list of local flags, global flags, and their definitions, see +\fBrctlblk_set_value\fR(3C). +.sp +.LP +To determine system behavior when a threshold value for a particular resource +control is reached, use \fBrctladm\fR to display the global flags for the +resource control . For example, to display the values for +\fBprocess.max-cpu-time\fR, enter: +.sp +.in +2 +.nf +$ rctladm process.max-cpu-time +process.max-cpu-time syslog=off [ lowerable no-deny cpu-time inf seconds ] +.fi +.in -2 + +.sp +.LP +The global flags indicate the following: +.sp +.ne 2 +.na +\fBlowerable\fR +.ad +.sp .6 +.RS 4n +Superuser privileges are not required to lower the privileged values for this +control. +.RE + +.sp +.ne 2 +.na +\fBno-deny\fR +.ad +.sp .6 +.RS 4n +Even when threshold values are exceeded, access to the resource is never +denied. +.RE + +.sp +.ne 2 +.na +\fBcpu-time\fR +.ad +.sp .6 +.RS 4n +\fBSIGXCPU\fR is available to be sent when threshold values of this resource +are reached. +.RE + +.sp +.ne 2 +.na +\fBseconds\fR +.ad +.sp .6 +.RS 4n +The time value for the resource control. +.RE + +.sp +.LP +Use the \fBprctl\fR command to display local values and actions for the +resource control. For example: +.sp +.in +2 +.nf +$ prctl -n process.max-cpu-time $$ + process 353939: -ksh + NAME PRIVILEGE VALUE FLAG ACTION RECIPIENT + process.max-cpu-time + privileged 18.4Es inf signal=XCPU - + system 18.4Es inf none +.fi +.in -2 + +.sp +.LP +The \fBmax\fR (\fBRCTL_LOCAL_MAXIMAL\fR) flag is set for both threshold values, +and the \fBinf\fR (\fBRCTL_GLOBAL_INFINITE\fR) flag is defined for this +resource control. An \fBinf\fR value has an infinite quantity. The value is +never enforced. Hence, as configured, both threshold quantities represent +infinite values that are never exceeded. +.SS "Resource Control Enforcement" +More than one resource control can exist on a resource. A resource control can +exist at each containment level in the process model. If resource controls are +active on the same resource at different container levels, the smallest +container's control is enforced first. Thus, action is taken on +\fBprocess.max-cpu-time\fR before \fBtask.max-cpu-time\fR if both controls are +encountered simultaneously. +.SH ATTRIBUTES +See \fBattributes\fR(7) for a description of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Evolving +.TE + +.SH SEE ALSO +.BR prctl (1), +.BR setrctl (2), +.BR rctlblk_set_value (3C), +.BR libpool (3LIB), +.BR FSS (4), +.BR project (5), +.BR attributes (7), +.BR pooladm (8), +.BR poolcfg (8), +.BR projadd (8), +.BR projmod (8), +.BR rctladm (8) +.sp +.LP +\fISystem Administration Guide: Virtualization Using the Solaris Operating +System\fR diff --git a/usr/src/man/man7/security-flags.7 b/usr/src/man/man7/security-flags.7 new file mode 100644 index 0000000000..6ffd80ea9e --- /dev/null +++ b/usr/src/man/man7/security-flags.7 @@ -0,0 +1,115 @@ +.\" +.\" 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, Richard Lowe. +.\" +.TH "SECURITY-FLAGS" "7" "June 6, 2016" +.SH "NAME" +\fBsecurity-flags\fR - process security flags +.SH "DESCRIPTION" +Each process on an illumos system has an associated set of security-flags +which describe additional per-process security and exploit mitigation +features which are enabled for that process. +.P +There are four sets of these flags for each process, the effective set +(abbreviated \fIE\fR) are the set which currently apply to the process and are +immutable. The inheritable set (abbreviated \fII\fR) are the flags which will +become effective the next time the process calls one of the \fBexec(2)\fR +family of functions, and will be inherited as both the effective and +inheritable sets by any child processes. The upper set (abbreviated \fIU\fR) +specify the maximal flags that a process can have in its inheritable set. The +lower set (abbreviated \fIL\fR) specify the minimal amount of flags that a +process must have in its inheritable set. The inheritable set may be changed +at any time, subject to permissions and the lower and upper sets. +.P +To change the security-flags of a process one must have both permissions +equivalent to those required to send a signal to the process and have the +\fBPRIV_PROC_SECFLAGS\fR privilege. +.P +Currently available features are: + +.sp +.ne 2 +.na +Address Space Layout Randomisation (\fBASLR\fR) +.ad +.RS 11n +The base addresses of the stack, heap and shared library (including +\fBld.so\fR) mappings are randomised, the bases of mapped regions other than +those using \fBMAP_FIXED\fR are randomised. +.P +Currently, executable base addresses are \fInot\fR randomised, due to which +the mitigation provided by this feature is currently limited. +.P +This flag may also be enabled by the presence of the \fBDT_SUNW_ASLR\fR +dynamic tag in the \fB.dynamic\fR section of the executable file. If this +tag has a value of 1, ASLR will be enabled. If the flag has a value of +\fB0\fR ASLR will be disabled. If the tag is not present, the value of the +ASLR flag will be inherited as normal. +.RE + +.sp +.ne 2 +.na +Forbid mappings at NULL (\fBFORBIDNULLMAP\fR) +.ad +.RS 11n +Mappings with an address of 0 are forbidden, and return EINVAL rather than +being honored. +.RE + +.sp +.ne 2 +.na +Make the userspace stack non-executable (\fBNOEXECSTACK\fR) +.ad +.RS 11n +The stack will be mapped without executable permission, and attempts to +execute it will fault. +.RE + +System default security-flags are configured via properties on the +\fBsvc:/system/process-security\fR service, which contains a boolean property +per-flag in the \fBdefault\fR, \fBlower\fR and \fBupper\fR, property groups. +The value indicates the setting of the flag, flags with no value take their +defaults. For example, to enable ASLR by default you would execute the +following commands: +.sp +.in +2 +.nf +# svccfg -s svc:/system/process-security setprop default/aslr = true +.fi +.in -2 +.sp +.P +To restore the setting to the defaults you would execute: +.sp +.in +2 +.nf +# svccfg -s svc:/system/process-security delpropvalue default/aslr true +.fi +.in -2 +.sp +.P +This can be done by any user with the \fBsolaris.smf.value.process-security\fR +authorization. +.P +Since security-flags are strictly inherited, this will not take effect until +the system or zone is next booted. + +.SH "SEE ALSO" +.BR psecflags (1), +.BR brk (2), +.BR exec (2), +.BR mmap (2), +.BR mmapobj (2), +.BR privileges (7), +.BR rbac (7), +.BR svccfg (8) diff --git a/usr/src/man/man7/smf.7 b/usr/src/man/man7/smf.7 new file mode 100644 index 0000000000..c25a108a97 --- /dev/null +++ b/usr/src/man/man7/smf.7 @@ -0,0 +1,510 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH SMF 7 "Jul 6, 2009" +.SH NAME +smf \- service management facility +.SH DESCRIPTION +.sp +.LP +The Solaris service management facility defines a programming model for +providing persistently running applications called \fIservices\fR. The facility +also provides the infrastructure in which to run services. A service can +represent a running application, the software state of a device, or a set of +other services. Services are represented in the framework by \fIservice +instance\fR objects, which are children of service objects. Instance objects +can inherit or override the configuration of the parent service object, which +allows multiple service instances to share configuration information. All +service and instance objects are contained in a \fIscope\fR that represents a +collection of configuration information. The configuration of the local Solaris +instance is called the "localhost" scope, and is the only currently supported +scope. +.sp +.LP +Each service instance is named with a fault management resource identifier +(FMRI) with the scheme \fBsvc:\fR. For example, the \fBsyslogd\fR(8) daemon +started at system startup is the default service instance named: +.sp +.in +2 +.nf +svc://localhost/system/system-log:default +svc:/system/system-log:default +system/system-log:default +.fi +.in -2 + +.sp +.LP +Many commands also allow FMRI abbreviations. See the \fBsvcs\fR(1) man page for +one such example. +.sp +.LP +In the above example, 'default' is the name of the instance +and 'system/system-log' is the service name. Service names can comprise multiple +components separated by slashes (/). All components, except the last, compose +the \fIcategory\fR of the service. Site-specific services should be named with +a category beginning with 'site'. +.sp +.LP +A service instance is either enabled or disabled. All services can be enabled +or disabled with the \fBsvcadm\fR(8) command. +.sp +.LP +The list of managed service instances on a system can be displayed with the +\fBsvcs\fR(1) command. +.SS "Dependencies" +.sp +.LP +Service instances can have dependencies on a set of \fBentities\fR which can +include services and files. Dependencies govern when the service is started and +automatically stopped. When the dependencies of an enabled service are not +satisfied, the service is kept in the offline state. When its dependencies are +satisfied, the service is started. If the start is successful, the service is +transitioned to the online state. +.sp +.LP +Whether a dependency is satisfied is determined by its \fBgrouping\fR: +.sp +.ne 2 +.na +\fB\fBrequire_all\fR\fR +.ad +.RS 16n +Satisfied when all cited services are running (online or degraded), or when all +indicated files are present. +.RE + +.sp +.ne 2 +.na +\fB\fBrequire_any\fR\fR +.ad +.RS 16n +Satisfied when one of the cited services is running (online or degraded), or +when at least one of the indicated files is present. +.RE + +.sp +.ne 2 +.na +\fB\fBoptional_all\fR\fR +.ad +.RS 16n +Satisfied if the cited services are running (online or degraded) or do not run +without administrative action (disabled, maintenance, not present, or offline +waiting for dependencies which do not start without administrative action). +.RE + +.sp +.ne 2 +.na +\fB\fBexclude_all\fR\fR +.ad +.RS 16n +Satisfied when all of the cited services are disabled, in the maintenance +state, or when cited services or files are not present. +.RE + +.sp +.LP +Once running (online or degraded), if a service cited by a \fBrequire_all\fR, +\fBrequire_any\fR, or \fBoptional_all\fR dependency is stopped or refreshed, +the SMF considers why the service was stopped and the \fBrestart_on\fR +attribute of the dependency to decide whether to stop the service. +.sp +.in +2 +.nf + | restart_on value +event | none error restart refresh +-------------------+------------------------------ +stop due to error | no yes yes yes +non-error stop | no no yes yes +refresh | no no no yes +.fi +.in -2 + +.sp +.LP +A service is considered to have stopped due to an error if the service has +encountered a hardware error or a software error such as a core dump. For +\fBexclude_all\fR dependencies, the service is stopped if the cited service is +started and the \fBrestart_on\fR attribute is not \fBnone\fR. +.sp +.LP +The dependencies on a service can be listed with \fBsvcs\fR(1)\ or +\fBsvccfg\fR(8), and modified with \fBsvccfg\fR(8). +.SS "Restarters" +.sp +.LP +Each service is managed by a restarter. The master restarter, +\fBsvc.startd\fR(8) manages states for the entire set of service instances and +their dependencies. The master restarter acts on behalf of its services and on +delegated restarters that can provide specific execution environments for +certain application classes. For instance, \fBinetd\fR(8) is a delegated +restarter that provides its service instances with an initial environment +composed of a network connection as input and output file descriptors. Each +instance delegated to \fBinetd\fR(8) is in the online state. While the daemon +of a particular instance might not be running, the instance is available to +run. +.sp +.LP +As dependencies are satisfied when instances move to the online state, +\fBsvc.startd\fR(8) invokes start methods of other instances or directs the +delegated restarter to do so. These operations might overlap. +.sp +.LP +The current set of services and associated restarters can be examined using +\fBsvcs\fR(1). A description of the common configuration used by all restarters +is given in \fBsmf_restarter\fR(7). +.SS "Methods" +.sp +.LP +Each service or service instance must define a set of methods that start, stop, +and, optionally, refresh the service. See \fBsmf_method\fR(7) for a more +complete description of the method conventions for \fBsvc.startd\fR(8) and +similar \fBfork\fR(2)-\fBexec\fR(2) restarters. +.sp +.LP +Administrative methods, such as for the capture of legacy configuration +information into the repository, are discussed on the \fBsvccfg\fR(8) manual +page. +.sp +.LP +The methods for a service can be listed and modified using the \fBsvccfg\fR(8) +command. +.SS "States" +.sp +.LP +Each service instance is always in a well-defined state based on its +dependencies, the results of the execution of its methods, and its potential +contracts events. The following states are defined: +.sp +.ne 2 +.na +\fB\fBUNINITIALIZED\fR\fR +.ad +.RS 17n +This is the initial state for all service instances. Instances are moved to +maintenance, offline, or a disabled state upon evaluation by +\fBsvc.startd\fR(8) or the appropriate restarter. +.RE + +.sp +.ne 2 +.na +\fB\fBOFFLINE\fR\fR +.ad +.RS 17n +The instance is enabled, but not yet running or available to run. If restarter +execution of the service start method or the equivalent method is successful, +the instance moves to the online state. Failures might lead to a degraded or +maintenance state. Administrative action can lead to the uninitialized state. +.RE + +.sp +.ne 2 +.na +\fB\fBONLINE\fR\fR +.ad +.RS 17n +The instance is enabled and running or is available to run. The specific nature +of the online state is application-model specific and is defined by the +restarter responsible for the service instance. Online is the expected +operating state for a properly configured service with all dependencies +satisfied. Failures of the instance can lead to a degraded or maintenance +state. Failures of services on which the instance depends can lead to offline +or degraded states. +.RE + +.sp +.ne 2 +.na +\fB\fBDEGRADED\fR\fR +.ad +.RS 17n +The instance is enabled and running or available to run. The instance, however, +is functioning at a limited capacity in comparison to normal operation. +Failures of the instance can lead to the maintenance state. Failures of +services on which the instance depends can lead to offline or degraded states. +Restoration of capacity should result in a transition to the online state. +.RE + +.sp +.ne 2 +.na +\fB\fBMAINTENANCE\fR\fR +.ad +.RS 17n +The instance is enabled, but not able to run. Administrative action (through +\fBsvcadm clear\fR) is required to move the instance out of the maintenance +state. The maintenance state might be a temporarily reached state if an +administrative operation is underway. +.RE + +.sp +.ne 2 +.na +\fB\fBDISABLED\fR\fR +.ad +.RS 17n +The instance is disabled. Enabling the service results in a transition to the +offline state and eventually to the online state with all dependencies +satisfied. +.RE + +.sp +.ne 2 +.na +\fB\fBLEGACY-RUN\fR\fR +.ad +.RS 17n +This state represents a legacy instance that is not managed by the service +management facility. Instances in this state have been started at some point, +but might or might not be running. Instances can only be observed using the +facility and are not transferred into other states. +.RE + +.sp +.LP +States can also have transitions that result in a return to the originating +state. +.SS "Properties and Property Groups" +.sp +.LP +The dependencies, methods, delegated restarter, and instance state mentioned +above are represented as properties or property groups of the service or +service instance. A service or service instance has an arbitrary number of +property groups in which to store application data. Using property groups in +this way allows the configuration of the application to derive the attributes +that the repository provides for all data in the facility. The application can +also use the appropriate subset of the \fBservice_bundle\fR(5) DTD to represent +its configuration data within the framework. +.sp +.LP +Property lookups are composed. If a property group-property combination is not +found on the service instance, most commands and the high-level interfaces of +\fBlibscf\fR(3LIB) search for the same property group-property combination on +the service that contains that instance. This allows common configuration among +service instances to be shared. Composition can be viewed as an inheritance +relationship between the service instance and its parent service. +.sp +.LP +Properties are protected from modification by unauthorized processes. See +\fBsmf_security\fR(7). +.SS "General Property Group" +.sp +.LP +The \fBgeneral\fR property group applies to all service instances. It includes +the following properties: +.sp +.ne 2 +.na +\fBenabled (boolean)\fR +.ad +.RS 21n +Specifies whether the instance is enabled. If this property is not present on +an instance, SMF does not tell the instance's restarter about the existence of +the restarter. +.RE + +.sp +.ne 2 +.na +\fBrestarter (fmri)\fR +.ad +.RS 21n +The restarter for this service. See the Restarters section for more +information. If this property is unset, the default system restarter is used. +.RE + +.SS "Snapshots" +.sp +.LP +Historical data about each instance in the repository is maintained by the +service management facility. This data is made available as read-only snapshots +for administrative inspection and rollback. The following set of snapshot types +might be available: +.sp +.ne 2 +.na +\fB\fBinitial\fR\fR +.ad +.RS 15n +Initial configuration of the instance created by the administrator or produced +during package installation. +.RE + +.sp +.ne 2 +.na +\fB\fBlast_import\fR\fR +.ad +.RS 15n +Configuration as prescribed by the manifest of the service that is taken during +\fBsvccfg\fR(8) import operation. This snapshot provides a baseline for +determining property customization. +.RE + +.sp +.ne 2 +.na +\fB\fBprevious\fR\fR +.ad +.RS 15n +Current configuration captured when an administrative undo operation is +performed. +.RE + +.sp +.ne 2 +.na +\fB\fBrunning\fR\fR +.ad +.RS 15n +The running configuration of the instance. +.RE + +.sp +.ne 2 +.na +\fB\fBstart\fR\fR +.ad +.RS 15n +Configuration captured during a successful transition to the online state. +.RE + +.sp +.LP +The \fBsvccfg\fR(8) command can be used to interact with snapshots. +.SS "Special Property Groups" +.sp +.LP +Some property groups are marked as "non-persistent". These groups are not +backed up in snapshots and their content is cleared during system boot. Such +groups generally hold an active program state which does not need to survive +system restart. +.SS "Configuration Repository" +.sp +.LP +The current state of each service instance, as well as the properties +associated with services and service instances, is stored in a system +repository managed by \fBsvc.configd\fR(8). This repository is transactional +and able to provide previous versions of properties and property groups +associated with each service or service instance. +.sp +.LP +The repository for service management facility data is managed by +\fBsvc.configd\fR(8). +.SS "Service Bundles, Manifests, and Profiles" +.sp +.LP +The information associated with a service or service instance that is stored in +the configuration repository can be exported as XML-based files. Such XML +files, known as service bundles, are portable and suitable for backup purposes. +Service bundles are classified as one of the following types: +.sp +.ne 2 +.na +\fB\fBmanifests\fR\fR +.ad +.RS 13n +Files that contain the complete set of properties associated with a specific +set of services or service instances. +.RE + +.sp +.ne 2 +.na +\fB\fBprofiles\fR\fR +.ad +.RS 13n +Files that contain a set of service instances and values for the enabled +property (type \fBboolean\fR in the general property group) on each instance. +.sp +Profiles can also contain configuration values for properties in services and +instances. Template elements cannot be defined in a profile. +.RE + +.sp +.LP +Service bundles can be imported or exported from a repository using the +\fBsvccfg\fR(8) command. See \fBservice_bundle\fR(5) for a description of the +service bundle file format with guidelines for authoring service bundles. +.sp +.LP +A \fIservice archive\fR is an XML file that contains the description and +persistent properties of every service in the repository, excluding transient +properties such as service state. This service archive is basically a 'svccfg +export' for every service which is not limited to named services. +.SS "Milestones" +.sp +.LP +An \fBsmf\fR milestone is a service that aggregates a multiple service +dependencies. Usually, a milestone does nothing useful itself, but declares a +specific state of system-readiness on which other services can depend. One +example is the \fBname-services\fR milestone, which simply depends upon the +currently enabled name services. +.SS "Legacy Startup Scripts" +.sp +.LP +Startup programs in the \fB/etc/rc?.d\fR directories are executed as part of +the corresponding run-level milestone: +.sp +.ne 2 +.na +\fB\fB/etc/rcS.d\fR\fR +.ad +.RS 14n +milestone/single-user:default +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rc2.d\fR\fR +.ad +.RS 14n +milestone/multi-user:default +.RE + +.sp +.ne 2 +.na +\fB\fB/etc/rc3.d\fR\fR +.ad +.RS 14n +milestone/multi-user-server:default +.RE + +.sp +.LP +Execution of each program is represented as a reduced-functionality service +instance named by the program's path. These instances are held in a special +legacy-run state. +.sp +.LP +These instances do not have an enabled property (type \fBboolean\fR in the +general property group) and, generally, cannot be manipulated with the +\fBsvcadm\fR(8) command. No error diagnosis or restart is done for these +programs. +.SH SEE ALSO +.sp +.LP +.BR svcs (1), +.BR exec (2), +.BR fork (2), +.BR strftime (3C), +.BR libscf (3LIB), +.BR contract (5), +.BR service_bundle (5), +.BR smf_bootstrap (7), +.BR smf_method (7), +.BR smf_restarter (7), +.BR smf_security (7), +.BR inetd (8), +.BR svc.configd (8), +.BR svc.startd (8), +.BR svcadm (8), +.BR svccfg (8) diff --git a/usr/src/man/man7/smf_bootstrap.7 b/usr/src/man/man7/smf_bootstrap.7 new file mode 100644 index 0000000000..d48cf8b2ad --- /dev/null +++ b/usr/src/man/man7/smf_bootstrap.7 @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH SMF_BOOTSTRAP 7 "Sep 25, 2008" +.SH NAME +smf_bootstrap \- service management facility boot, packaging, and compatibility +behavior +.SH DESCRIPTION +.sp +.LP +The service management facility establishes conventions for delivering service +manifests, incorporating service manifest changes, describing service +configuration stability, using service configuration overrides, and the use of +service profiles. +.SS "Manifest Loading at Boot" +.sp +.LP +The \fBsvc:/system/manifest-import:default\fR service uses \fBsvccfg\fR(8) to +import certain manifest files from the \fB/var/svc/manifest\fR directory tree +into the service configuration repository. The service imports files that it +has not imported previously and those files which have changed since the last +time they were imported by the service. When a manifest is imported by the +service, a hash of the file that includes its contents is recorded in a +property group of the \fBsvc:/smf/manifest\fR service. The +\fBmanifest-import\fR service uses the hash to determine whether the file has +changed. See \fBsvccfg\fR(8) for information on the \fBsvccfg import\fR +behavior for services that already exist in the repository. +.SS "Manifest Handling During Packaging Operations" +.sp +.LP +Service manifests within packages should be identified with the class +\fBmanifest\fR. Class action scripts that install and remove service manifests +are included in the packaging subsystem. When \fBpkgadd\fR(8) is invoked, the +service manifest is imported. +.sp +.LP +When \fBpkgrm\fR(8) is invoked, instances in the manifest that are disabled +are deleted. Instances in the manifest that are online or degraded are disabled +first and then deleted. Any services in the manifest with no remaining +instances are also deleted. +.sp +.LP +If the \fB-R\fR option is supplied to \fBpkgadd\fR(8) or \fBpkgrm\fR(8), the +actions described in this section will be done when the system is next rebooted +with that alternate root path. +.SS "Stability Declarations" +.sp +.LP +Each service group and each property group delivered in a manifest should +declare a stability level based on \fBattributes\fR(7) definitions. With +knowledge of the stability level, an application developer can determine the +likelihood that feature development based on the existence or components of a +service or object is likely to remain functional across a release boundary. +.sp +.LP +In an \fBsmf\fR(7) context, the stability value also identifies the expected +scope of the changes to properties within the property group across a release +boundary for the service, which can include patches for that service. The +following two sections discuss this in more detail. +.SS "Property Overrides" +.sp +.LP +The \fBservice_bundle\fR(5) document type definition includes an override +attribute that is applicable to each property in a service manifest. If set to +\fBtrue\fR, the attribute instructs \fBsvccfg\fR(8) and other manifest import +tools to replace the current value of a property in the repository with the one +from the manifest. If the override attribute is absent or present but set to +\fBfalse\fR, the current value in the repository is preserved. +.sp +.LP +Property groups declared as Stable do not contain override attributes on +enclosed properties. Property groups declared as Evolving do so only to correct +an erroneous setting. Property groups declared as Unstable can contain +overrides on any property. The exception to this behavior is for the stability +property itself, which can be modified to identify incipient change to the +interface presented by the service. +.SS "Property Group Deletion" +.sp +.LP +The \fBservice_bundle\fR(5) document type definition includes a delete +attribute, applicable to each property group in a service manifest. If set to +\fBtrue\fR, the delete attribute instructs \fBsvccfg\fR(8) and other manifest +import tools to delete this property group from the repository. If the delete +attribute is absent or present but set to \fBfalse\fR, the property group in +the repository is preserved. +.sp +.LP +Property groups declared as Stable or Evolving are not deleted. Property groups +declared as Unstable can be deleted across any release boundary. +.SS "Profile Application" +.sp +.LP +The first time the existence of each of the three service profiles listed below +is detected, \fBsvc.startd\fR(8) automatically applies the profile. +.sp +.in +2 +.nf +/var/svc/profile/generic.xml +/var/svc/profile/platform.xml +/var/svc/profile/site.xml +.fi +.in -2 + +.sp +.LP +The \fBsvc:/smf/manifest\fR service is used in a similar fashion. +.sp +.LP +Additional service profiles that characterize the activation of various groups +of service instances might be present in \fB/var/svc/profile\fR. None of the +\fB/var/svc/profile\fR profiles are automatically applied to the repository. A +profile can be manually applied or re-applied using \fBsvccfg\fR(8). +.SH SEE ALSO +.sp +.LP +.BR libscf (3LIB), +.BR service_bundle (5), +.BR attributes (7), +.BR smf (7), +.BR smf_security (7), +.BR pkgadd (8), +.BR pkgrm (8), +.BR svc.startd (8), +.BR svcadm (8), +.BR svccfg (8) +.SH NOTES +.sp +.LP +The present version of \fBsmf\fR(7) does not support multiple repositories. diff --git a/usr/src/man/man7/smf_method.7 b/usr/src/man/man7/smf_method.7 new file mode 100644 index 0000000000..9f2b9fc243 --- /dev/null +++ b/usr/src/man/man7/smf_method.7 @@ -0,0 +1,601 @@ +'\" te +.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association. +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH SMF_METHOD 7 "February 25, 2019" +.SH NAME +smf_method \- service management framework conventions for methods +.SH DESCRIPTION +.LP +The class of services managed by \fBsvc.startd\fR(8) in the service management +framework, \fBsmf\fR(7), consists of applications that fit a simple +\fBfork\fR(2)-\fBexec\fR(2) model. The \fBsvc.startd\fR(8) master daemon and +other restarters support the \fBfork\fR(2)-\fBexec\fR(2) model, potentially +with additional capabilities. The \fBsvc.startd\fR(8) daemon and other +restarters require that the methods which activate, manipulate, or examine a +service instance follow the conventions described in this manual page. +.SS "Invocation form" +.LP +The form of a method invocation is not dictated by convention. In some cases, a +method invocation might consist of the direct invocation of the daemon or other +binary executable that provides the service. For cases in which an executable +script or other mediating executable is used, the convention recommends the +form: +.sp +.in +2 +.nf +/path/to/method_executable abbr_method_name +.fi +.in -2 + +.sp +.LP +The \fIabbr_method_name\fR used for the recommended form is a supported method +such as \fBstart\fR or \fBstop\fR. The set of methods supported by a restarter +is given on the related restarter page. The \fBsvc.startd\fR(8) daemon +supports \fBstart\fR, \fBstop\fR, and \fBrefresh\fR methods. +.sp +.LP +A restarter might define other kinds of methods beyond those referenced in this +page. The conventions surrounding such extensions are defined by the restarter +and might not be identical to those given here. +.SS "Environment Variables" +.LP +The restarter provides four environment variables to the method that determine +the context in which the method is invoked. +.sp +.ne 2 +.na +\fB\fBSMF_FMRI\fR\fR +.ad +.sp .6 +.RS 4n +The service fault management resource identifier (FMRI) of the instance for +which the method is invoked. +.RE + +.sp +.ne 2 +.na +\fB\fBSMF_METHOD\fR\fR +.ad +.sp .6 +.RS 4n +The full name of the method being invoked, such as \fBstart\fR or \fBstop\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBSMF_RESTARTER\fR\fR +.ad +.sp .6 +.RS 4n +The service FMRI of the restarter that invokes the method +.RE + +.sp +.ne 2 +.na +\fB\fBSMF_ZONENAME\fR\fR +.ad +.sp .6 +.RS 4n +The name of the zone in which the method is running. This can also be obtained +by using the \fBzonename\fR(1) command. +.RE + +.sp +.LP +These variables should be removed from the environment prior to the invocation +of any persistent process by the method. A convenience shell function, +\fBsmf_clear_env\fR, is given for service authors who use Bourne-compatible +shell scripting to compose service methods in the include file described below. +.sp +.LP +The method context can cause other environment variables to be set as described +below. +.SS "Method Definition" +.LP +A method is defined minimally by three properties in a propertygroup of type +\fBmethod\fR. +.sp +.LP +These properties are: +.sp +.ne 2 +.na +\fBexec (\fIastring\fR)\fR +.ad +.RS 27n +Method executable string. +.RE + +.sp +.ne 2 +.na +\fBtimeout_seconds (\fIcount\fR)\fR +.ad +.RS 27n +Number of seconds before method times out. See the \fBTimeouts\fR section for +more detail. +.RE + +.sp +.ne 2 +.na +\fBtype (\fIastring\fR)\fR +.ad +.RS 27n +Method type. Currently always set to \fBmethod\fR. +.RE + +.sp +.LP +A Method Context can be defined to further refine the execution environment of +the method. See the \fBMethod Context\fR section for more information. +.SS "Method Tokens" +.LP +When defined in the \fBexec\fR string of the method by the restarter +\fBsvc.startd\fR, a set of tokens are parsed and expanded with appropriate +value. Other restarters might not support method tokens. The delegated +restarter for inet services, \fBinetd\fR(8), does not support the following +method expansions. +.sp +.ne 2 +.na +\fB\fB%%\fR\fR +.ad +.sp .6 +.RS 4n +% +.RE + +.sp +.ne 2 +.na +\fB\fB%r\fR\fR +.ad +.sp .6 +.RS 4n +Name of the restarter, such as \fBsvc.startd\fR +.RE + +.sp +.ne 2 +.na +\fB\fB%m\fR\fR +.ad +.sp .6 +.RS 4n +The full name of the method being invoked, such as \fBstart\fR or \fBstop\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB%s\fR\fR +.ad +.sp .6 +.RS 4n +Name of the service +.RE + +.sp +.ne 2 +.na +\fB\fB%i\fR\fR +.ad +.sp .6 +.RS 4n +Name of the instance +.RE + +.sp +.ne 2 +.na +\fB\fB\fR\fB%f\fR\fR +.ad +.sp .6 +.RS 4n +FMRI of the instance +.RE + +.sp +.ne 2 +.na +\fB\fB%{prop[:,]}\fR\fR +.ad +.sp .6 +.RS 4n +Value(s) of a property. The \fBprop\fR might be a property FMRI, a property +group name and a property name separated by a \fB/\fR, or a property name in +the \fBapplication\fR property group. These values can be followed by a \fB,\fR +(comma) or \fB:\fR (colon). If present, the separators are used to separate +multiple values. If absent, a space is used. The following shell metacharacters +encountered in string values are quoted with a \ (backslash): +.sp +.in +2 +.nf +; & ( ) | ^ < > newline space tab \ " ' +.fi +.in -2 + +An invalid expansion constitutes method failure. +.RE + +.sp +.LP +Two explicit tokens can be used in the place of method commands. +.sp +.ne 2 +.na +\fB\fB:kill [-signal]\fR\fR +.ad +.sp .6 +.RS 4n +Sends the specified signal, which is \fBSIGTERM\fR by default, to all processes +in the primary instance contract. Always returns \fBSMF_EXIT_OK\fR. This token +should be used to replace common \fBpkill\fR invocations. +.RE + +.sp +.ne 2 +.na +\fB\fB:true\fR\fR +.ad +.sp .6 +.RS 4n +Always returns \fBSMF_EXIT_OK\fR. This token should be used for methods that +are required by the restarter but which are unnecessary for the particular +service implementation. +.RE + +.SS "Exiting and Exit Status" +.LP +The required behavior of a start method is to delay exiting until the service +instance is ready to answer requests or is otherwise functional. +.sp +.LP +The following exit status codes are defined in \fB<libscf.h>\fR and in the +shell support file. +.sp + +.sp +.TS +l l l +l l l . +\fBSMF_EXIT_OK\fR \fB0\fR T{ +Method exited, performing its operation successfully. +T} +\fBSMF_EXIT_NODAEMON\fR \fB94\fR T{ +Method exited successfully but purposefully leaves no processes remaining in +the contract; it should be treated as if it had a transient service model. +T} +\fBSMF_EXIT_ERR_FATAL\fR \fB95\fR T{ +Method failed fatally and is unrecoverable without administrative intervention. +T} +\fBSMF_EXIT_ERR_CONFIG\fR \fB96\fR T{ +Unrecoverable configuration error. A common condition that returns this exit status is the absence of required configuration files for an enabled service instance. +T} +\fBSMF_EXIT_ERR_NOSMF\fR \fB99\fR T{ +Method has been mistakenly invoked outside the \fBsmf\fR(7) facility. Services that depend on \fBsmf\fR(7) capabilities should exit with this status value. +T} +\fBSMF_EXIT_ERR_PERM\fR \fB100\fR T{ +Method requires a form of permission such as file access, privilege, authorization, or other credential that is not available when invoked. +T} +\fBSMF_EXIT_ERR_OTHER\fR \fBnon-zero\fR T{ +Any non-zero exit status from a method is treated as an unknown error. A series of unknown errors can be diagnosed as a fault by the restarter or on behalf of the restarter. +T} +.TE + +.sp +.LP +Use of a precise exit code allows the responsible restarter to categorize an +error response as likely to be intermittent and worth pursuing restart or +permanent and request administrative intervention. +.SS "Timeouts" +.LP +Each method can have an independent timeout, given in seconds. The choice of a +particular timeout should be based on site expectations for detecting a method +failure due to non-responsiveness. Sites with replicated filesystems or other +failover resources can elect to lengthen method timeouts from the default. +Sites with no remote resources can elect to shorten the timeouts. Method +timeout is specified by the \fBtimeout_seconds\fR property. +.sp +.LP +If you specify \fB0 timeout_seconds\fR for a method, it declares to the +restarter that there is no timeout for the service. This setting is not +preferred, but is available for services that absolutely require it. +.sp +.LP +\fB-1 timeout_seconds\fR is also accepted, but is a deprecated specification. +.SS "Shell Programming Support" +.LP +A set of environment variables that define the above exit status values is +provided with convenience shell functions in the file +\fB/lib/svc/share/smf_include.sh\fR. This file is a Bourne shell script +suitable for inclusion via the source operator in any Bourne-compatible shell. +.sp +.LP +To assist in the composition of scripts that can serve as SMF methods as well +as \fB/etc/init.d\fR scripts, the \fBsmf_present()\fR shell function is +provided. If the \fBsmf\fR(7) facility is not available, \fBsmf_present()\fR +returns a non-zero exit status. +.sp +.LP +One possible structure for such a script follows: +.sp +.in +2 +.nf +if smf_present; then + # Shell code to run application as managed service + .... + + smf_clear_env +else + # Shell code to run application as /etc/init.d script + .... +fi +.fi +.in -2 + +.sp +.LP +This example shows the use of both convenience functions that are provided. +.SS "Method Context" +.LP +The service management facility offers a common mechanism set the context in +which the \fBfork\fR(2)-\fBexec\fR(2) model services execute. +.sp +.LP +The desired method context should be provided by the service developer. All +service instances should run with the lowest level of privileges possible to +limit potential security compromises. +.sp +.LP +A method context can contain the following properties: +.sp +.ne 2 +.na +\fB\fBuse_profile\fR\fR +.ad +.sp .6 +.RS 4n +A boolean that specifies whether the profile should be used instead of the +\fBuser\fR, \fBgroup\fR, \fBprivileges\fR, and \fBlimit_privileges\fR +properties. +.RE + +.sp +.ne 2 +.na +\fBenvironment\fR +.ad +.sp .6 +.RS 4n +Environment variables to insert into the environment of the method, in the form +of a number of \fBNAME=value\fR strings. +.RE + +.sp +.ne 2 +.na +\fB\fBprofile\fR\fR +.ad +.sp .6 +.RS 4n +The name of an RBAC (role-based access control) profile which, along with the +method executable, identifies an entry in \fBexec_attr\fR(5). +.RE + +.sp +.ne 2 +.na +\fB\fBuser\fR\fR +.ad +.sp .6 +.RS 4n +The user ID in numeric or text form. +.RE + +.sp +.ne 2 +.na +\fB\fBgroup\fR\fR +.ad +.sp .6 +.RS 4n +The group ID in numeric or text form. +.RE + +.sp +.ne 2 +.na +\fB\fBsupp_groups\fR\fR +.ad +.sp .6 +.RS 4n +An optional string that specifies the supplemental group memberships by ID, in +numeric or text form. +.RE + +.sp +.ne 2 +.na +\fB\fBprivileges\fR\fR +.ad +.sp .6 +.RS 4n +An optional string specifying the privilege set as defined in +\fBprivileges\fR(7). +.RE + +.sp +.ne 2 +.na +\fB\fBlimit_privileges\fR\fR +.ad +.sp .6 +.RS 4n +An optional string specifying the limit privilege set as defined in +\fBprivileges\fR(7). +.RE + +.sp +.ne 2 +.na +\fB\fBworking_directory\fR\fR +.ad +.sp .6 +.RS 4n +The home directory from which to launch the method. \fB:home\fR can be used as +a token to indicate the home directory of the user whose \fBuid\fR is used to +launch the method. If the property is unset, \fB:home\fR is used. +.RE + +.sp +.ne 2 +.na +\fB\fBsecurity_flags\fR\fR +.ad +.sp .6 +.RS 4n +The security flags to apply when launching the method. See \fBsecurity-flags\fR(7). +.sp +.LP +The "default" keyword specifies those flags specified in +\fBsvc:/system/process-security\fR. The "all" keyword enables all flags, the +"none" keyword enables no flags. The "current" keyword specifies the current +flags. Flags may be added by specifying their name (optionally preceded +by '+'), and removed by preceding their name with '-'). +.sp +.LP +Use of "all" has associated risks, as future versions of the system may +include further flags which may harm poorly implemented software. +.RE + +.sp +.ne 2 +.na +\fB\fBcorefile_pattern\fR\fR +.ad +.sp .6 +.RS 4n +An optional string that specifies the corefile pattern to use for the service, +as per \fBcoreadm\fR(8). Most restarters supply a default. Setting this +property overrides local customizations to the global core pattern. +.RE + +.sp +.ne 2 +.na +\fB\fBproject\fR\fR +.ad +.sp .6 +.RS 4n +The project ID in numeric or text form. \fB:default\fR can be used as a token +to indicate a project identified by \fBgetdefaultproj\fR(3PROJECT) for the user +whose \fBuid\fR is used to launch the method. +.RE + +.sp +.ne 2 +.na +\fB\fBresource_pool\fR\fR +.ad +.sp .6 +.RS 4n +The resource pool name on which to launch the method. \fB:default\fR can be +used as a token to indicate the pool specified in the \fBproject\fR(5) entry +given in the \fBproject\fR attribute above. +.RE + +.sp +.LP +The method context can be set for the entire service instance by specifying a +\fBmethod_context\fR property group for the service or instance. A method might +override the instance method context by providing the method context properties +on the method property group. +.sp +.LP +Invalid method context settings always lead to failure of the method, with the +exception of invalid environment variables that issue warnings. +.sp +.LP +In addition to the context defined above, many \fBfork\fR(2)-\fBexec\fR(2) +model restarters also use the following conventions when invoking executables +as methods: +.sp +.ne 2 +.na +\fBArgument array\fR +.ad +.sp .6 +.RS 4n +The arguments in \fBargv[]\fR are set consistently with the result \fB/bin/sh +-c\fR of the \fBexec\fR string. +.RE + +.sp +.ne 2 +.na +\fBFile descriptors\fR +.ad +.sp .6 +.RS 4n +File descriptor \fB0\fR is \fB/dev/null\fR. File descriptors \fB1\fR and +\fB2\fR are recommended to be a per-service log file. +.RE + +.SH FILES +.ne 2 +.na +\fB\fB/lib/svc/share/smf_include.sh\fR\fR +.ad +.sp .6 +.RS 4n +Definitions of exit status values. +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/include/libscf.h\fR\fR +.ad +.sp .6 +.RS 4n +Definitions of exit status codes. +.RE + +.SH SEE ALSO +.LP +.BR zonename (1), +.BR exec (2), +.BR fork (2), +.BR getdefaultproj (3PROJECT), +.BR exec_attr (5), +.BR project (5), +.BR service_bundle (5), +.BR attributes (7), +.BR privileges (7), +.BR rbac (7), +.BR security-flags (7), +.BR smf (7), +.BR smf_bootstrap (7), +.BR zones (7), +.BR coreadm (8), +.BR inetd (8), +.BR svc.startd (8), +.BR svccfg (8) +.SH NOTES +.LP +The present version of \fBsmf\fR(7) does not support multiple repositories. +.sp +.LP +When a service is configured to be started as root but with privileges +different from \fBlimit_privileges\fR, the resulting process is privilege +aware. This can be surprising to developers who expect \fBseteuid(<non-zero +UID>)\fR to reduce privileges to basic or less. diff --git a/usr/src/man/man7/smf_restarter.7 b/usr/src/man/man7/smf_restarter.7 new file mode 100644 index 0000000000..2b21d96f25 --- /dev/null +++ b/usr/src/man/man7/smf_restarter.7 @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2019 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 SMF_RESTARTER 7 "Dec 11, 2019" +.SH NAME +smf_restarter \- service management facility conventions for restarters +.SH DESCRIPTION +All service instances in the service management facility must be managed by a +restarter. This manual page describes configuration, functionality, and +reporting characteristics that are common to all restarters in the framework. +Characteristics specific to a particular restarter are described in the +restarter's man page. +.sp +.LP +For each managed service, a restarter relies on retrieving properties on the +service instance to determine configuration. The restarter manages a set of +property groups to communicate the current disposition of a service with +display tools such as \fBsvcs\fR(1). +.SS "Service Configuration" +The common restarter configuration for all services is captured in the +\fBgeneral\fR property group. This group includes the following required and +optional property settings. +.sp +.ne 2 +.na +\fB\fBenabled\fR\fR +.ad +.RS 19n +This is a required property. If set, the restarter of an instance attempts to +maintain availability of the service. +.RE + +.sp +.ne 2 +.na +\fB\fBrestarter\fR\fR +.ad +.RS 19n +This is an optional property that allows the specification of an alternate +restarter to manage the service instance. If the restarter property is empty or +absent, the restarter defaults to \fBsvc.startd\fR(8). +.RE + +.sp +.ne 2 +.na +\fB\fBsingle_instance\fR\fR +.ad +.RS 19n +This is an optional property. When set, only one instance of the service is +allowed to transition to an online or degraded status at any time. Note that no +known implementation honours this setting, and it should be considered obsolete. +.RE + +.SS "Service Reporting" +All restarters report status using the \fBrestarter\fR property group, which +includes the following properties: +.sp +.ne 2 +.na +\fB\fBnext_state\fR\fR +.ad +.RS 19n +The current state and next state, if currently in transition, for instances +stored in these properties. See \fBsmf\fR(7) for a description of the potential +states. +.RE + +.sp +.ne 2 +.na +\fB\fBauxiliary_state\fR\fR +.ad +.RS 19n +An astring with no spaces that contains a precise term to describe the full +restarter-specific state in combination with the restarter state property. The +auxiliary state cannot always be set and is always cleared during transition +out of any state. Each restarter must define the precise list of auxiliary +states it uses. +.RE + +.sp +.ne 2 +.na +\fB\fBstate_timestamp\fR\fR +.ad +.RS 19n +The time when the current state was reached. +.RE + +.sp +.ne 2 +.na +\fB\fBcontract\fR\fR +.ad +.RS 19n +The primary process contract ID, if any, under which the service instance is +executing. +.RE + +.SH SEE ALSO +.BR svcs (1), +.BR service_bundle (5), +.BR smf (7), +.BR smf_method (7), +.BR svc.startd (8) diff --git a/usr/src/man/man7/smf_security.7 b/usr/src/man/man7/smf_security.7 new file mode 100644 index 0000000000..78f03f2eb4 --- /dev/null +++ b/usr/src/man/man7/smf_security.7 @@ -0,0 +1,234 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH SMF_SECURITY 7 "May 13, 2017" +.SH NAME +smf_security \- service management facility security behavior +.SH DESCRIPTION +.LP +The configuration subsystem for the service management facility, \fBsmf\fR(7), +requires privilege to modify the configuration of a service. Privileges are +granted to a user by associating the authorizations described below to the user +through \fBuser_attr\fR(5) and \fBprof_attr\fR(5). See \fBrbac\fR(7). +.sp +.LP +The following authorization is used to manipulate services and service +instances. +.sp +.ne 2 +.na +\fB\fBsolaris.smf.modify\fR\fR +.ad +.RS 22n +Authorized to add, delete, or modify services, service instances, or their +properties, and to read protected property values. +.RE + +.SS "Property Group Authorizations" +.LP +The \fBsmf\fR(7) configuration subsystem associates properties with each +service and service instance. Related properties are grouped. Groups can +represent an execution method, credential information, application data, or +restarter state. The ability to create or modify property groups can cause +\fBsmf\fR(7) components to perform actions that can require operating system +privilege. Accordingly, the framework requires appropriate authorization to +manipulate property groups. +.sp +.LP +Each property group has a type corresponding to its purpose. The core property +group types are \fBmethod\fR, \fBdependency\fR, \fBapplication\fR, and +\fBframework\fR. Additional property group types can be introduced, provided +they conform to the extended naming convention in \fBsmf\fR(7). The following +basic authorizations, however, apply only to the core property group types: +.sp +.ne 2 +.na +\fB\fBsolaris.smf.modify.method\fR\fR +.ad +.sp .6 +.RS 4n +Authorized to change values or create, delete, or modify a property group of +type \fBmethod\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBsolaris.smf.modify.dependency\fR\fR +.ad +.sp .6 +.RS 4n +Authorized to change values or create, delete, or modify a property group of +type \fBdependency\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBsolaris.smf.modify.application\fR\fR +.ad +.sp .6 +.RS 4n +Authorized to change values, read protected values, and create, delete, or +modify a property group of type application. +.RE + +.sp +.ne 2 +.na +\fB\fBsolaris.smf.modify.framework\fR\fR +.ad +.sp .6 +.RS 4n +Authorized to change values or create, delete, or modify a property group of +type \fBframework\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBsolaris.smf.modify\fR\fR +.ad +.sp .6 +.RS 4n +Authorized to add, delete, or modify services, service instances, or their +properties, and to read protected property values. +.RE + +.sp +.LP +Property group-specific authorization can be specified by properties contained +in the property group. +.sp +.ne 2 +.na +\fB\fBmodify_authorization\fR\fR +.ad +.RS 24n +Authorizations allow the addition, deletion, or modification of properties +within the property group, and the retrieval of property values from the +property group if protected. +.RE + +.sp +.ne 2 +.na +\fB\fBvalue_authorization\fR\fR +.ad +.RS 24n +Authorizations allow changing the values of any property of the property group +except \fBmodify_authorization\fR, and the retrieval of any property values +except modify_authorization from the property group if protected. +.RE + +.sp +.ne 2 +.na +\fB\fBread_authorization\fR\fR +.ad +.RS 24n +Authorizations allow the retrieval of property values within the property +group. The presence of a string-valued property with this name identifies the +containing property group as protected. This property has no effect on property +groups of types other than application. See \fBProtected Property Groups\fR. +.RE + +.sp +.LP +The above authorization properties are only used if they have type +\fBastring\fR. If an instance property group does not have one of the +properties, but the instance's service has a property group of the same name +with the property, its values are used. +.SS "Protected Property Groups" +.LP +Normally, all property values in the repository can be read by any user without +explicit authorization. Property groups of non-framework types can be used to +store properties with values that require protection. They must not be revealed +except upon proper authorization. A property group's status as protected is +indicated by the presence of a string-valued \fBread_authorization\fR property. +If this property is present, the values of all properties in the property group +is retrievable only as described in \fBProperty Group Authorizations\fR. +.sp +.LP +Administrative domains with policies that prohibit backup of data considered +sensitive should exclude the SMF repository databases from their backups. In +the face of such a policy, non-protected property values can be backed up by +using the \fBsvccfg\fR(8) archive command to create an archive of the +repository without protected property values. +.SS "Service Action Authorization" +.LP +Certain actions on service instances can result in service interruption or +deactivation. These actions require an authorization to ensure that any denial +of service is a deliberate administrative action. Such actions include a +request for execution of the refresh or restart methods, or placement of a +service instance in the maintenance or other non-operational state. The +following authorization allows such actions to be requested: +.sp +.ne 2 +.na +\fB\fBsolaris.smf.manage\fR\fR +.ad +.RS 22n +Authorized to request restart, refresh, or other state modification of any +service instance. +.RE + +.sp +.LP +In addition, the \fBgeneral/action_authorization\fR property can specify +additional authorizations that permit service actions to be requested for that +service instance. The \fBsolaris.smf.manage\fR authorization is required to +modify this property. +.SS "Defined Rights Profiles" +.LP +Two rights profiles are included that offer grouped authorizations for +manipulating typical \fBsmf\fR(7) operations. +.sp +.ne 2 +.na +\fBService Management\fR +.ad +.RS 22n +A service manager can manipulate any service in the repository in any way. It +corresponds to the \fBsolaris.smf.manage\fR and \fBsolaris.smf.modify\fR +authorizations. +.RE + +.sp +.ne 2 +.na +\fBService Operator\fR +.ad +.RS 22n +A service operator has the ability to enable or disable any service instance on +the system, as well as request that its restart or refresh method be executed. +It corresponds to the \fBsolaris.smf.manage\fR and +\fBsolaris.smf.modify.framework\fR authorizations. +.sp +Sites can define additional rights profiles customized to their needs. +.RE + +.SS "Remote Repository Modification" +.LP +Remote repository servers can deny modification attempts due to additional +privilege checks. See NOTES. +.SH SEE ALSO +.LP +.BR auths (1), +.BR profiles (1), +.BR prof_attr (5), +.BR user_attr (5), +.BR rbac (7), +.BR smf (7), +.BR svccfg (8) +.SH NOTES +.LP +The present version of \fBsmf\fR(7) does not support remote repositories. +.sp +.LP +When a service is configured to be started as root but with privileges +different from \fBlimit_privileges\fR, the resulting process is privilege +aware. This can be surprising to developers who expect \fBseteuid(<non-zero +UID>)\fR to reduce privileges to basic or less. diff --git a/usr/src/man/man7/smf_template.7 b/usr/src/man/man7/smf_template.7 new file mode 100644 index 0000000000..9f68952666 --- /dev/null +++ b/usr/src/man/man7/smf_template.7 @@ -0,0 +1,806 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH SMF_TEMPLATE 7 "Nov 10, 2008" +.SH NAME +smf_template \- service management framework support for service metadata +.SH DESCRIPTION +.sp +.LP +Templates are defined by service developers to describe metadata about a +service in general or individual configuration properties on a service, +including human-consumable descriptions as well as definitions of valid +configuration. +.sp +.LP +Administrators are provided access to templates through SMF commands that +describe configuration values and validate configuration against templates. +.sp +.LP +Tool developers can use templates to provide more helpful user interfaces for +service configuration. +.SS "Template Data" +.sp +.LP +Service metadata is defined in the template as part of the service manifest. +.SS "Consuming Template Data" +.sp +.LP +The \fBsvcs -lv\fR and \fBsvccfg describe\fR commands can be used to access +metadata about properties in a human-readable format. +.sp +.LP +\fBsvccfg\fR(8)'s \fBvalidate\fR subcommand can be used to validate a service +instance or manifest against template data. A set of \fBlibscf\fR(3LIB) +interfaces is available to access template data. +.SS "Template Definition" +.sp +.LP +The sole interface to define templates is the service manifest. +.sp +.LP +Service authors should provide template metadata including \fBcommon_names\fR, +\fBdescriptions\fR, \fBchoices\fR and \fBconstraints\fR for service-specific +property groups and properties which they introduce. At a minimum, service +authors must provide descriptions for property groups and properties in the C +locale. Service authors should not provide template metadata for +framework-delivered property groups such as methods and dependencies. +.sp +.LP +See the \fBEXAMPLES\fR section for an example of authoring a template +definition for a service. +.SS "Template Composition" +.sp +.LP +All template interfaces search for template data about a property group first +on the instance, then on the service, then on the service's restarter, and +finally globally. +.sp +.LP +A property group template is defined by its author to apply to a specific +instance, to a service and all of its instances, to a restarter's delegates, or +globally. A typical service author defines the template on an instance or on a +service. A template defined on an instance is applied to that instance only, +and can override a template for that property group defined on the service. A +template defined on the service is applied to all instances of that service. +.sp +.LP +Restarter authors can define templates in their manifest that apply to any +service which uses their restarter, which is also known as a \fBdelegate\fR. +SMF framework authors have defined templates for property groups with +well-known meanings to the entire SMF framework in the manifest for +\fBsvc:/system/svc/global\fR. +.sp +.LP +Templates defined globally or by the restarter and re-defined by the service or +instance are flagged as a validation error. Service authors can avoid these +errors by creating templates only for property groups specific to their service +and not consumed by the SMF framework. +.sp +.LP +Property group templates can also be wildcarded by name or type. Only the most +specific template definition applicable to a property group is honored. +.SS "Template Details" +.SS "Service and Instance Templates" +.sp +.LP +The \fBtemplate\fR element defines the start of a template block. All further +definitions below can be included in a template block. A \fBtemplate\fR element +can be contained in either a \fBservice\fR or \fBinstance\fR element. If it is +contained in the \fBservice\fR element, it applies to the service and all +instances of that service. If it is contained in the \fBinstance\fR element, it +applies to only that instance of the service. +.sp +.LP +Whenever possible, we recommend defining the template data for the entire +service. +.sp +.in +2 +.nf +<service ... > + <template> + </template> +</service> +.fi +.in -2 + +.SS "Service and Instance Common Names" +.sp +.LP +The entire service or instance can define a common name to describe the purpose +of the service/instance. +.sp +.in +2 +.nf +<template> + <common_name> + <loctext xml:lang='C'>console login</loctext> + </common_name> +<template> +.fi +.in -2 + +.sp +.LP +\fIcommon_name\fR is a free-form string, but is intended to be used as a label +in a GUI or CLI. +.sp +.LP +The following guidelines are recommended: +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A word or two is usually most appropriate. Limit the name to under 40 +characters. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be clear. The service, property group, or property name might not be helpful +for humans, but \fIcommon_name\fR should help clarify the purpose of the +entity. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should +not contain clauses or phrases. Punctuation should only be present to meet +trademark requirements. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Capital letters must be used only for acronyms or proper names. For locales +other than English, use appropriate capitalization for a sentence fragment. +.RE +.SS "Service and Instance Descriptions" +.sp +.LP +The description element contains a longer description of the property group, +suitable for a status line or a tool-tip: +.sp +.in +2 +.nf +<template> + <description> + <loctext xml:lang='C'>Provide the text login prompt on console. + </lcotext> + </description> +<template> +.fi +.in -2 + +.sp +.LP +\fIdescription\fR Guidelines +.RS +4 +.TP +.ie t \(bu +.el o +Use proper grammar. \fIdescription\fR is a sentence meant to be read by humans. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A few sentences are usually most appropriate. +.RE +.SS "Documentation" +.sp +.LP +Documentation for this service can be defined explicitly, so that when the +service is experiencing issues, or a consumer of the service wants more +information on it, they can find it easily. +.sp +.LP +Documentation can include man pages or references to stable URLs for reference +documentation. +.sp +.in +2 +.nf +<template> + <documentation> + <manpage title='ttymon' section='8' manpath='/usr/share/man' /> + <doc_link name='docs.sun.com' uri='http://docs.sun.com' /> + </documentation> +</template> +.fi +.in -2 + +.SS "Property Groups" +.sp +.LP +The \fBpg_pattern\fR element contains the definitions for a property group: +.sp +.in +2 +.nf +<template> + <pg_pattern name="pgname" type="pgtype" target="this" required="true"> + </pg_pattern> +</template> +.fi +.in -2 + +.sp +.LP +\fIname\fR is the property group's name, and \fItype\fR is the property group's +type. +.sp +.LP +\fItarget\fR specifies what the target of this definition is. \fB"this"\fR +would refer to the defining service or instance. \fB"instance"\fR can only be +used in a service's template block, and means the definition applies to all +instances of this service. \fB"delegate"\fR can only be used in a restarter's +template block, and applies to all instances that are delegated to that +restarter. \fB"all"\fR, only usable by the master restarter, would refer to all +services on the system. The default value of target is \fB"this"\fR. +.sp +.LP +\fBrequired\fR indicates whether this property group is required or not. The +default value of required is \fBfalse\fR. If \fBrequired\fR is \fBtrue\fR, both +\fIname\fR and \fItype\fR must be specified. +.sp +.LP +\fIname\fR and/or \fItype\fR can be omitted. If either of these attributes is +omitted it is treated as a wildcard. For instance, if the name attribute is +omitted from the \fBpg_pattern\fR definition, the \fBpg_pattern\fR is applied +to all property groups that have the specified type. +.SS "Property Group Names" +.sp +.LP +The \fIcommon_name\fR element contains the localized, human-readable name for +the property group: +.sp +.in +2 +.nf +<pg_pattern ...> + <common_name> + <loctext xml:lang='C'>startt method</loctext> + </common_name> +</pg_pattern> +.fi +.in -2 + +.sp +.LP +\fIcommon_name\fR is a free-form string, but is intended to be used as a label +in a GUI or CLI. +.sp +.LP +The following guidelines are recommended: +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A word or two is usually most appropriate. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be clear. The service, property group, or property name might not be helpful +for humans, but \fIcommon_name\fR should help clarify the purpose of the +entity. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should +not contain clauses or phrases. Punctuation should only be present to meet +trademark requirements. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Capital letters must be used only for acronyms or proper names. For locales +other than English, use appropriate capitalization for a sentence fragment. +.RE +.SS "Property Group Description" +.sp +.LP +The \fIdescription\fR element contains a longer description of the property +group, suitable for a status line or a tool-tip: +.sp +.in +2 +.nf +<pg_pattern ...> + <description> + <loctext xml:lang='C'>A required method which starts the service. + </loctext> + </description> +</pg_pattern> +.fi +.in -2 + +.sp +.LP +\fIdescription\fR Guidelines +.RS +4 +.TP +.ie t \(bu +.el o +Use proper grammar. description is a sentence meant to be read by humans. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A few sentences are usually most appropriate. +.RE +.SS "Properties" +.sp +.LP +The \fIprop_pattern\fR element contains the definitions for a specific +property: +.sp +.in +2 +.nf +<pg_pattern ...> + <prop_pattern name="propname" type="proptype" required="true"> + </prop_pattern> +</pg_pattern> +.fi +.in -2 + +.sp +.LP +\fIname\fR is the property's name, and \fItype\fR is the property's type. +.sp +.LP +\fBrequired\fR indicates whether this property is required. The default value +of \fBrequired\fR is \fBfalse\fR. +.sp +.LP +\fIname\fR is always required. \fItype\fR is optional only if \fBrequired\fR is +\fBfalse\fR. +.SS "Property Names" +.sp +.LP +The \fIcommon_name\fR element contains the localized, human-readable name for +the property: +.sp +.in +2 +.nf + +.fi +.in -2 + +.sp +.LP +\fIcommon_name\fR is a free-form string field, but is intended to be used as a +label in a GUI or CLI. +.sp +.in +2 +.nf +<prop_pattern ...> +<common_name> + <loctext xml:lang='C'>retry interval</loctext> +</common_name> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +The following guidelines are recommended: +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A word or two is usually most appropriate. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be clear. The service, property group, or property name might not be helpful +for humans, but \fIcommon_name\fR should help clarify the purpose of the +entity. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should +not contain clauses or phrases. Punctuation should only be present to meet +trademark requirements. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Capital letters must be used only for acronyms or proper names. For locales +other than English, use appropriate capitalization for a sentence fragment. +.RE +.SS "Property units" +.sp +.LP +The \fIunits\fR element contains the localized, human-readable units for a +numerical property: +.sp +.in +2 +.nf +<prop_pattern ...> + <units> + <loctext xml:lang='C'>seconds</loctext> + </units> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +\fIunits\fR Guidelines +.sp +.LP +The following guidelines are recommended: +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. Strive to use only a single word or label. The plural form is usually +most appropriate. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +No punctuation. units is not a sentence or a paragraph. It should not contain +clauses or phrases. Punctuation should only be present to meet trademark +requirements. +.RE +.SS "Property description" +.sp +.LP +The \fIdescription\fR element contains a longer description of the property, +suitable for a status line or a tool-tip: +.sp +.in +2 +.nf +<prop_pattern ...> + <description> <loctext xml:lang='C'> + The number of seconds to wait before retry. + </loctext> </description> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +\fIdescription\fR Guidelines +.RS +4 +.TP +.ie t \(bu +.el o +Use proper grammar. \fIdescription\fR is a sentence meant to be read by humans. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A few sentences are usually most appropriate. +.RE +.SS "Property visibility" +.sp +.LP +The \fIvisibility\fR element specifies whether simplified views in higher level +software might want to display this property. +.sp +.in +2 +.nf +<prop_pattern ...> + <visibility value="hidden | readonly | readwrite"/> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +Some properties are internal implementation details and should not be presented +as a configuration setting. Others might merely be read-only. This property is +used to specify these restrictions. A value of hidden indicates that the +property shouldn't be displayed, \fBreadonly\fR means that the property isn't +intended to be modified, and \fBreadwrite\fR indicates the property is +modifiable. +.sp +.LP +This is not a security mechanism, it is solely intended to help prevent the +user from shooting himself in the foot, and to remove unnecessary clutter from +CLI output or a GUI display. Hidden properties is visible in full-disclosure +modes of many commands and UIs. +.SS "Property format" +.sp +.LP +The \fIcardinality\fR and \fIinternal_separators\fR elements constrain the +structure of a property: +.sp +.in +2 +.nf +<prop_pattern ...> + <cardinality min="1" max="1"/> + <internal_separators>,<internal_separators> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +\fIcardinality\fR indicates the acceptable number of property values. \fImin\fR +is the minimum number, and \fImax\fR is the maximum number. Both are optional. +If neither is specified, \fB<cardinality/>\fR is the same as the default, zero +or more values. +.sp +.LP +\fIinternal_separators\fR specify the separator characters used for those +property values into which multiple real values are packed. +.SS "Value constraints" +.sp +.LP +The \fIconstraints\fR element specifies what values are acceptable for a +property: +.sp +.in +2 +.nf +<prop_pattern ...> +<constraints> + <value name="blue" /> + <range min="1" max="7"/> + <include_values type="values"/> +</constraints> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +The \fIvalue\fR element includes a possible property value. range includes an +integer range. +.sp +.LP +\fIvalue\fR and \fIrange\fR can be used in any combination, as restricting +their use would prohibit many valid descriptions. If no value constraints are +specified, the property can take on any value. +.sp +.LP +\fIinclude_values\fR includes all values specified by the values block (see +\fBValue Descriptions\fR section). +.SS "Value choices" +.sp +.LP +The choices block indicates which values a UI should offer the user: +.sp +.in +2 +.nf +<prop_pattern ...> +<choices> + <range min="1" max="3"/> + <value name="vt100" /> + <value name="xterm" /> + <include_values type="constraints"/> + <include_values type="values"/> +</choices> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +range and value include ranges and individual values like they do for +constraints. +.sp +.LP +\fIinclude_values\fR includes all values specified by either the constraints +block or the values block (see next section). +.SS "Value Descriptions" +.sp +.LP +Like property names, the values a property can take on can also have +inscrutable representations. The values element contains localized, +human-readable descriptions for specific property values: +.sp +.in +2 +.nf +<prop_pattern> +<values> + <value name="blue"> + <common_name> + <loctext xml:lang='C'>blueloctext xml:lang='C'>blue> + </common_name> + <description> + <loctext xml:lang='C> + The color between green and indigo. + </loctext> + </description> + </value> +</values> +</prop_pattern> +.fi +.in -2 + +.sp +.LP +\fIcommon_name\fR is a free-form string field, but is intended to be used as a +label in a GUI or CLI. +.sp +.LP +The following guidelines are recommended: +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A word or two is usually most appropriate. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be clear. The service, property group, or property name might not be helpful +for humans, but \fIcommon_name\fR should help clarify the purpose of the +entity. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +No punctuation. \fIcommon_name\fR is not a sentence or a paragraph. It should +not contain clauses or phrases. Punctuation should only be present to meet +trademark requirements. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Capital letters must be used only for acronyms or proper names. For locales +other than English, use appropriate capitalization for a sentence fragment. +.RE +.sp +.LP +description Guidelines +.RS +4 +.TP +.ie t \(bu +.el o +Use proper grammar. description is a sentence meant to be read by humans. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Be brief. A few sentences are usually most appropriate. +.RE +.SH EXAMPLES +.sp +.LP +Assuming a basic service which wants to define basic templates data looks +like this: +.sp +.in +2 +.nf +<?xml version="1.0"? +<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1"> +<service_bundle type='manifest' name='FOOfoo:foo'> +<service name='system/foo' type='service' version='1'> + <dependency> + name='multi-user' + type='service' + grouping='require_all' + restart_on='none' + <service_fmri value='svc:/milestone/multi-user' /> + </dependency> + <exec_method + type='method' + name='start' + exec='/opt/foo/food' + timeout_seconds='60'> + </exec_method> + <exec_method + type='method' + name='stop' + exec=':kill' + timeout_seconds='60'> + </exec_method> + <property_group name='config' type='application'> + <propval name='local_only' type='boolean' value='false' /> + <propval name='config_file' type='astring' + value='/opt/foo/foo.conf' /> + <property name='modules' type='astring'> + <astring_list> + <value_node value='bar'/> + <value_node value='baz'/> + </astring_list> + </property> + </property_group> + + <instance name='default' enabled='false' /> +</service_bundle> +</service> +.fi +.in -2 + +.sp +.LP +That service could define some basic templates data to help an administrator +using this service inside of the \fB<service>\fR tags. The most helpful +things are to document the purpose of the service itself and the +service-specific configuration. +.sp +.in +2 +.nf +<template> + <common_name> <loctext xml:lang='C'> + all-purpose demonstration + </loctext> /common_name> + <documentation> + <manpage title='food' section='8' + manpath='/opt/foo/man' /> + </documentation> + + <pg_pattern name='config' type='application' target='this' + required='true'> + <description> <loctext xml:lang='C'> + Basic configuration for foo. + </loctext> </description> + <prop_pattern name='local_only' type='boolean' + required='false'> + <description> <loctext xml:lang='C'> + Only listen to local connection requests. + </loctext> </description> + </prop_pattern> + <prop_pattern name='config_file' type='astring' + required='true'> + <cardinality min='1' max='1'/> + <description> <loctext xml:lang='C'> + Configuration file for foo. + </loctext> </description> + </prop_pattern> + <prop_pattern name='modules' type='astring' + required='false'> + <description> <loctext xml:lang='C'> + Plugin modules for foo. + </loctext> /description> + <values> + <value name='bar'> + <description> <loctext xml:lang='C'> + Allow foo to access the bar. + </loctext> </description> + </value> + <value name='baz'> + <description> <loctext xml:lang='C'> + Allow foo to access baz functions. + </loctext> </description> + </value> + <value name='qux'> + <description> <loctext xml:lang='C'> + Allow foo to access qux functions. + </loctext> </description> + </value> + </values> + <choices> + <include_values type='values'/> + </choices> + <prop_pattern> + </pg_pattern> +</template> +.fi +.in -2 + +.SH FILES +.sp +.LP +\fB/usr/share/lib/xml/dtd/service_bundle.dtd.1\fR +.SH SEE ALSO +.sp +.LP +.BR svcs (1), +.BR libscf (3LIB), +.BR service_bundle (5), +.BR smf (7), +.BR svccfg (8) diff --git a/usr/src/man/man7/standards.7 b/usr/src/man/man7/standards.7 new file mode 100644 index 0000000000..e52d5ea520 --- /dev/null +++ b/usr/src/man/man7/standards.7 @@ -0,0 +1,493 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH STANDARDS 7 "Nov 26, 2017" +.SH NAME +standards, ANSI, C, C++, ISO, POSIX, POSIX.1, POSIX.2, SUS, SUSv2, SUSv3, SVID, +SVID3, XNS, XNS4, XNS5, XPG, XPG3, XPG4, XPG4v2 \- standards and specifications +supported by Solaris +.SH DESCRIPTION +.LP +Solaris 10 supports IEEE Std 1003.1 and IEEE Std 1003.2, commonly known as +POSIX.1 and POSIX.2, respectively. The following table lists each version of +these standards with a brief description and the SunOS or Solaris release that +first conformed to it. +.sp + +.sp +.TS +c c c +l l l . +POSIX Standard Description Release +_ +POSIX.1-1988 system interfaces and headers SunOS 4.1 +_ +POSIX.1-1990 POSIX.1-1988 update Solaris 2.0 +_ +POSIX.1b-1993 realtime extensions Solaris 2.4 +_ +POSIX.1c-1996 threads extensions Solaris 2.6 +_ +POSIX.2-1992 shell and utilities Solaris 2.5 +_ +POSIX.2a-1992 interactive shell and utilities Solaris 2.5 +_ +POSIX.1-2001 T{ +POSIX.1-1990, POSIX.1b-1993, POSIX.1c-1996, POSIX.2-1992, and POSIX.2a-1992 updates +T} Solaris 10 +.TE + +.sp +.LP +Solaris 10 also supports the X/Open Common Applications Environment (CAE) +Portability Guide Issue 3 (XPG3) and Issue 4 (XPG4); Single UNIX Specification +(SUS, also known as XPG4v2); Single UNIX Specification, Version 2 (SUSv2); and +Single UNIX Specification, Version 3 (SUSv3). Both XPG4 and SUS include +Networking Services Issue 4 (XNS4). SUSv2 includes Networking Services Issue 5 +(XNS5). +.sp +.LP +The following table lists each X/Open specification with a brief description +and the SunOS or Solaris release that first conformed to it. +.sp + +.sp +.TS +c c c +c c c . +X/Open CAE +_ + Specification Description Release +_ +XPG3 T{ +superset of POSIX.1-1988 containing utilities from SVID3 +T} SunOS 4.1 +_ +XPG4 T{ +superset of POSIX.1-1990, POSIX.2-1992, and POSIX.2a-1992 containing extensions to POSIX standards from XPG3 +T} Solaris 2.4 +_ +SUS (XPG4v2) T{ +superset of XPG4 containing historical BSD interfaces widely used by common application packages +T} Solaris 2.6 +_ +XNS4 sockets and XTI interfaces Solaris 2.6 +_ +SUSv2 T{ +superset of SUS extended to support POSIX.1b-1993, POSIX.1c-1996, and ISO/IEC 9899 (C Standard) Amendment 1 +T} Solaris 7 +_ +XNS5 T{ +superset and LP64-clean derivative of XNS4. +T} Solaris 7 +_ +SUSv3 same as POSIX.1-2001 Solaris 10 +.TE + +.sp +.LP +The XNS4 specification is safe for use only in ILP32 (32-bit) environments and +should not be used for LP64 (64-bit) application environments. Use XNS5 or +SUSv3, which have LP64-clean interfaces that are portable across ILP32 and LP64 +environments. Solaris releases 7 through 10 support both the ILP32 and LP64 +environments. +.sp +.LP +Solaris releases 7 through 10 have been branded to conform to The Open Group's +UNIX 98 Product Standard. Solaris 10 has been branded to conform to The Open +Group's UNIX 03 Product Standard. +.sp +.LP +Solaris releases 2.0 through 10 support the interfaces specified by the System +V Interface Definition, Third Edition, Volumes 1 through 4 (SVID3). Note, +however, that since the developers of this specification (UNIX Systems +Laboratories) are no longer in business and since this specification defers to +POSIX and X/Open CAE specifications, there is some disagreement about what is +currently required for conformance to this specification. +.sp +.LP +When \fBSun Studio C Compiler 5.6\fR is installed, Solaris releases 2.0 through +10 support the ANSI X3.159-1989 Programming Language - C and ISO/IEC 9899:1990 +Programming Language - C (C) interfaces. +.sp +.LP +When \fBSun Studio C Compiler 5.6\fR is installed, Solaris releases 7 through +10 support ISO/IEC 9899:1990 Amendment 1:1995: C Integrity. +.sp +.LP +When \fBSun Studio C Compiler 5.6\fR is installed, Solaris 10 supports ISO/IEC +9899:1999 Programming Languages - C. +.sp +.LP +When \fBSun Studio C++ Compiler 5.6\fR is installed, Solaris releases 2.5.1 +through 10 support ISO/IEC 14882:1998 Programming Languages - C++. Unsupported +features of that standard are described in the compiler README file. +.SS "Utilities" +.LP +If the behavior required by POSIX.2, POSIX.2a, XPG4, SUS, or SUSv2 conflicts +with historical Solaris utility behavior, the original Solaris version of the +utility is unchanged; a new version that is standard-conforming has been +provided in \fB/usr/xpg4/bin\fR. If the behavior required by POSIX.1-2001 or +SUSv3 conflicts with historical Solaris utility behavior, a new version that is +standard-conforming has been provided in \fB/usr/xpg4/bin\fR or in +\fB/usr/xpg6/bin\fR. If the behavior required by POSIX.1-2001 or SUSv3 +conflicts with POSIX.2, POSIX.2a, SUS, or SUSv2, a new version that is SUSv3 +standard-conforming has been provided in \fB/usr/xpg6/bin\fR. +.sp +.LP +An application that wants to use standard-conforming utilities must set the +\fBPATH\fR (\fBsh\fR(1) or \fBksh\fR(1)) or \fBpath\fR (\fBcsh\fR(1)) +environment variable to specify the directories listed below in the order +specified to get the appropriate utilities: +.sp +.ne 2 +.na +\fBSVID3, XPG3\fR +.ad +.sp .6 +.RS 4n +.RS +4 +.TP +1. +\fB/usr/ccs/bin\fR +.RE +.RS +4 +.TP +2. +\fB/usr/bin\fR +.RE +.RS +4 +.TP +3. +directory containing binaries for your compiler +.RE +.RS +4 +.TP +4. +other directories containing binaries needed by the application +.RE +.RE + +.sp +.ne 2 +.na +\fBPOSIX.2, POSIX.2a, SUS, SUSv2, XPG4\fR +.ad +.sp .6 +.RS 4n +.RS +4 +.TP +1. +\fB/usr/xpg4/bin\fR +.RE +.RS +4 +.TP +2. +\fB/usr/ccs/bin\fR +.RE +.RS +4 +.TP +3. +\fB/usr/bin\fR +.RE +.RS +4 +.TP +4. +directory containing binaries for your compiler +.RE +.RS +4 +.TP +5. +other directories containing binaries needed by the application +.RE +.RE + +.sp +.ne 2 +.na +\fBPOSIX.1-2001, SUSv3\fR +.ad +.sp .6 +.RS 4n +.RS +4 +.TP +1. +\fB/usr/xpg6/bin\fR +.RE +.RS +4 +.TP +2. +\fB/usr/xpg4/bin\fR +.RE +.RS +4 +.TP +3. +\fB/usr/ccs/bin\fR +.RE +.RS +4 +.TP +4. +\fB/usr/bin\fR +.RE +.RS +4 +.TP +5. +directory containing binaries for your compiler +.RE +.RS +4 +.TP +6. +other directories containing binaries needed by the application +.RE +.RE + +.SS "Feature Test Macros" +.LP +Feature test macros are used by applications to indicate additional sets of +features that are desired beyond those specified by the C standard. If an +application uses only those interfaces and headers defined by a particular +standard (such as POSIX or X/Open CAE), then it need only define the +appropriate feature test macro specified by that standard. If the application +is using interfaces and headers not defined by that standard, then in addition +to defining the appropriate standard feature test macro, it must also define +\fB__EXTENSIONS__\fR. Defining \fB__EXTENSIONS__\fR provides the application +with access to all interfaces and headers not in conflict with the specified +standard. The application must define \fB__EXTENSIONS__\fR either on the +compile command line or within the application source files. +.SS "1989 ANSI C, 1990 ISO C, 1999 ISO C" +.LP +No feature test macros need to be defined to indicate that an application is a +conforming C application. +.SS "ANSI/ISO C++" +.LP +ANSI/ISO C++ does not define any feature test macros. If the standard C++ +announcement macro \fB__cplusplus\fR is predefined to value 199711 or greater, +the compiler operates in a standard-conforming mode, indicating C++ standards +conformance. The value 199711 indicates conformance to ISO/IEC 14882:1998, as +required by that standard. (As noted above, conformance to the standard is +incomplete.) A standard-conforming mode is not available with compilers prior +to Sun WorkShop C++ 5.0. +.sp +.LP +C++ bindings are not defined for POSIX or X/Open CAE, so specifying feature +test macros such as \fB_POSIX_SOURCE\fR, \fB_POSIX_C_SOURCE\fR, and +\fB_XOPEN_SOURCE\fR can result in compilation errors due to conflicting +requirements of standard C++ and those specifications. +.SS "POSIX" +.LP +Applications that are intended to be conforming POSIX.1 applications must +define the feature test macros specified by the standard before including any +headers. For the standards listed below, applications must define the feature +test macros listed. Application writers must check the corresponding standards +for other macros that can be queried to determine if desired options are +supported by the implementation. +.sp + +.sp +.TS +c c +l l . +\fBPOSIX Standard\fR \fBFeature Test Macros\fR +_ +POSIX.1-1990 \fB_POSIX_SOURCE\fR +_ +T{ +POSIX.1-1990 and POSIX.2-1992 C-Language Bindings Option +T} \fB_POSIX_SOURCE\fR and \fB_POSIX_C_SOURCE=2\fR +POSIX.1b-1993 \fB_POSIX_C_SOURCE=199309L\fR +_ +POSIX.1c-1996 \fB_POSIX_C_SOURCE=199506L\fR +_ +POSIX.1-2001 \fB_POSIX_C_SOURCE=200112L\fR +.TE + +.SS "SVID3" +.LP +The SVID3 specification does not specify any feature test macros to indicate +that an application is written to meet SVID3 requirements. The SVID3 +specification was written before the C standard was completed. +.SS "X/Open CAE" +.LP +To build or compile an application that conforms to one of the X/Open CAE +specifications, use the following guidelines. Applications need not set the +POSIX feature test macros if they require both CAE and POSIX functionality. +.sp +.ne 2 +.na +\fBXPG3\fR +.ad +.RS 16n +The application must define \fB_XOPEN_SOURCE\fR. If \fB_XOPEN_SOURCE\fR is +defined with a value, the value must be less than 500. +.RE + +.sp +.ne 2 +.na +\fBXPG4\fR +.ad +.RS 16n +The application must define \fB_XOPEN_SOURCE\fR and set \fB_XOPEN_VERSION=4\fR. +If \fB_XOPEN_SOURCE\fR is defined with a value, the value must be less than +500. +.RE + +.sp +.ne 2 +.na +\fBSUS (XPG4v2)\fR +.ad +.RS 16n +The application must define \fB_XOPEN_SOURCE\fR and set +\fB_XOPEN_SOURCE_EXTENDED=1\fR. If \fB_XOPEN_SOURCE\fR is defined with a value, +the value must be less than 500. +.RE + +.sp +.ne 2 +.na +\fBSUSv2\fR +.ad +.RS 16n +The application must define \fB_XOPEN_SOURCE=500\fR. +.RE + +.sp +.ne 2 +.na +\fBSUSv3\fR +.ad +.RS 16n +The application must define \fB_XOPEN_SOURCE=600\fR. +.RE + +.SS "Compilation" +.LP +A POSIX.1 (1988-1996)-, XPG4-, SUS-, or SUSv2-conforming implementation must +include an ANSI X3.159-1989 (ANSI C Language) standard-conforming compilation +system and the \fBcc\fR and \fBc89\fR utilities. A POSIX.1-2001- or +SUSv3-conforming implementation must include an ISO/IEC 99899:1999 (1999 ISO C +Language) standard-conforming compilation system and the \fBc99\fR utility. +Solaris 10 was tested with the \fBcc\fR, \fBc89\fR, and \fBc99\fR utilities and +the compilation environment provided by \fBSun Studio C Compiler 5.6\fR. +.sp +.LP +When \fBcc\fR is used to link applications, \fB/usr/lib/values-xpg4.o\fR must +be specified on any link/load command line, unless the application is +POSIX.1-2001- or SUSv3-conforming, in which case \fB/usr/lib/values-xpg6.o\fR +must be specified on any link/load compile line. The preferred way to build +applications, however, is described in the table below. +.sp +.LP +An XNS4- or XNS5-conforming application must include \fB-l\fR \fBXNS\fR on any +link/load command line in addition to defining the feature test macros +specified for SUS or SUSv2, respectively. +.sp +.LP +If the compiler supports the \fBredefine_extname\fR pragma feature (the \fBSun +Studio C Compiler 5.6\fR compilers define the macro +\fB__PRAGMA_REDEFINE_EXTNAME\fR to indicate that it supports this feature), +then the standard headers use \fB#pragma\fR \fBredefine_extname\fR directives +to properly map function names onto library entry point names. This mapping +provides full support for ISO C, POSIX, and X/Open namespace reservations. +.sp +.LP +If this pragma feature is not supported by the compiler, the headers use the +\fB#define\fR directive to map internal function names onto appropriate library +entry point names. In this instance, applications should avoid using the +explicit 64-bit file offset symbols listed on the \fBlf64\fR(7) manual page, +since these names are used by the implementation to name the alternative entry +points. +.sp +.LP +When using \fBSun Studio C Compiler 5.6\fR compilers, applications conforming +to the specifications listed above should be compiled using the utilities and +flags indicated in the following table: +.sp +.in +2 +.nf +Specification Compiler/Flags Feature Test Macros +_________________________________________________________________________ +1989 ANSI C and 1990 ISO C c89 none +_________________________________________________________________________ +1999 ISO C c99 none +_________________________________________________________________________ +2011 ISO C c11 none + gcc -stdc=c11 +_________________________________________________________________________ +SVID3 cc -Xt -xc99=none none +_________________________________________________________________________ +POSIX.1-1990 c89 _POSIX_SOURCE +_________________________________________________________________________ +POSIX.1-1990 and POSIX.2-1992 c89 _POSIX_SOURCE and + C-Language Bindings Option POSIX_C_SOURCE=2 +_________________________________________________________________________ +POSIX.1b-1993 c89 _POSIX_C_SOURCE=199309L +_________________________________________________________________________ +POSIX.1c-1996 c89 _POSIX_C_SOURCE=199506L +_________________________________________________________________________ +POSIX.1-2001 c99 _POSIX_C_SOURCE=200112L +_________________________________________________________________________ +CAE XPG3 cc -Xa -xc99=none _XOPEN_SOURCE +_________________________________________________________________________ +CAE XPG4 c89 _XOPEN_SOURCE and + _XOPEN_VERSION=4 +_________________________________________________________________________ +SUS (CAE XPG4v2) c89 _XOPEN_SOURCE and + (includes XNS4) _XOPEN_SOURCE_EXTENDED=1 +_________________________________________________________________________ +SUSv2 (includes XNS5) c89 _XOPEN_SOURCE=500 +_________________________________________________________________________ +SUSv3 c99 _XOPEN_SOURCE=600 +.fi +.in -2 +.sp + +.sp +.LP +For platforms supporting the LP64 (64-bit) programming environment, +SUSv2-conforming LP64 applications using XNS5 library calls should be built +with command lines of the form: +.sp +.in +2 +.nf +c89 $(getconf XBS5_LP64_OFF64_CFLAGS) -D_XOPEN_SOURCE=500 \e + $(getconf XBS5_LP64_OFF64_LDFLAGS) foo.c -o foo \e + $(getconf XBS5_LP64_OFF64_LIBS) -lxnet +.fi +.in -2 + +.sp +.LP +Similar SUSv3-conforming LP64 applications should be built with command lines +of the form: +.sp +.in +2 +.nf +c99 $(getconf POSIX_V6_LP64_OFF64_CFLAGS) -D_XOPEN_SOURCE=600 \e + $(getconf POSIX_V6_LP64_OFF64_LDFLAGS) foo.c -o foo \e + $(getconf POSIX_V6_LP64_OFF64_LIBS) -lxnet +.fi +.in -2 + +.SS "SUSv3" +.ne 2 +.na +\fB\fBc99\fR\fR +.ad +.RS 28n +\fB_XOPEN_SOURCE=600\fR +.RE + +.SH SEE ALSO +.LP +.BR csh (1), +.BR ksh (1), +.BR sh (1), +.BR exec (2), +.BR sysconf (3C), +.BR system (3C), +.BR environ (7), +.BR lf64 (7) diff --git a/usr/src/man/man7/sticky.7 b/usr/src/man/man7/sticky.7 new file mode 100644 index 0000000000..5b35238c6a --- /dev/null +++ b/usr/src/man/man7/sticky.7 @@ -0,0 +1,44 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH STICKY 7 "Aug 1, 2002" +.SH NAME +sticky \- mark files for special treatment +.SH DESCRIPTION +.sp +.LP +The \fIsticky bit\fR (file mode bit \fB01000\fR, see \fBchmod\fR(2)) is used +to indicate special treatment of certain files and directories. A directory for +which the sticky bit is set restricts deletion of files it contains. A file in +a sticky directory can only be removed or renamed by a user who has write +permission on the directory, and either owns the file, owns the directory, has +write permission on the file, or is a privileged user. Setting the sticky bit +is useful for directories such as \fB/tmp\fR, which must be publicly writable +but should deny users permission to arbitrarily delete or rename the files of +others. +.sp +.LP +If the sticky bit is set on a regular file and no execute bits are set, the +system's page cache will not be used to hold the file's data. This bit is +normally set on swap files of diskless clients so that accesses to these files +do not flush more valuable data from the system's cache. Moreover, by default +such files are treated as swap files, whose inode modification times may not +necessarily be correctly recorded on permanent storage. +.sp +.LP +Any user may create a sticky directory. See \fBchmod\fR for details about +modifying file modes. +.SH SEE ALSO +.sp +.LP +.BR chmod (1), +.BR chmod (2), +.BR chown (2), +.BR mkdir (2), +.BR rename (2), +.BR unlink (2) +.SH BUGS +.sp +.LP +The \fBmkdir\fR(2) function will not create a directory with the sticky bit +set. diff --git a/usr/src/man/man7/tbl.7 b/usr/src/man/man7/tbl.7 new file mode 100644 index 0000000000..67b24ec019 --- /dev/null +++ b/usr/src/man/man7/tbl.7 @@ -0,0 +1,455 @@ +.\" $Id: tbl.7,v 1.37 2021/09/18 12:34:27 schwarze Exp $ +.\" +.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2014,2015,2017,2018,2019 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: September 18 2021 $ +.Dt TBL 7 +.Os +.Sh NAME +.Nm tbl +.Nd tbl language reference for mandoc +.Sh DESCRIPTION +The +.Nm tbl +language formats tables. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +pages. +This manual describes the subset of the +.Nm +language accepted by the +.Xr mandoc 1 +utility. +.Pp +Each table is started with a +.Xr mandoc_roff 7 +.Ic \&TS +macro, consist of at most one line of +.Sx Options , +one or more +.Sx Layout +lines, one or more +.Sx Data +lines, and ends with a +.Ic \&TE +macro. +All input must be 7-bit ASCII. +.Ss Options +If the first input line of a table ends with a semicolon, it contains +case-insensitive options separated by spaces, tabs, or commas. +Otherwise, it is interpreted as the first +.Sx Layout +line. +.Pp +The following options are available. +Some of them require arguments enclosed in parentheses: +.Bl -tag -width Ds +.It Cm allbox +Draw a single-line box around each table cell. +.It Cm box +Draw a single-line box around the table. +For GNU compatibility, this may also be invoked with +.Cm frame . +.It Cm center +Center the table instead of left-adjusting it. +For GNU compatibility, this may also be invoked with +.Cm centre . +.It Cm decimalpoint +Use the single-character argument as the decimal point with the +.Cm n +layout key. +This is a GNU extension. +.It Cm delim +Use the two characters of the argument as +.Xr eqn 7 +delimiters. +Currently unsupported. +.It Cm doublebox +Draw a double-line box around the table. +For GNU compatibility, this may also be invoked with +.Cm doubleframe . +.It Cm expand +Increase the width of the table to the current line length. +Currently ignored. +.It Cm linesize +Draw lines with the point size given by the unsigned integer argument. +Currently ignored. +.It Cm nokeep +Allow page breaks within the table. +This is a GNU extension and currently ignored. +.It Cm nospaces +Ignore leading and trailing spaces in data cells. +This is a GNU extension. +.It Cm nowarn +Suppress warnings about tables exceeding the current line length. +This is a GNU extension and currently ignored. +.It Cm tab +Use the single-character argument as a delimiter between data cells. +By default, the horizontal tabulator character is used. +.El +.Ss Layout +The table layout follows an +.Sx Options +line or a +.Xr mandoc_roff 7 +.Ic \&TS +or +.Ic \&T& +macro. +Each layout line specifies how one line of +.Sx Data +is formatted. +The last layout line ends with a full stop. +It also applies to all remaining data lines. +Multiple layout lines can be joined by commas on a single physical +input line. +.Pp +Each layout line consists of one or more layout cell specifications, +optionally separated by whitespace. +The following case-insensitive key characters start a new cell +specification: +.Bl -tag -width 2n +.It Cm c +Center the string in this cell. +.It Cm r +Right-justify the string in this cell. +.It Cm l +Left-justify the string in this cell. +.It Cm n +Justify a number around its last decimal point. +If no decimal point is found in the number, +it is assumed to trail the number. +.It Cm s +Horizontally span columns from the last +.Pf non- Cm s +layout cell. +It is an error if a column span follows a +.Cm _ +or +.Cm = +cell, or comes first on a layout line. +The combined cell as a whole consumes only one cell +of the corresponding data line. +.It Cm a +Left-justify a string and pad with one space. +.It Cm \(ha +Vertically span rows from the last +.Pf non- Cm \(ha +layout cell. +It is an error to invoke a vertical span on the first layout line. +Unlike a horizontal span, a vertical span consumes a data cell +and discards the content. +.It Cm _ +Draw a single horizontal line in this cell. +This consumes a data cell and discards the content. +It may also be invoked with +.Cm \- . +.It Cm = +Draw a double horizontal line in this cell. +This consumes a data cell and discards the content. +.El +.Pp +Each cell key may be followed by zero or more of the following +case-insensitive modifiers: +.Bl -tag -width 2n +.It Cm b +Use a bold font for the contents of this cell. +.It Cm d +Move content down to the last row of this vertical span. +Currently ignored. +.It Cm e +Make this column wider to match the maximum width +of any other column also having the +.Cm e +modifier. +.It Cm f +The next one or two characters select the font to use for this cell. +One-character font names must be followed by a blank or period. +See the +.Xr mandoc_roff 7 +manual for supported font names. +.It Cm i +Use an italic font for the contents of this cell. +.It Cm m +Specify a cell start macro. +This is a GNU extension and currently unsupported. +.It Cm p +Set the point size to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm v +Set the vertical line spacing to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm t +Do not vertically center content in this vertical span, +leave it in the top row. +Currently ignored. +.It Cm u +Move cell content up by half a table row. +Currently ignored. +.It Cm w +Specify a minimum column width. +.It Cm x +After determining the width of all other columns, distribute the +rest of the line length among all columns having the +.Cm x +modifier. +.It Cm z +Do not use this cell for determining the width of this column. +.It Cm \&| +Draw a single vertical line to the right of this cell. +.It Cm || +Draw a double vertical line to the right of this cell. +.El +.Pp +If a modifier consists of decimal digits, +it specifies a minimum spacing in units of +.Cm n +between this column and the next column to the right. +The default is 3. +If there is a vertical line, it is drawn inside the spacing. +.Ss Data +The data section follows the last +.Sx Layout +line. +Each data line consists of one or more data cells, delimited by +.Cm tab +characters. +.Pp +If a data cell contains only the two bytes +.Ql \e\(ha , +the cell above spans to this row, as if the layout specification +of this cell were +.Cm \(ha . +.Pp +If a data cell contains only the single character +.Ql _ +or +.Ql = , +a single or double horizontal line is drawn across the cell, +joining its neighbours. +If a data cell contains only the two character sequence +.Ql \e_ +or +.Ql \e= , +a single or double horizontal line is drawn inside the cell, +not joining its neighbours. +If a data line contains nothing but the single character +.Ql _ +or +.Ql = , +a horizontal line across the whole table is inserted +without consuming a layout row. +.Pp +In place of any data cell, a text block can be used. +It starts with +.Ic \&T{ +at the end of a physical input line. +Input line breaks inside the text block +neither end the text block nor its data cell. +It only ends if +.Ic \&T} +occurs at the beginning of a physical input line and is followed +by an end-of-cell indicator. +If the +.Ic \&T} +is followed by the end of the physical input line, the text block, +the data cell, and the data line ends at this point. +If the +.Ic \&T} +is followed by the +.Cm tab +character, only the text block and the data cell end, +but the data line continues with the data cell following the +.Cm tab +character. +If +.Ic \&T} +is followed by any other character, it does not end the text block, +which instead continues to the following physical input line. +.Sh EXAMPLES +String justification and font selection: +.Bd -literal -offset indent +\&.TS +rb c lb +r ci l. +r center l +ri ce le +right c left +\&.TE +.Ed +.Bd -filled -offset indent +.TS +rb c lb +r ci l. +r center l +ri ce le +right c left +.TE +.Ed +.Pp +Some ports in +.Ox 6.1 +to show number alignment and line drawing: +.Bd -literal -offset indent +\&.TS +box tab(:); +r| l +r n. +software:version +_ +AFL:2.39b +Mutt:1.8.0 +Ruby:1.8.7.374 +TeX Live:2015 +\&.TE +.Ed +.Bd -filled -offset indent +.TS +box tab(:); +r| l +r n. +software:version +_ +AFL:2.39b +Mutt:1.8.0 +Ruby:1.8.7.374 +TeX Live:2015 +.TE +.Ed +.sp 2v +Spans and skipping width calculations: +.Bd -literal -offset indent +\&.TS +box tab(:); +lz s | rt +lt| cb| \(ha +\(ha | rz s. +left:r +l:center: +:right +\&.TE +.Ed +.Bd -filled -offset indent +.TS +box tab(:); +lz s | rt +lt| cb| ^ +^ | rz s. +left:r +l:center: +:right +.TE +.Ed +.sp 2v +Text blocks, specifying spacings and specifying and equalizing +column widths, putting lines into individual cells, and overriding +.Cm allbox : +.Bd -literal -offset indent +\&.TS +allbox tab(:); +le le||7 lw10. +The fourth line:_:line 1 +of this column:=:line 2 +determines:\_:line 3 +the column width.:T{ +This text is too wide to fit into a column of width 17. +T}:line 4 +T{ +No break here. +T}::line 5 +\&.TE +.Ed +.Bd -filled -offset indent +.TS +allbox tab(:); +le le||7 lw10. +The fourth line:_:line 1 +of this column:=:line 2 +determines:\_:line 3 +the column width.:T{ +This text is too wide to fit into a column of width 17. +T}:line 4 +T{ +No break here. +T}::line 5 +.TE +.Ed +.sp 2v +These examples were constructed to demonstrate many +.Nm +features in a compact way. +In real manual pages, keep tables as simple as possible. +They usually look better, are less fragile, and are more portable. +.Sh COMPATIBILITY +The +.Xr mandoc 1 +implementation of +.Nm +doesn't support +.Xr mdoc 7 +and +.Xr man 7 +macros and +.Xr eqn 7 +equations inside tables. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr mandoc_roff 7 , +.Xr mdoc 7 +.Rs +.%A M. E. Lesk +.%T Tbl \(em A Program to Format Tables +.%D June 11, 1976 +.Re +.Sh HISTORY +The tbl utility, a preprocessor for troff, was originally written by M. +E. Lesk at Bell Labs in 1975. +The GNU reimplementation of tbl, part of the groff package, was released +in 1990 by James Clark. +A standalone tbl implementation was written by Kristaps Dzonsons in +2010. +This formed the basis of the implementation that first appeared in +.Ox 4.9 +as a part of the +.Xr mandoc 1 +utility. +.Sh AUTHORS +This +.Nm +reference was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . +.Sh BUGS +In +.Fl T +.Cm utf8 +output mode, heavy lines are drawn instead of double lines. +This cannot be improved because the Unicode standard only provides +an incomplete set of box drawing characters with double lines, +whereas it provides a full set of box drawing characters +with heavy lines. +It is unlikely this can be improved in the future because the box +drawing characters are already marked in Unicode as characters +intended only for backward compatibility with legacy systems, +and their use is not encouraged. +So it seems unlikely that the missing ones might get added in the future. diff --git a/usr/src/man/man7/tecla.7 b/usr/src/man/man7/tecla.7 new file mode 100644 index 0000000000..ba148db78f --- /dev/null +++ b/usr/src/man/man7/tecla.7 @@ -0,0 +1,3666 @@ +'\" te +.\" Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd. All Rights Reserved. +.\" Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, and/or sell copies of the Software, and to permit persons +.\" to whom the Software is furnished to do so, provided that the above +.\" copyright notice(s) and this permission notice appear in all copies of +.\" the Software and that both the above copyright notice(s) and this +.\" permission notice appear in supporting documentation. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR +.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL +.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Except as contained in this notice, the name of a copyright holder +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" of the copyright holder. +.\" Portions Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.TH TECLA 7 "April 9, 2016" +.SH NAME +tecla, teclarc \- User interface provided by the tecla library. +.SH DESCRIPTION +.LP +This man page describes the command-line editing features that are available to +users of programs that read keyboard input via the tecla library. Users of the +\fBtcsh\fR shell will find the default key bindings very familiar. Users of the +\fBbash\fR shell will also find it quite familiar, but with a few minor +differences, most notably in how forward and backward searches through the list +of historical commands are performed. There are two major editing modes, one +with \fBemacs\fR-like key bindings and another with \fBvi\fR-like key bindings. +By default \fBemacs\fR mode is enabled, but \fBvi\fR(1) mode can alternatively +be selected via the user's configuration file. This file can also be used to +change the bindings of individual keys to suit the user's preferences. By +default, tab completion is provided. If the application hasn't reconfigured +this to complete other types of symbols, then tab completion completes file +names. +.SS "Key Sequence Notation" +.LP +In the rest of this man page, and also in all tecla configuration files, key +sequences are expressed as follows. +.sp +.ne 2 +.na +\fB\fB^A\fR or \fBC-a\fR\fR +.ad +.RS 13n +This is a 'CONTROL-A', entered by pressing the CONTROL key at the same time as +the 'A' key. +.RE + +.sp +.ne 2 +.na +\fB\eE\fR or \fBM-\fR +.ad +.RS 13n +In key sequences, both of these notations can be entered either by pressing the +ESCAPE key, then the following key, or by pressing the META key at the same +time as the following key. Thus the key sequence \fBM-p\fR can be typed in two +ways, by pressing the ESCAPE key, followed by pressing 'P', or by pressing the +META key at the same time as 'P'. +.RE + +.sp +.ne 2 +.na +\fBup\fR +.ad +.RS 13n +This refers to the up-arrow key. +.RE + +.sp +.ne 2 +.na +\fBdown\fR +.ad +.RS 13n +This refers to the down-arrow key. +.RE + +.sp +.ne 2 +.na +\fBleft\fR +.ad +.RS 13n +This refers to the left-arrow key. +.RE + +.sp +.ne 2 +.na +\fBright\fR +.ad +.RS 13n +This refers to the right-arrow key. +.RE + +.sp +.ne 2 +.na +\fBa\fR +.ad +.RS 13n +This is just a normal 'A' key. +.RE + +.SS "The Tecla Configuration File" +.LP +By default, tecla looks for a file called \fB\&.teclarc\fR in your home +directory (ie. \fB~/.teclarc\fR). If it finds this file, it reads it, +interpreting each line as defining a new key binding or an editing +configuration option. Since the \fBemacs\fR key-bindings are installed by +default, if you want to use the non-default \fBvi\fR editing mode, the most +important item to go in this file is the following line: +.sp +.in +2 +.nf +edit-mode vi +.fi +.in -2 + +.sp +.LP +This will re-configure the default bindings for \fBvi\fR-mode. The complete set +of arguments that this command accepts are: +.sp +.ne 2 +.na +\fBvi\fR +.ad +.RS 9n +Install key bindings like those of the \fBvi\fR editor. +.RE + +.sp +.ne 2 +.na +\fBemacs\fR +.ad +.RS 9n +Install key bindings like those of the \fBemacs\fR editor. This is the default. +.RE + +.sp +.ne 2 +.na +\fBnone\fR +.ad +.RS 9n +Use just the native line editing facilities provided by the terminal driver. +.RE + +.sp +.LP +To prevent the terminal bell from being rung, such as when an unrecognized +control-sequence is typed, place the following line in the configuration file: +.sp +.in +2 +.nf +nobeep +.fi +.in -2 + +.sp +.LP +An example of a key binding line in the configuration file is the following. +.sp +.in +2 +.nf +bind M-[2~ insert-mode +.fi +.in -2 + +.sp +.LP +On many keyboards, the above key sequence is generated when one presses the +insert key, so with this key binding, one can toggle between the +\fBemacs\fR-mode insert and overwrite modes by hitting one key. One could also +do it by typing out the above sequence of characters one by one. As explained +above, the \fBM-\fR part of this sequence can be typed either by pressing the +ESCAPE key before the following key, or by pressing the META key at the same +time as the following key. Thus if you had set the above key binding, and the +insert key on your keyboard didn't generate the above key sequence, you could +still type it in either of the following 2 ways. +.RS +4 +.TP +1. +Hit the ESCAPE key momentarily, then press '[', then '2', then finally '~'. +.RE +.RS +4 +.TP +2. +Press the META key at the same time as pressing the '[' key, then press '2', +then '~'. +.RE +.sp +.LP +If you set a key binding for a key sequence that is already bound to a +function, the new binding overrides the old one. If in the new binding you omit +the name of the new function to bind to the key sequence, the original binding +becomes undefined. +.sp +.LP +Starting with versions of \fBlibtecla\fR later than 1.3.3 it is now possible to +bind key sequences that begin with a printable character. Previously key +sequences were required to start with a CONTROL or META character. +.sp +.LP +Note that the special keywords "up", "down", "left", and "right" refer to the +arrow keys, and are thus not treated as key sequences. So, for example, to +rebind the up and down arrow keys to use the history search mechanism instead +of the simple history recall method, you could place the following in your +configuration file: +.sp +.in +2 +.nf +bind up history-search-backwards +bind down history-search-backwards +.fi +.in -2 + +.sp +.LP +To unbind an existing binding, you can do this with the bind command by +omitting to name any action to rebind the key sequence to. For example, by not +specifying an action function, the following command unbinds the default +beginning-of-line action from the \fB^A\fR key sequence: +.sp +.in +2 +.nf +bind ^A +.fi +.in -2 + +.sp +.LP +If you create a \fB~/.teclarc\fR configuration file, but it appears to have no +effect on the program, check the documentation of the program to see if the +author chose a different name for this file. +.SS "Filename and Tilde Completion" +.LP +With the default key bindings, pressing the TAB key (aka. \fB^I\fR) results in +tecla attempting to complete the incomplete file name that precedes the cursor. +Tecla searches backwards from the cursor, looking for the start of the file +name, stopping when it hits either a space or the start of the line. If more +than one file has the specified prefix, then tecla completes the file name up +to the point at which the ambiguous matches start to differ, then lists the +possible matches. +.sp +.LP +In addition to literally written file names, tecla can complete files that +start with \fB~/\fR and \fB~user/\fR expressions and that contain \fB$envvar\fR +expressions. In particular, if you hit TAB within an incomplete \fB~user\fR, +expression, tecla will attempt to complete the username, listing any ambiguous +matches. +.sp +.LP +The completion binding is implemented using the \fBcpl_complete_word()\fR +function, which is also available separately to users of this library. See the +\fBcpl_complete_word\fR(3TECLA) man page for more details. +.SS "Filename Expansion" +.LP +With the default key bindings, pressing \fB^X*\fR causes tecla to expand the +file name that precedes the cursor, replacing \fB~/\fR and \fB~user/\fR +expressions with the corresponding home directories, and replacing +\fB$envvar\fR expressions with the value of the specified environment variable, +then if there are any wildcards, replacing the so far expanded file name with a +space-separated list of the files which match the wild cards. +.sp +.LP +The expansion binding is implemented using the \fBef_expand_file()\fR function. +See the \fBef_expand_file\fR(3TECLA) man page for more details. +.SS "Recalling Previously Typed Lines" +.LP +Every time that a new line is entered by the user, it is appended to a list of +historical input lines maintained within the \fBGetLine\fR resource object. You +can traverse up and down this list using the up and down arrow keys. +Alternatively, you can do the same with the \fB^P\fR, and \fB^N\fR keys, and in +\fBvi\fR command mode you can alternatively use the k and j characters. Thus +pressing up-arrow once, replaces the current input line with the previously +entered line. Pressing up-arrow again, replaces this with the line that was +entered before it, etc.. Having gone back one or more lines into the history +list, one can return to newer lines by pressing down-arrow one or more times. +If you do this sufficient times, you will return to the original line that you +were entering when you first hit up-arrow. +.sp +.LP +Note that in \fBvi\fR mode, all of the history recall functions switch the +library into command mode. +.sp +.LP +In \fBemacs\fR mode the \fBM-p\fR and \fBM-n\fR keys work just like the +\fB^P\fR and \fB^N\fR keys, except that they skip all but those historical +lines which share the prefix that precedes the cursor. In \fBvi\fR command mode +the upper case 'K' and 'J' characters do the same thing, except that the string +that they search for includes the character under the cursor as well as what +precedes it. +.sp +.LP +Thus for example, suppose that you were in \fBemacs\fR mode, and you had just +entered the following list of commands in the order shown: +.sp +.in +2 +.nf +ls ~/tecla/ +cd ~/tecla +ls -l getline.c +\fBemacs\fR ~/tecla/getline.c +.fi +.in -2 + +.sp +.LP +If you next typed: +.sp +.in +2 +.nf +ls +.fi +.in -2 + +.sp +.LP +and then hit \fBM-p\fR, then rather than returning the previously typed +\fBemacs\fR line, which doesn't start with "ls", tecla would recall the "ls -l +getline.c" line. Pressing \fBM-p\fR again would recall the "ls ~/tecla/" line. +.sp +.LP +Note that if the string that you are searching for, contains any of the special +characters, *, ?, or '[', then it is interpreted as a pattern to be matched. +Thus, continuing with the above example, after typing in the list of commands +shown, if you then typed: +.sp +.in +2 +.nf +*tecla* +.fi +.in -2 + +.sp +.LP +and hit \fBM-p\fR, then the "\fBemacs\fR ~/tecla/getline.c" line would be +recalled first, since it contains the word tecla somewhere in the line, +Similarly, hitting \fBM-p\fR again, would recall the "ls ~/tecla/" line, and +hitting it once more would recall the "ls ~/tecla/" line. The pattern syntax is +the same as that described for file name expansion, in the +\fBef_expand_file\fR(3TECLA). +.SS "History Files" +.LP +Authors of programs that use the tecla library have the option of saving +historical command-lines in a file before exiting, and subsequently reading +them back in from this file when the program is next started. There is no +standard name for this file, since it makes sense for each application to use +its own history file, so that commands from different applications don't get +mixed up. +.SS "International Character Sets" +.LP +Since \fBlibtecla\fR version 1.4.0, tecla has been 8-bit clean. This means that +all 8-bit characters that are printable in the user's current locale are now +displayed verbatim and included in the returned input line. Assuming that the +calling program correctly contains a call like the following, +.sp +.in +2 +.nf +setlocale(LC_CTYPE, ""); +.fi +.in -2 + +.sp +.LP +then the current locale is determined by the first of the environment variables +\fBLC_CTYPE\fR, \fBLC_ALL\fR, and \fBLANG\fR, that is found to contain a valid +locale name. If none of these variables are defined, or the program neglects to +call \fBsetlocale\fR, then the default C locale is used, which is US 7-bit +ASCII. On most unix-like platforms, you can get a list of valid locales by +typing the command: +.sp +.in +2 +.nf +locale -a +.fi +.in -2 + +.sp +.LP +at the shell prompt. +.SS "Meta Keys and Locales" +.LP +Beware that in most locales other than the default C locale, META characters +become printable, and they are then no longer considered to match \fBM-c\fR +style key bindings. This allows international characters to be entered with the +compose key without unexpectedly triggering META key bindings. You can still +invoke META bindings, since there are actually two ways to do this. For example +the binding \fBM-c\fR can also be invoked by pressing the ESCAPE key +momentarily, then pressing the c key, and this will work regardless of locale. +Moreover, many modern terminal emulators, such as gnome's gnome-terminal's and +KDE's konsole terminals, already generate escape pairs like this when you use +the META key, rather than a real meta character, and other emulators usually +have a way to request this behavior, so you can continue to use the META key on +most systems. +.sp +.LP +For example, although xterm terminal emulators generate real 8-bit meta +characters by default when you use the META key, they can be configured to +output the equivalent escape pair by setting their \fBEightBitInput\fR X +resource to False. You can either do this by placing a line like the following +in your \fB~/.Xdefaults\fR file, +.sp +.in +2 +.nf +XTerm*EightBitInput: False +.fi +.in -2 + +.sp +.LP +or by starting an \fBxterm\fR with an \fB-xrm\fR \&'*EightBitInput: False' +command-line argument. In recent versions of xterm you can toggle this feature +on and off with the 'Meta Sends Escape' option in the menu that is displayed +when you press the left mouse button and the CONTROL key within an xterm +window. In CDE, dtterms can be similarly coerced to generate escape pairs in +place of meta characters, by setting the \fBDtterm*KshMode\fR resource to True. +.SS "Entering International Characters" +.LP +If you don't have a keyboard that generates all of the international characters +that you need, there is usually a compose key that will allow you to enter +special characters, or a way to create one. For example, under X windows on +unix-like systems, if your keyboard doesn't have a compose key, you can +designate a redundant key to serve this purpose with the xmodmap command. For +example, on many PC keyboards there is a microsoft-windows key, which is +otherwise useless under Linux. On a laptop, for example, the \fBxev\fR program +might report that pressing this key generates keycode 115. To turn this key +into a COMPOSE key, do the following: +.sp +.in +2 +.nf +xmodmap -e 'keycode 115 = Multi_key' +.fi +.in -2 + +.sp +.LP +Type this key followed by a " character to enter an 'I' with a umlaut over it. +.SS "The Available Key Binding Functions" +.LP +The following is a list of the editing functions provided by the tecla library. +The names in the leftmost column of the list can be used in configuration files +to specify which function a given key or combination of keys should invoke. +They are also used in the next two sections to list the default key bindings in +\fBemacs\fR and \fBvi\fR modes. +.sp +.ne 2 +.na +\fBuser-interrupt\fR +.ad +.RS 30n +Send a SIGINT signal to the parent process. +.RE + +.sp +.ne 2 +.na +\fBsuspend\fR +.ad +.RS 30n +Suspend the parent process. +.RE + +.sp +.ne 2 +.na +\fBstop-output\fR +.ad +.RS 30n +Pause terminal output. +.RE + +.sp +.ne 2 +.na +\fBstart-output\fR +.ad +.RS 30n +Resume paused terminal output. +.RE + +.sp +.ne 2 +.na +\fBliteral-next\fR +.ad +.RS 30n +Arrange for the next character to be treated as a normal character. This allows +control characters to be entered. +.RE + +.sp +.ne 2 +.na +\fBcursor-right\fR +.ad +.RS 30n +Move the cursor one character right. +.RE + +.sp +.ne 2 +.na +\fBcursor-left\fR +.ad +.RS 30n +Move the cursor one character left. +.RE + +.sp +.ne 2 +.na +\fBinsert-mode\fR +.ad +.RS 30n +Toggle between insert mode and overwrite mode. +.RE + +.sp +.ne 2 +.na +\fBbeginning-of-line\fR +.ad +.RS 30n +Move the cursor to the beginning of the line. +.RE + +.sp +.ne 2 +.na +\fBend-of-line\fR +.ad +.RS 30n +Move the cursor to the end of the line. +.RE + +.sp +.ne 2 +.na +\fBdelete-line\fR +.ad +.RS 30n +Delete the contents of the current line. +.RE + +.sp +.ne 2 +.na +\fBkill-line\fR +.ad +.RS 30n +Delete everything that follows the cursor. +.RE + +.sp +.ne 2 +.na +\fBbackward-kill-line\fR +.ad +.RS 30n +Delete all characters between the cursor and the start of the line. +.RE + +.sp +.ne 2 +.na +\fBforward-word\fR +.ad +.RS 30n +Move to the end of the word which follows the cursor. +.RE + +.sp +.ne 2 +.na +\fBforward-to-word\fR +.ad +.RS 30n +Move the cursor to the start of the word that follows the cursor. +.RE + +.sp +.ne 2 +.na +\fBbackward-word\fR +.ad +.RS 30n +Move to the start of the word which precedes the cursor. +.RE + +.sp +.ne 2 +.na +\fBgoto-column\fR +.ad +.RS 30n +Move the cursor to the 1-relative column in the line specified by any preceding +digit-argument sequences (see Entering Repeat Counts below). +.RE + +.sp +.ne 2 +.na +\fBfind-parenthesis\fR +.ad +.RS 30n +If the cursor is currently over a parenthesis character, move it to the +matching parenthesis character. If not over a parenthesis character move right +to the next close parenthesis. +.RE + +.sp +.ne 2 +.na +\fBforward-delete-char\fR +.ad +.RS 30n +Delete the character under the cursor. +.RE + +.sp +.ne 2 +.na +\fBbackward-delete-char\fR +.ad +.RS 30n +Delete the character which precedes the cursor. +.RE + +.sp +.ne 2 +.na +\fBlist-or-eof\fR +.ad +.RS 30n +This is intended for binding to \fB^D\fR. When invoked when the cursor is +within the line it displays all possible completions then redisplays the line +unchanged. When invoked on an empty line, it signals end-of-input (EOF) to the +caller of \fBgl_get_line()\fR. +.RE + +.sp +.ne 2 +.na +\fBdel-char-or-list-or-eof\fR +.ad +.RS 30n +This is intended for binding to \fB^D\fR. When invoked when the cursor is +within the line it invokes forward-delete-char. When invoked at the end of the +line it displays all possible completions then redisplays the line unchanged. +When invoked on an empty line, it signals end-of-input (EOF) to the caller of +\fBgl_get_line()\fR. +.RE + +.sp +.ne 2 +.na +\fBforward-delete-word\fR +.ad +.RS 30n +Delete the word which follows the cursor. +.RE + +.sp +.ne 2 +.na +\fBbackward-delete-word\fR +.ad +.RS 30n +Delete the word which precedes the cursor. +.RE + +.sp +.ne 2 +.na +\fBupcase-word\fR +.ad +.RS 30n +Convert all of the characters of the word which follows the cursor, to upper +case. +.RE + +.sp +.ne 2 +.na +\fBdowncase-word\fR +.ad +.RS 30n +Convert all of the characters of the word which follows the cursor, to lower +case. +.RE + +.sp +.ne 2 +.na +\fBcapitalize-word\fR +.ad +.RS 30n +Capitalize the word which follows the cursor. +.RE + +.sp +.ne 2 +.na +\fBchange-case\fR +.ad +.RS 30n +If the next character is upper case, toggle it to lower case and vice versa. +.RE + +.sp +.ne 2 +.na +\fBredisplay\fR +.ad +.RS 30n +Redisplay the line. +.RE + +.sp +.ne 2 +.na +\fBclear-screen\fR +.ad +.RS 30n +Clear the terminal, then redisplay the current line. +.RE + +.sp +.ne 2 +.na +\fBtranspose-chars\fR +.ad +.RS 30n +Swap the character under the cursor with the character just before the cursor. +.RE + +.sp +.ne 2 +.na +\fBset-mark\fR +.ad +.RS 30n +Set a mark at the position of the cursor. +.RE + +.sp +.ne 2 +.na +\fBexchange-point-and-mark\fR +.ad +.RS 30n +Move the cursor to the last mark that was set, and move the mark to where the +cursor used to be. +.RE + +.sp +.ne 2 +.na +\fBkill-region\fR +.ad +.RS 30n +Delete the characters that lie between the last mark that was set, and the +cursor. +.RE + +.sp +.ne 2 +.na +\fBcopy-region-as-kill\fR +.ad +.RS 30n +Copy the text between the mark and the cursor to the cut buffer, without +deleting the original text. +.RE + +.sp +.ne 2 +.na +\fByank\fR +.ad +.RS 30n +Insert the text that was last deleted, just before the current position of the +cursor. +.RE + +.sp +.ne 2 +.na +\fBappend-yank\fR +.ad +.RS 30n +Paste the current contents of the cut buffer, after the cursor. +.RE + +.sp +.ne 2 +.na +\fBup-history\fR +.ad +.RS 30n +Recall the next oldest line that was entered. Note that in \fBvi\fR mode you +are left in command mode. +.RE + +.sp +.ne 2 +.na +\fBdown-history\fR +.ad +.RS 30n +Recall the next most recent line that was entered. If no history recall session +is currently active, the next line from a previous recall session is recalled. +Note that in vi mode you are left in command mode. +.RE + +.sp +.ne 2 +.na +\fBhistory-search-backward\fR +.ad +.RS 30n +Recall the next oldest line who's prefix matches the string which currently +precedes the cursor (in \fBvi\fR command-mode the character under the cursor is +also included in the search string). Note that in \fBvi\fR mode you are left in +command mode. +.RE + +.sp +.ne 2 +.na +\fBhistory-search-forward\fR +.ad +.RS 30n +Recall the next newest line who's prefix matches the string which currently +precedes the cursor (in \fBvi\fR command-mode the character under the cursor is +also included in the search string). Note that in \fBvi\fR mode you are left in +command mode. +.RE + +.sp +.ne 2 +.na +\fBhistory-re-search-backward\fR +.ad +.RS 30n +Recall the next oldest line who's prefix matches that established by the last +invocation of either history-search-forward or history-search-backward. +.RE + +.sp +.ne 2 +.na +\fBhistory-re-search-forward\fR +.ad +.RS 30n +Recall the next newest line who's prefix matches that established by the last +invocation of either history-search-forward or history-search-backward. +.RE + +.sp +.ne 2 +.na +\fBcomplete-word\fR +.ad +.RS 30n +Attempt to complete the incomplete word which precedes the cursor. Unless the +host program has customized word completion, file name completion is attempted. +In \fBvi\fR command mode the character under the cursor is also included in +the word being completed, and you are left in \fBvi\fR insert mode. +.RE + +.sp +.ne 2 +.na +\fBexpand-filename\fR +.ad +.RS 30n +Within the command line, expand wild cards, tilde expressions and dollar +expressions in the file name which immediately precedes the cursor. In \fBvi\fR +command mode the character under the cursor is also included in the file name +being expanded, and you are left in \fBvi\fR insert mode. +.RE + +.sp +.ne 2 +.na +\fBlist-glob\fR +.ad +.RS 30n +List any file names which match the wild-card, tilde and dollar expressions in +the file name which immediately precedes the cursor, then redraw the input line +unchanged. +.RE + +.sp +.ne 2 +.na +\fBlist-history\fR +.ad +.RS 30n +Display the contents of the history list for the current history group. If a +repeat count of \fB> 1\fR is specified, only that many of the most recent lines +are displayed. See the Entering Repeat Counts section. +.RE + +.sp +.ne 2 +.na +\fBread-from-file\fR +.ad +.RS 30n +Temporarily switch to reading input from the file who's name precedes the +cursor. +.RE + +.sp +.ne 2 +.na +\fBread-init-files\fR +.ad +.RS 30n +Re-read \fBteclarc\fR configuration files. +.RE + +.sp +.ne 2 +.na +\fBbeginning-of-history\fR +.ad +.RS 30n +Move to the oldest line in the history list. Note that in \fBvi\fR mode you are +left in command mode. +.RE + +.sp +.ne 2 +.na +\fBend-of-history\fR +.ad +.RS 30n +Move to the newest line in the history list (ie. the current line). Note that +in \fBvi\fR mode this leaves you in command mode. +.RE + +.sp +.ne 2 +.na +\fBdigit-argument\fR +.ad +.RS 30n +Enter a repeat count for the next key binding function. For details, see the +Entering Repeat Counts section. +.RE + +.sp +.ne 2 +.na +\fBnewline\fR +.ad +.RS 30n +Terminate and return the current contents of the line, after appending a +newline character. The newline character is normally '\en', but will be the +first character of the key sequence that invoked the newline action, if this +happens to be a printable character. If the action was invoked by the '\en' +newline character or the '\er' carriage return character, the line is appended +to the history buffer. +.RE + +.sp +.ne 2 +.na +\fBrepeat-history\fR +.ad +.RS 30n +Return the line that is being edited, then arrange for the next most recent +entry in the history buffer to be recalled when tecla is next called. +Repeatedly invoking this action causes successive historical input lines to be +re-executed. Note that this action is equivalent to the 'Operate' action in +ksh. +.RE + +.sp +.ne 2 +.na +\fBring-bell\fR +.ad +.RS 30n +Ring the terminal bell, unless the bell has been silenced via the nobeep +configuration option (see The Tecla Configuration File section). +.RE + +.sp +.ne 2 +.na +\fBforward-copy-char\fR +.ad +.RS 30n +Copy the next character into the cut buffer (NB. use repeat counts to copy more +than one). +.RE + +.sp +.ne 2 +.na +\fBbackward-copy-char\fR +.ad +.RS 30n +Copy the previous character into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBforward-copy-word\fR +.ad +.RS 30n +Copy the next word into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBbackward-copy-word\fR +.ad +.RS 30n +Copy the previous word into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBforward-find-char\fR +.ad +.RS 30n +Move the cursor to the next occurrence of the next character that you type. +.RE + +.sp +.ne 2 +.na +\fBbackward-find-char\fR +.ad +.RS 30n +Move the cursor to the last occurrence of the next character that you type. +.RE + +.sp +.ne 2 +.na +\fBforward-to-char\fR +.ad +.RS 30n +Move the cursor to the character just before the next occurrence of the next +character that the user types. +.RE + +.sp +.ne 2 +.na +\fBbackward-to-char\fR +.ad +.RS 30n +Move the cursor to the character just after the last occurrence before the +cursor of the next character that the user types. +.RE + +.sp +.ne 2 +.na +\fBrepeat-find-char\fR +.ad +.RS 30n +Repeat the last backward-find-char, forward-find-char, backward-to-char or +forward-to-char. +.RE + +.sp +.ne 2 +.na +\fBinvert-refind-char\fR +.ad +.RS 30n +Repeat the last backward-find-char, forward-find-char, backward-to-char, or +forward-to-char in the opposite direction. +.RE + +.sp +.ne 2 +.na +\fBdelete-to-column\fR +.ad +.RS 30n +Delete the characters from the cursor up to the column that is specified by the +repeat count. +.RE + +.sp +.ne 2 +.na +\fBdelete-to-parenthesis\fR +.ad +.RS 30n +Delete the characters from the cursor up to and including the matching +parenthesis, or next close parenthesis. +.RE + +.sp +.ne 2 +.na +\fBforward-delete-find\fR +.ad +.RS 30n +Delete the characters from the cursor up to and including the following +occurrence of the next character typed. +.RE + +.sp +.ne 2 +.na +\fBbackward-delete-find\fR +.ad +.RS 30n +Delete the characters from the cursor up to and including the preceding +occurrence of the next character typed. +.RE + +.sp +.ne 2 +.na +\fBforward-delete-to\fR +.ad +.RS 30n +Delete the characters from the cursor up to, but not including, the following +occurrence of the next character typed. +.RE + +.sp +.ne 2 +.na +\fBbackward-delete-to\fR +.ad +.RS 30n +Delete the characters from the cursor up to, but not including, the preceding +occurrence of the next character typed. +.RE + +.sp +.ne 2 +.na +\fBdelete-refind\fR +.ad +.RS 30n +Repeat the last *-delete-find or *-delete-to action. +.RE + +.sp +.ne 2 +.na +\fBdelete-invert-refind\fR +.ad +.RS 30n +Repeat the last *-delete-find or *-delete-to action, in the opposite direction. +.RE + +.sp +.ne 2 +.na +\fBcopy-to-column\fR +.ad +.RS 30n +Copy the characters from the cursor up to the column that is specified by the +repeat count, into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBcopy-to-parenthesis\fR +.ad +.RS 30n +Copy the characters from the cursor up to and including the matching +parenthesis, or next close parenthesis, into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBforward-copy-find\fR +.ad +.RS 30n +Copy the characters from the cursor up to and including the following occurrence +of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBbackward-copy-find\fR +.ad +.RS 30n +Copy the characters from the cursor up to and including the preceding occurrence +of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBforward-copy-to\fR +.ad +.RS 30n +Copy the characters from the cursor up to, but not including, the following +occurrence of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBbackward-copy-to\fR +.ad +.RS 30n +Copy the characters from the cursor up to, but not including, the preceding +occurrence of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.na +\fBcopy-refind\fR +.ad +.RS 30n +Repeat the last *-copy-find or *-copy-to action. +.RE + +.sp +.ne 2 +.na +\fBcopy-invert-refind\fR +.ad +.RS 30n +Repeat the last *-copy-find or *-copy-to action, in the opposite direction. +.RE + +.sp +.ne 2 +.na +\fBvi-mode\fR +.ad +.RS 30n +Switch to \fBvi\fR mode from emacs mode. +.RE + +.sp +.ne 2 +.na +\fBemacs-mode\fR +.ad +.RS 30n +Switch to \fBemacs\fR mode from \fBvi\fR mode. +.RE + +.sp +.ne 2 +.na +\fBvi-insert\fR +.ad +.RS 30n +From \fBvi\fR command mode, switch to insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-overwrite\fR +.ad +.RS 30n +From \fBvi\fR command mode, switch to overwrite mode. +.RE + +.sp +.ne 2 +.na +\fBvi-insert-at-bol\fR +.ad +.RS 30n +From \fBvi\fR command mode, move the cursor to the start of the line and switch +to insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-append-at-eol\fR +.ad +.RS 30n +From \fBvi\fR command mode, move the cursor to the end of the line and switch +to append mode. +.RE + +.sp +.ne 2 +.na +\fBvi-append\fR +.ad +.RS 30n +From \fBvi\fR command mode, move the cursor one position right, and switch to +insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-replace-char\fR +.ad +.RS 30n +From \fBvi\fR command mode, replace the character under the cursor with the +next character entered. +.RE + +.sp +.ne 2 +.na +\fBvi-forward-change-char\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the next character then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-backward-change-char\fR +.ad +.RS 30n +From vi command mode, delete the preceding character then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-forward-change-word\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the next word then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-backward-change-word\fR +.ad +.RS 30n +From vi command mode, delete the preceding word then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-change-rest-of-line\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete from the cursor to the end of the line, then +enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-change-line\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the current line, then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-change-to-bol\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete all characters between the cursor and the +beginning of the line, then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-change-to-column\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the characters from the cursor up to the +column that is specified by the repeat count, then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-change-to-parenthesis\fR +.ad +.RS 30n +Delete the characters from the cursor up to and including the matching +parenthesis, or next close parenthesis, then enter \fBvi\fR insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-forward-change-find\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the characters from the cursor up to and +including the following occurrence of the next character typed, then enter +insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-backward-change-find\fR +.ad +.RS 30n +From vi command mode, delete the characters from the cursor up to and including +the preceding occurrence of the next character typed, then enter insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-forward-change-to\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the characters from the cursor up to, but +not including, the following occurrence of the next character typed, then enter +insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-backward-change-to\fR +.ad +.RS 30n +From \fBvi\fR command mode, delete the characters from the cursor up to, but +not including, the preceding occurrence of the next character typed, then enter +insert mode. +.RE + +.sp +.ne 2 +.na +\fBvi-change-refind\fR +.ad +.RS 30n +Repeat the last vi-*-change-find or vi-*-change-to action. +.RE + +.sp +.ne 2 +.na +\fBvi-change-invert-refind\fR +.ad +.RS 30n +Repeat the last vi-*-change-find or vi-*-change-to action, in the opposite +direction. +.RE + +.sp +.ne 2 +.na +\fBvi-undo\fR +.ad +.RS 30n +In \fBvi\fR mode, undo the last editing operation. +.RE + +.sp +.ne 2 +.na +\fBvi-repeat-change\fR +.ad +.RS 30n +In \fBvi\fR command mode, repeat the last command that modified the line. +.RE + +.SS "Default Key Bindings In \fBemacs\fR Mode" +.LP +The following default key bindings, which can be overridden by the tecla +configuration file, are designed to mimic most of the bindings of the unix +\fBtcsh\fR shell, when it is in \fBemacs\fR editing mode. +.sp +.LP +This is the default editing mode of the tecla library. +.sp +.LP +Under UNIX the terminal driver sets a number of special keys for certain +functions. The tecla library attempts to use the same key bindings to maintain +consistency. The key sequences shown for the following 6 bindings are thus just +examples of what they will probably be set to. If you have used the stty +command to change these keys, then the default bindings should match. +.sp +.ne 2 +.na +\fB\fB^C\fR\fR +.ad +.RS 6n +user-interrupt +.RE + +.sp +.ne 2 +.na +\fB^\e\fR +.ad +.RS 6n +abort +.RE + +.sp +.ne 2 +.na +\fB\fB^Z\fR\fR +.ad +.RS 6n +suspend +.RE + +.sp +.ne 2 +.na +\fB\fB^Q\fR\fR +.ad +.RS 6n +start-output +.RE + +.sp +.ne 2 +.na +\fB\fB^S\fR\fR +.ad +.RS 6n +stop-output +.RE + +.sp +.ne 2 +.na +\fB\fB^V\fR\fR +.ad +.RS 6n +literal-next +.RE + +.sp +.LP +The cursor keys are referred to by name, as follows. This is necessary because +different types of terminals generate different key sequences when their cursor +keys are pressed. +.sp +.ne 2 +.na +\fBright\fR +.ad +.RS 9n +cursor-right +.RE + +.sp +.ne 2 +.na +\fBleft\fR +.ad +.RS 9n +cursor-left +.RE + +.sp +.ne 2 +.na +\fBup\fR +.ad +.RS 9n +up-history +.RE + +.sp +.ne 2 +.na +\fBdown\fR +.ad +.RS 9n +down-history +.RE + +.sp +.LP +The remaining bindings don't depend on the terminal settings. +.sp +.ne 2 +.na +\fB\fB^F\fR\fR +.ad +.RS 21n +cursor-right +.RE + +.sp +.ne 2 +.na +\fB\fB^B\fR\fR +.ad +.RS 21n +cursor-left +.RE + +.sp +.ne 2 +.na +\fB\fBM-i\fR\fR +.ad +.RS 21n +insert-mode +.RE + +.sp +.ne 2 +.na +\fB\fB^A\fR\fR +.ad +.RS 21n +beginning-of-line +.RE + +.sp +.ne 2 +.na +\fB\fB^E\fR\fR +.ad +.RS 21n +end-of-line +.RE + +.sp +.ne 2 +.na +\fB\fB^U\fR\fR +.ad +.RS 21n +delete-line +.RE + +.sp +.ne 2 +.na +\fB\fB^K\fR\fR +.ad +.RS 21n +kill-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-f\fR\fR +.ad +.RS 21n +forward-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-b\fR\fR +.ad +.RS 21n +backward-word +.RE + +.sp +.ne 2 +.na +\fB\fB^D\fR\fR +.ad +.RS 21n +del-char-or-list-or-eof +.RE + +.sp +.ne 2 +.na +\fB\fB^H\fR\fR +.ad +.RS 21n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fB^?\fR\fR +.ad +.RS 21n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-d\fR\fR +.ad +.RS 21n +forward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-^H\fR\fR +.ad +.RS 21n +backward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-^?\fR\fR +.ad +.RS 21n +backward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-u\fR\fR +.ad +.RS 21n +upcase-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-l\fR\fR +.ad +.RS 21n +downcase-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-c\fR\fR +.ad +.RS 21n +capitalize-word +.RE + +.sp +.ne 2 +.na +\fB\fB^R\fR\fR +.ad +.RS 21n +redisplay +.RE + +.sp +.ne 2 +.na +\fB\fB^L\fR\fR +.ad +.RS 21n +clear-screen +.RE + +.sp +.ne 2 +.na +\fB\fB^T\fR\fR +.ad +.RS 21n +transpose-chars +.RE + +.sp +.ne 2 +.na +\fB\fB^@\fR\fR +.ad +.RS 21n +set-mark +.RE + +.sp +.ne 2 +.na +\fB\fB^X^X\fR\fR +.ad +.RS 21n +exchange-point-and-mark +.RE + +.sp +.ne 2 +.na +\fB\fB^W\fR\fR +.ad +.RS 21n +kill-region +.RE + +.sp +.ne 2 +.na +\fB\fBM-w\fR\fR +.ad +.RS 21n +copy-region-as-kill +.RE + +.sp +.ne 2 +.na +\fB\fB^Y\fR\fR +.ad +.RS 21n +yank +.RE + +.sp +.ne 2 +.na +\fB\fB^P\fR\fR +.ad +.RS 21n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fB^N\fR\fR +.ad +.RS 21n +down-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-p\fR\fR +.ad +.RS 21n +history-search-backward +.RE + +.sp +.ne 2 +.na +\fB\fBM-n\fR\fR +.ad +.RS 21n +history-search-forward +.RE + +.sp +.ne 2 +.na +\fB\fB^I\fR\fR +.ad +.RS 21n +complete-word +.RE + +.sp +.ne 2 +.na +\fB\fB^X*\fR\fR +.ad +.RS 21n +expand-filename +.RE + +.sp +.ne 2 +.na +\fB\fB^X^F\fR\fR +.ad +.RS 21n +read-from-file +.RE + +.sp +.ne 2 +.na +\fB\fB^X^R\fR\fR +.ad +.RS 21n +read-init-files +.RE + +.sp +.ne 2 +.na +\fB\fB^Xg\fR\fR +.ad +.RS 21n +list-glob +.RE + +.sp +.ne 2 +.na +\fB\fB^Xh\fR\fR +.ad +.RS 21n +list-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-<\fR\fR +.ad +.RS 21n +beginning-of-history +.RE + +.sp +.ne 2 +.na +\fB\fBM->\fR\fR +.ad +.RS 21n +end-of-history +.RE + +.sp +.ne 2 +.na +\fB\fB\en\fR\fR +.ad +.RS 21n +newline +.RE + +.sp +.ne 2 +.na +\fB\fB\er\fR\fR +.ad +.RS 21n +newline +.RE + +.sp +.ne 2 +.na +\fB\fBM-o\fR\fR +.ad +.RS 21n +repeat-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-^V\fR\fR +.ad +.RS 21n +\fBvi\fR-mode +.RE + +.sp +.ne 2 +.na +\fB\fBM-0, M-1, ... M-9\fR\fR +.ad +.RS 21n +digit-argument (see below) +.RE + +.sp +.LP +Note that \fB^I\fR is what the TAB key generates, and that \fB^@\fR can be +generated not only by pressing the CONTROL key and the @ key simultaneously, +but also by pressing the CONTROL key and the space bar at the same time. +.SS "Default Key Bindings in \fBvi\fR Mode" +.LP +The following default key bindings are designed to mimic the \fBvi\fR style of +editing as closely as possible. This means that very few editing functions are +provided in the initial character input mode, editing functions instead being +provided by the \fBvi\fR command mode. The \fBvi\fR command mode is entered +whenever the ESCAPE character is pressed, or whenever a key sequence that +starts with a meta character is entered. In addition to mimicing \fBvi\fR, +\fBlibtecla\fR provides bindings for tab completion, wild-card expansion of +file names, and historical line recall. +.sp +.LP +To learn how to tell the tecla library to use \fBvi\fR mode instead of the +default \fBemacs\fR editing mode, see the earlier section entitled The Tecla +Configuration File. +.sp +.LP +Under UNIX the terminal driver sets a number of special keys for certain +functions. The tecla library attempts to use the same key bindings to maintain +consistency, binding them both in input mode and in command mode. The key +sequences shown for the following 6 bindings are thus just examples of what +they will probably be set to. If you have used the \fBstty\fR command to change +these keys, then the default bindings should match. +.sp +.ne 2 +.na +\fB\fB^C\fR\fR +.ad +.RS 8n +user-interrupt +.RE + +.sp +.ne 2 +.na +\fB^\e\fR +.ad +.RS 8n +abort +.RE + +.sp +.ne 2 +.na +\fB\fB^Z\fR\fR +.ad +.RS 8n +suspend +.RE + +.sp +.ne 2 +.na +\fB\fB^Q\fR\fR +.ad +.RS 8n +start-output +.RE + +.sp +.ne 2 +.na +\fB\fB^S\fR\fR +.ad +.RS 8n +stop-output +.RE + +.sp +.ne 2 +.na +\fB\fB^V\fR\fR +.ad +.RS 8n +literal-next +.RE + +.sp +.ne 2 +.na +\fB\fBM-^C\fR\fR +.ad +.RS 8n +user-interrupt +.RE + +.sp +.ne 2 +.na +\fBM-^\e\fR +.ad +.RS 8n +abort +.RE + +.sp +.ne 2 +.na +\fB\fBM-^Z\fR\fR +.ad +.RS 8n +suspend +.RE + +.sp +.ne 2 +.na +\fB\fBM-^Q\fR\fR +.ad +.RS 8n +start-output +.RE + +.sp +.ne 2 +.na +\fB\fBM-^S\fR\fR +.ad +.RS 8n +stop-output +.RE + +.sp +.LP +Note that above, most of the bindings are defined twice, once as a raw control +code like \fB^C\fR and then a second time as a META character like \fBM-^C\fR. +The former is the binding for \fBvi\fR input mode, whereas the latter is the +binding for \fBvi\fR command mode. Once in command mode all key sequences that +the user types that they don't explicitly start with an ESCAPE or a META key, +have their first key secretly converted to a META character before the key +sequence is looked up in the key binding table. Thus, once in command mode, +when you type the letter i, for example, the tecla library actually looks up +the binding for \fBM-i\fR. +.sp +.LP +The cursor keys are referred to by name, as follows. This is necessary because +different types of terminals generate different key sequences when their cursor +keys are pressed. +.sp +.ne 2 +.na +\fB\fBright\fR\fR +.ad +.RS 9n +cursor-right +.RE + +.sp +.ne 2 +.na +\fB\fBleft\fR\fR +.ad +.RS 9n +cursor-left +.RE + +.sp +.ne 2 +.na +\fB\fBup\fR\fR +.ad +.RS 9n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fBdown\fR\fR +.ad +.RS 9n +down-history +.RE + +.sp +.LP +The cursor keys normally generate a key sequence that start with an ESCAPE +character, so beware that using the arrow keys will put you into command mode +(if you aren't already in command mode). +.sp +.LP +The following are the terminal-independent key bindings for \fBvi\fR input +mode. +.sp +.ne 2 +.na +\fB\fB^D\fR\fR +.ad +.RS 8n +list-or-eof +.RE + +.sp +.ne 2 +.na +\fB\fB^G\fR\fR +.ad +.RS 8n +list-glob +.RE + +.sp +.ne 2 +.na +\fB\fB^H\fR\fR +.ad +.RS 8n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fB^I\fR\fR +.ad +.RS 8n +complete-word +.RE + +.sp +.ne 2 +.na +\fB\fB\er\fR\fR +.ad +.RS 8n +newline +.RE + +.sp +.ne 2 +.na +\fB\fB\en\fR\fR +.ad +.RS 8n +newline +.RE + +.sp +.ne 2 +.na +\fB\fB^L\fR\fR +.ad +.RS 8n +clear-screen +.RE + +.sp +.ne 2 +.na +\fB\fB^N\fR\fR +.ad +.RS 8n +down-history +.RE + +.sp +.ne 2 +.na +\fB\fB^P\fR\fR +.ad +.RS 8n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fB^R\fR\fR +.ad +.RS 8n +redisplay +.RE + +.sp +.ne 2 +.na +\fB\fB^U\fR\fR +.ad +.RS 8n +backward-kill-line +.RE + +.sp +.ne 2 +.na +\fB\fB^W\fR\fR +.ad +.RS 8n +backward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fB^X*\fR\fR +.ad +.RS 8n +expand-filename +.RE + +.sp +.ne 2 +.na +\fB\fB^X^F\fR\fR +.ad +.RS 8n +read-from-file +.RE + +.sp +.ne 2 +.na +\fB\fB^X^R\fR\fR +.ad +.RS 8n +read-init-files +.RE + +.sp +.ne 2 +.na +\fB\fB^?\fR\fR +.ad +.RS 8n +backward-delete-char +.RE + +.sp +.LP +The following are the key bindings that are defined in \fBvi\fR command mode, +this being specified by them all starting with a META character. As mentioned +above, once in command mode the initial meta character is optional. For +example, you might enter command mode by typing ESCAPE, and then press 'H' +twice to move the cursor two positions to the left. Both 'H' characters get +quietly converted to \fBM-h\fR before being compared to the key binding table, +the first one because ESCAPE followed by a character is always converted to the +equivalent META character, and the second because command mode was already +active. +.sp +.ne 2 +.na +\fBM-<space>\fR +.ad +.RS 21n +cursor-right (META-space) +.RE + +.sp +.ne 2 +.na +\fB\fBM-$\fR\fR +.ad +.RS 21n +end-of-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-*\fR\fR +.ad +.RS 21n +expand-filename +.RE + +.sp +.ne 2 +.na +\fB\fBM-+\fR\fR +.ad +.RS 21n +down-history +.RE + +.sp +.ne 2 +.na +\fB\fBM--\fR\fR +.ad +.RS 21n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-<\fR\fR +.ad +.RS 21n +beginning-of-history +.RE + +.sp +.ne 2 +.na +\fB\fBM->\fR\fR +.ad +.RS 21n +end-of-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-^\fR\fR +.ad +.RS 21n +beginning-of-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-\fR\fR +.ad +.RS 21n +repeat-find-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-,\fR\fR +.ad +.RS 21n +invert-refind-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-|\fR\fR +.ad +.RS 21n +goto-column +.RE + +.sp +.ne 2 +.na +\fB\fBM-~\fR\fR +.ad +.RS 21n +change-case +.RE + +.sp +.ne 2 +.na +\fB\fBM-.\fR\fR +.ad +.RS 21n +vi-repeat-change +.RE + +.sp +.ne 2 +.na +\fB\fBM-%\fR\fR +.ad +.RS 21n +find-parenthesis +.RE + +.sp +.ne 2 +.na +\fB\fBM-a\fR\fR +.ad +.RS 21n +vi-append +.RE + +.sp +.ne 2 +.na +\fB\fBM-A\fR\fR +.ad +.RS 21n +vi-append-at-eol +.RE + +.sp +.ne 2 +.na +\fB\fBM-b\fR\fR +.ad +.RS 21n +backward-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-B\fR\fR +.ad +.RS 21n +backward-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-C\fR\fR +.ad +.RS 21n +vi-change-rest-of-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-cb\fR\fR +.ad +.RS 21n +vi-backward-change-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-cB\fR\fR +.ad +.RS 21n +vi-backward-change-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-cc\fR\fR +.ad +.RS 21n +vi-change-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-ce\fR\fR +.ad +.RS 21n +vi-forward-change-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-cE\fR\fR +.ad +.RS 21n +vi-forward-change-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-cw\fR\fR +.ad +.RS 21n +vi-forward-change-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-cW\fR\fR +.ad +.RS 21n +vi-forward-change-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-cF\fR\fR +.ad +.RS 21n +vi-backward-change-find +.RE + +.sp +.ne 2 +.na +\fB\fBM-cf\fR\fR +.ad +.RS 21n +vi-forward-change-find +.RE + +.sp +.ne 2 +.na +\fB\fBM-cT\fR\fR +.ad +.RS 21n +vi-backward-change-to +.RE + +.sp +.ne 2 +.na +\fB\fBM-ct\fR\fR +.ad +.RS 21n +vi-forward-change-to +.RE + +.sp +.ne 2 +.na +\fB\fBM-c;\fR\fR +.ad +.RS 21n +vi-change-refind +.RE + +.sp +.ne 2 +.na +\fB\fBM-c,\fR\fR +.ad +.RS 21n +vi-change-invert-refind +.RE + +.sp +.ne 2 +.na +\fB\fBM-ch\fR\fR +.ad +.RS 21n +vi-backward-change-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-c^H\fR\fR +.ad +.RS 21n +vi-backward-change-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-c^?\fR\fR +.ad +.RS 21n +vi-backward-change-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-cl\fR\fR +.ad +.RS 21n +vi-forward-change-char +.RE + +.sp +.ne 2 +.na +\fBM-c<space>\fR +.ad +.RS 21n +vi-forward-change-char (META-c-space) +.RE + +.sp +.ne 2 +.na +\fB\fBM-c^\fR\fR +.ad +.RS 21n +vi-change-to-bol +.RE + +.sp +.ne 2 +.na +\fB\fBM-c0\fR\fR +.ad +.RS 21n +vi-change-to-bol +.RE + +.sp +.ne 2 +.na +\fB\fBM-c$\fR\fR +.ad +.RS 21n +vi-change-rest-of-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-c|\fR\fR +.ad +.RS 21n +vi-change-to-column +.RE + +.sp +.ne 2 +.na +\fB\fBM-c%\fR\fR +.ad +.RS 21n +vi-change-to-parenthesis +.RE + +.sp +.ne 2 +.na +\fB\fBM-dh\fR\fR +.ad +.RS 21n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-d^H\fR\fR +.ad +.RS 21n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-d^?\fR\fR +.ad +.RS 21n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-dl\fR\fR +.ad +.RS 21n +forward-delete-char +.RE + +.sp +.ne 2 +.na +\fBM-d<space>\fR +.ad +.RS 21n +forward-delete-char (META-d-space) +.RE + +.sp +.ne 2 +.na +\fB\fBM-dd\fR\fR +.ad +.RS 21n +delete-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-db\fR\fR +.ad +.RS 21n +backward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-dB\fR\fR +.ad +.RS 21n +backward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-de\fR\fR +.ad +.RS 21n +forward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-dE\fR\fR +.ad +.RS 21n +forward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-dw\fR\fR +.ad +.RS 21n +forward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-dW\fR\fR +.ad +.RS 21n +forward-delete-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-dF\fR\fR +.ad +.RS 21n +backward-delete-find +.RE + +.sp +.ne 2 +.na +\fB\fBM-df\fR\fR +.ad +.RS 21n +forward-delete-find +.RE + +.sp +.ne 2 +.na +\fB\fBM-dT\fR\fR +.ad +.RS 21n +backward-delete-to +.RE + +.sp +.ne 2 +.na +\fB\fBM-dt\fR\fR +.ad +.RS 21n +forward-delete-to +.RE + +.sp +.ne 2 +.na +\fB\fBM-d;\fR\fR +.ad +.RS 21n +delete-refind +.RE + +.sp +.ne 2 +.na +\fB\fBM-d,\fR\fR +.ad +.RS 21n +delete-invert-refind +.RE + +.sp +.ne 2 +.na +\fB\fBM-d^\fR\fR +.ad +.RS 21n +backward-kill-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-d0\fR\fR +.ad +.RS 21n +backward-kill-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-d$\fR\fR +.ad +.RS 21n +kill-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-D\fR\fR +.ad +.RS 21n +kill-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-d|\fR\fR +.ad +.RS 21n +delete-to-column +.RE + +.sp +.ne 2 +.na +\fB\fBM-d%\fR\fR +.ad +.RS 21n +delete-to-parenthesis +.RE + +.sp +.ne 2 +.na +\fB\fBM-e\fR\fR +.ad +.RS 21n +forward-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-E\fR\fR +.ad +.RS 21n +forward-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-f\fR\fR +.ad +.RS 21n +forward-find-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-F\fR\fR +.ad +.RS 21n +backward-find-char +.RE + +.sp +.ne 2 +.na +\fB\fBM--\fR\fR +.ad +.RS 21n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-h\fR\fR +.ad +.RS 21n +cursor-left +.RE + +.sp +.ne 2 +.na +\fB\fBM-H\fR\fR +.ad +.RS 21n +beginning-of-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-i\fR\fR +.ad +.RS 21n +vi-insert +.RE + +.sp +.ne 2 +.na +\fB\fBM-I\fR\fR +.ad +.RS 21n +vi-insert-at-bol +.RE + +.sp +.ne 2 +.na +\fB\fBM-j\fR\fR +.ad +.RS 21n +down-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-J\fR\fR +.ad +.RS 21n +history-search-forward +.RE + +.sp +.ne 2 +.na +\fB\fBM-k\fR\fR +.ad +.RS 21n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-K\fR\fR +.ad +.RS 21n +history-search-backward +.RE + +.sp +.ne 2 +.na +\fB\fBM-l\fR\fR +.ad +.RS 21n +cursor-right +.RE + +.sp +.ne 2 +.na +\fB\fBM-L\fR\fR +.ad +.RS 21n +end-of-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-n\fR\fR +.ad +.RS 21n +history-re-search-forward +.RE + +.sp +.ne 2 +.na +\fB\fBM-N\fR\fR +.ad +.RS 21n +history-re-search-backward +.RE + +.sp +.ne 2 +.na +\fB\fBM-p\fR\fR +.ad +.RS 21n +append-yank +.RE + +.sp +.ne 2 +.na +\fB\fBM-P\fR\fR +.ad +.RS 21n +yank +.RE + +.sp +.ne 2 +.na +\fB\fBM-r\fR\fR +.ad +.RS 21n +vi-replace-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-R\fR\fR +.ad +.RS 21n +vi-overwrite +.RE + +.sp +.ne 2 +.na +\fB\fBM-s\fR\fR +.ad +.RS 21n +vi-forward-change-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-S\fR\fR +.ad +.RS 21n +vi-change-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-t\fR\fR +.ad +.RS 21n +forward-to-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-T\fR\fR +.ad +.RS 21n +backward-to-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-u\fR\fR +.ad +.RS 21n +vi-undo +.RE + +.sp +.ne 2 +.na +\fB\fBM-w\fR\fR +.ad +.RS 21n +forward-to-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-W\fR\fR +.ad +.RS 21n +forward-to-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-x\fR\fR +.ad +.RS 21n +forward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-X\fR\fR +.ad +.RS 21n +backward-delete-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-yh\fR\fR +.ad +.RS 21n +backward-copy-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-y^H\fR\fR +.ad +.RS 21n +backward-copy-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-y^?\fR\fR +.ad +.RS 21n +backward-copy-char +.RE + +.sp +.ne 2 +.na +\fB\fBM-yl\fR\fR +.ad +.RS 21n +forward-copy-char +.RE + +.sp +.ne 2 +.na +\fBM-y<space>\fR +.ad +.RS 21n +forward-copy-char (META-y-space) +.RE + +.sp +.ne 2 +.na +\fB\fBM-ye\fR\fR +.ad +.RS 21n +forward-copy-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-yE\fR\fR +.ad +.RS 21n +forward-copy-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-yw\fR\fR +.ad +.RS 21n +forward-copy-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-yW\fR\fR +.ad +.RS 21n +forward-copy-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-yb\fR\fR +.ad +.RS 21n +backward-copy-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-yB\fR\fR +.ad +.RS 21n +backward-copy-word +.RE + +.sp +.ne 2 +.na +\fB\fBM-yf\fR\fR +.ad +.RS 21n +forward-copy-find +.RE + +.sp +.ne 2 +.na +\fB\fBM-yF\fR\fR +.ad +.RS 21n +backward-copy-find +.RE + +.sp +.ne 2 +.na +\fB\fBM-yt\fR\fR +.ad +.RS 21n +forward-copy-to +.RE + +.sp +.ne 2 +.na +\fB\fBM-yT\fR\fR +.ad +.RS 21n +backward-copy-to +.RE + +.sp +.ne 2 +.na +\fB\fBM-y;\fR\fR +.ad +.RS 21n +copy-refind +.RE + +.sp +.ne 2 +.na +\fB\fBM-y,\fR\fR +.ad +.RS 21n +copy-invert-refind +.RE + +.sp +.ne 2 +.na +\fB\fBM-y^\fR\fR +.ad +.RS 21n +copy-to-bol +.RE + +.sp +.ne 2 +.na +\fB\fBM-y0\fR\fR +.ad +.RS 21n +copy-to-bol +.RE + +.sp +.ne 2 +.na +\fB\fBM-y$\fR\fR +.ad +.RS 21n +copy-rest-of-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-yy\fR\fR +.ad +.RS 21n +copy-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-Y\fR\fR +.ad +.RS 21n +copy-line +.RE + +.sp +.ne 2 +.na +\fB\fBM-y|\fR\fR +.ad +.RS 21n +copy-to-column +.RE + +.sp +.ne 2 +.na +\fB\fBM-y%\fR\fR +.ad +.RS 21n +copy-to-parenthesis +.RE + +.sp +.ne 2 +.na +\fB\fBM-^E\fR\fR +.ad +.RS 21n +emacs-mode +.RE + +.sp +.ne 2 +.na +\fB\fBM-^H\fR\fR +.ad +.RS 21n +cursor-left +.RE + +.sp +.ne 2 +.na +\fB\fBM-^?\fR\fR +.ad +.RS 21n +cursor-left +.RE + +.sp +.ne 2 +.na +\fB\fBM-^L\fR\fR +.ad +.RS 21n +clear-screen +.RE + +.sp +.ne 2 +.na +\fB\fBM-^N\fR\fR +.ad +.RS 21n +down-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-^P\fR\fR +.ad +.RS 21n +up-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-^R\fR\fR +.ad +.RS 21n +redisplay +.RE + +.sp +.ne 2 +.na +\fB\fBM-^D\fR\fR +.ad +.RS 21n +list-or-eof +.RE + +.sp +.ne 2 +.na +\fB\fBM-^I\fR\fR +.ad +.RS 21n +complete-word +.RE + +.sp +.ne 2 +.na +\fBM-\er\fR +.ad +.RS 21n +newline +.RE + +.sp +.ne 2 +.na +\fB\fBM-\en\fR\fR +.ad +.RS 21n +newline +.RE + +.sp +.ne 2 +.na +\fB\fBM-^X^R\fR\fR +.ad +.RS 21n +read-init-files +.RE + +.sp +.ne 2 +.na +\fB\fBM-^Xh\fR\fR +.ad +.RS 21n +list-history +.RE + +.sp +.ne 2 +.na +\fB\fBM-0, M-1, ... M-9\fR\fR +.ad +.RS 21n +digit-argument (see below) +.RE + +.sp +.LP +Note that \fB^I\fR is what the TAB key generates. +.SS "Entering Repeat Counts" +.LP +Many of the key binding functions described previously, take an optional count, +typed in before the target key sequence. This is interpreted as a repeat count +by most bindings. A notable exception is the goto-column binding, which +interprets the count as a column number. +.sp +.LP +By default you can specify this count argument by pressing the META key while +typing in the numeric count. This relies on the digit-argument action being +bound to 'META-0', 'META-1' etc. Once any one of these bindings has been +activated, you can optionally take your finger off the META key to type in the +rest of the number, since every numeric digit thereafter is treated as part of +the number, unless it is preceded by the literal-next binding. As soon as a +non-digit, or literal digit key is pressed the repeat count is terminated and +either causes the just typed character to be added to the line that many times, +or causes the next key binding function to be given that argument. +.sp +.LP +For example, in \fBemacs\fR mode, typing: +.sp +.in +2 +.nf +M-12a +.fi +.in -2 + +.sp +.LP +causes the letter 'a' to be added to the line 12 times, whereas +.sp +.in +2 +.nf +M-4M-c +.fi +.in -2 + +.sp +.LP +Capitalizes the next 4 words. +.sp +.LP +In \fBvi\fR command mode the meta modifier is automatically added to all +characters typed in, so to enter a count in \fBvi\fR command-mode, just +involves typing in the number, just as it does in the \fBvi\fR editor itself. +So for example, in vi command mode, typing: +.sp +.in +2 +.nf +4w2x +.fi +.in -2 + +.sp +.LP +moves the cursor four words to the right, then deletes two characters. +.sp +.LP +You can also bind digit-argument to other key sequences. If these end in a +numeric digit, that digit gets appended to the current repeat count. If it +doesn't end in a numeric digit, a new repeat count is started with a value of +zero, and can be completed by typing in the number, after letting go of the key +which triggered the digit-argument action. +.SH FILES +.ne 2 +.na +\fB\fB/usr/lib/libtecla.so\fR\fR +.ad +.RS 27n +The tecla library +.RE + +.sp +.ne 2 +.na +\fB\fB/usr/include/libtecla.h\fR\fR +.ad +.RS 27n +The tecla header file +.RE + +.sp +.ne 2 +.na +\fB\fB~/.teclarc\fR\fR +.ad +.RS 27n +The personal tecla customization file +.RE + +.SH ATTRIBUTES +.LP +See \fBattributes\fR(7) 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 +.LP +.BR vi (1), +.BR libtecla (3LIB), +.BR cpl_complete_word (3TECLA), +.BR ef_expand_file (3TECLA), +.BR gl_get_line (3TECLA), +.BR gl_io_mode (3TECLA), +.BR pca_lookup_file (3TECLA), +.BR attributes (7) diff --git a/usr/src/man/man7/term.7 b/usr/src/man/man7/term.7 new file mode 100644 index 0000000000..f31af9d797 --- /dev/null +++ b/usr/src/man/man7/term.7 @@ -0,0 +1,215 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 TERM 7 "Jul 3, 1990" +.SH NAME +term \- conventional names for terminals +.SH DESCRIPTION +.sp +.LP +Terminal names are maintained as part of the shell environment in the +environment variable \fB\fR\fBTERM\fR\fB\&. \fR See \fBsh\fR(1), +\fBprofile\fR(5), and \fBenviron\fR(7). These names are used by certain +commands (for example, \fBtabs\fR, \fBtput\fR, and \fBvi\fR) and certain +functions (for example, see \fBcurses\fR(3CURSES)). +.sp +.LP +Files under \fB/usr/share/lib/terminfo\fR are used to name terminals and +describe their capabilities. These files are in the format described in +\fBterminfo\fR(5). Entries in \fBterminfo\fR source files consist of a number +of comma-separated fields. To print a description of a terminal \fIterm\fR, +use the command \fBinfocmp\fR \fB-I\fR \fIterm\fR. See \fBinfocmp\fR(8). +White space after each comma is ignored. The first line of each terminal +description in the \fBterminfo\fR database gives the names by which +\fBterminfo\fR knows the terminal, separated by bar (\fB|\fR) characters. The +first name given is the most common abbreviation for the terminal (this is the +one to use to set the environment variable \fBTERMINFO\fR in +\fB$HOME/.profile\fR; see \fBprofile\fR(5)), the last name given should be a +long name fully identifying the terminal, and all others are understood as +synonyms for the terminal name. All names but the last should contain no blanks +and must be unique in the first 14 characters; the last name may contain blanks +for readability. +.sp +.LP +Terminal names (except for the last, verbose entry) should be chosen using the +following conventions. The particular piece of hardware making up the terminal +should have a root name chosen, for example, for the AT&T 4425 terminal, +\fBatt4425\fR. This name should not contain hyphens, except that synonyms may +be chosen that do not conflict with other names. Up to 8 characters, chosen +from the set \fBa\fR through \fBz\fR and \fB0\fR through \fB9\fR, make up a +basic terminal name. Names should generally be based on original vendors rather +than local distributors. A terminal acquired from one vendor should not have +more than one distinct basic name. Terminal sub-models, operational modes that +the hardware can be in, or user preferences should be indicated by appending a +hyphen and an indicator of the mode. Thus, an AT&T 4425 terminal in 132 column +mode is \fBatt4425\(miw\fR. The following suffixes should be used where +possible: +.sp + +.sp +.TS +l l l +l l l . +Suffix Meaning Example +\(miw Wide mode (more than 80 columns) att4425\(miw +\(miam With auto. margins (usually default) vt100\(miam +\(minam Without automatic margins vt100\(minam +\(mi\fIn\fR Number of lines on the screen aaa\(mi60 +\(mina No arrow keys (leave them in local) c100\(mina +\(minp Number of pages of memory c100\(mi4p +\(mirv Reverse video att4415\(mirv +.TE + +.sp +.LP +To avoid conflicts with the naming conventions used in describing the different +modes of a terminal (for example, \fB-w\fR), it is recommended that a +terminal's root name not contain hyphens. Further, it is good practice to make +all terminal names used in the \fBterminfo\fR(5) database unique. Terminal +entries that are present only for inclusion in other entries via the \fBuse=\fR +facilities should have a '\fB+\fR' in their name, as in \fB4415+nl\fR. +.sp +.LP +Here are some of the known terminal names: (For a complete list, enter the +command \fBls -C /usr/share/lib/terminfo/?\fR ). +.sp + +.sp +.TS +l l +l l . +2621,hp2621 Hewlett-Packard 2621 series +2631 Hewlett-Packard 2631 line printer +2631\(mic T{ +Hewlett-Packard 2631 line printer, compressed mode +T} +2631\(mie T{ +Hewlett-Packard 2631 line printer, expanded mode +T} +2640,hp2640 Hewlett-Packard 2640 series +2645,hp2645 Hewlett-Packard 2645 series +3270 IBM Model 3270 +33,tty33 AT&T Teletype Model 33 KSR +35,tty35 AT&T Teletype Model 35 KSR +37,tty37 AT&T Teletype Model 37 KSR +4000a Trendata 4000a +4014,tek4014 TEKTRONIX 4014 +40,tty40 AT&T Teletype Dataspeed 40/2 +43,tty43 AT&T Teletype Model 43 KSR +4410,5410 T{ +AT&T 4410/5410 in 80-column mode, version 2 +T} +4410\(minfk,5410\(minfk T{ +AT&T 4410/5410 without function keys, version 1 +T} +4410\(minsl,5410\(minsl AT&T 4410/5410 without pln defined +4410\(miw,5410\(miw AT&T 4410/5410 in 132-column mode +4410v1,5410v1 T{ +AT&T 4410/5410 in 80-column mode, version 1 +T} +4410v1\(miw,5410v1\(miw T{ +AT&T 4410/5410 in 132-column mode, version 1 +T} +4415,5420 AT&T 4415/5420 in 80-column mode +4415\(minl,5420\(minl AT&T 4415/5420 without changing labels +4415\(mirv,5420\(mirv T{ +AT&T 4415/5420 80 columns in reverse video +T} +4415\(mirv\(minl,5420\(mirv\(minl T{ +AT&T 4415/5420 reverse video without changing labels +T} +4415\(miw,5420\(miw AT&T 4415/5420 in 132-column mode +4415\(miw\(minl,5420\(miw\(minl T{ +AT&T 4415/5420 in 132-column mode without changing labels +T} +4415\(miw\(mirv,5420\(miw\(mirv T{ +AT&T 4415/5420 132 columns in reverse video +T} +4418,5418 AT&T 5418 in 80-column mode +4418\(miw,5418\(miw AT&T 5418 in 132-column mode +4420 AT&T Teletype Model 4420 +4424 AT&T Teletype Model 4424 +4424-2 T{ +AT&T Teletype Model 4424 in display function group ii +T} +4425,5425 AT&T 4425/5425 +4425\(mifk,5425\(mifk AT&T 4425/5425 without function keys +4425\(minl,5425\(minl T{ +AT&T 4425/5425 without changing labels in 80-column mode +T} +4425\(miw,5425\(miw AT&T 4425/5425 in 132-column mode +4425\(miw\(mifk,5425\(miw\(mifk T{ +AT&T 4425/5425 without function keys in 132-column mode +T} +4425\(minl\(miw,5425\(minl\(miw T{ +AT&T 4425/5425 without changing labels in 132-column mode +T} +4426 AT&T Teletype Model 4426S +450 DASI 450 (same as Diablo 1620) +450\(mi12 DASI 450 in 12-pitch mode +500,att500 AT&T-IS 500 terminal +510,510a AT&T 510/510a in 80-column mode +513bct,att513 AT&T 513 bct terminal +5320 AT&T 5320 hardcopy terminal +5420_2 AT&T 5420 model 2 in 80-column mode +5420_2\(miw AT&T 5420 model 2 in 132-column mode +5620,dmd AT&T 5620 terminal 88 columns +5620\(mi24,dmd\(mi24 T{ +AT&T Teletype Model DMD 5620 in a 24x80 layer +T} +5620\(mi34,dmd\(mi34 T{ +AT&T Teletype Model DMD 5620 in a 34x80 layer +T} +610,610bct AT&T 610 bct terminal in 80-column mode +610\(miw,610bct\(miw AT&T 610 bct terminal in 132-column mode +630,630MTG AT&T 630 Multi-Tasking Graphics terminal +7300,pc7300,unix_pc AT&T UNIX PC Model 7300 +735,ti Texas Instruments TI735 and TI725 +745 Texas Instruments TI745 +dumb T{ +generic name for terminals that lack reverse line-feed and other special escape sequences +T} +hp Hewlett-Packard (same as 2645) +lp generic name for a line printer +pt505 AT&T Personal Terminal 505 (22 lines) +pt505\(mi24 T{ +AT&T Personal Terminal 505 (24-line mode) +T} +sync T{ +generic name for synchronous Teletype Model 4540-compatible terminals +T} +.TE + +.sp +.LP +Commands whose behavior depends on the type of terminal should accept arguments +of the form \fB-T\fR\fIterm\fR where \fIterm\fR is one of the names given +above; if no such argument is present, such commands should obtain the terminal +type from the environment variable \fBTERM\fR, which, in turn, should contain +\fIterm\fR. +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/share/lib/terminfo/?/*\fR\fR +.ad +.sp .6 +.RS 4n +compiled terminal description database +.RE + +.SH SEE ALSO +.sp +.LP +.BR sh (1), +.BR stty (1), +.BR tabs (1), +.BR tput (1), +.BR vi (1), +.BR curses (3CURSES), +.BR profile (5), +.BR terminfo (5), +.BR environ (7), +.BR infocmp (8) diff --git a/usr/src/man/man7/threads.7 b/usr/src/man/man7/threads.7 new file mode 100644 index 0000000000..8b6cd939b8 --- /dev/null +++ b/usr/src/man/man7/threads.7 @@ -0,0 +1,502 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2016 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 THREADS 7 "Mar 27, 2016" +.SH NAME +threads, pthreads \- POSIX pthreads, c11, and illumos threads concepts +.SH SYNOPSIS +.SS "POSIX" +.nf +gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +.fi + +.LP +.nf +#include <pthread.h> +.fi + +.SS "C11" +.nf +gcc -std=c11 -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +.fi + +.LP +.nf +#include <threads.h> +.fi + +.SS "illumos" +.nf +gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +.fi + +.LP +.nf +#include <sched.h> +.fi + +.LP +.nf +#include <thread.h> +.fi + +.SH DESCRIPTION +A thread is an independent source of execution within a process. Every process +is created with a single thread, which calls the +.B main +function. A process may have multiple threads, all of which are scheduled +independently by the system and may run concurrently. Threads within a process +all use the same address space and as a result can access all data in the +process; however, each thread is created with its own attributes and its own +stack. When a thread is created, it inherits the signal mask of the thread which +created it, but it has no pending signals. +.sp +.LP +All threads of execution have their own, independent life time, though it is +ultimately bounded by the life time of the process. If the process terminates +for any reason, whether due to a call to \fBexit\fR(3C), the receipt of a fatal +signal, or some other reason, then all threads within the process are +terminated. Threads may themselves exit and status information of them may be +obtained, for more information, see the \fBpthread_detach\fR(3C), +\fBpthread_join\fR(3C), and \fBpthread_exit\fR(3C) functions, and their +equivalents as described in the tables later on in the manual. +.sp +.LP +Most hardware platforms do not have any special synchronization for data objects +which may be accessed concurrently from multiple threads of execution. To avoid +such problems, programs may use atomic operations (see \fBatomic_ops\fR(3C)) and +locking primitives, such as mutexes, readers/writer locks, condition variables, +and semaphores. Note, that depending on the hardware platform, memory +synchronization may be necessary, for more information, see \fBmembar_ops\fR(3C). +.LP +POSIX, C11, and illumos threads each have their own implementation within +\fBlibc\fR(3LIB). All implementations are interoperable, their functionality +similar, and can be used within the same application. Only POSIX threads are +guaranteed to be fully portable to other POSIX-compliant environments. C11 +threads are an optional part of ISO C11 and may not exist on every ISO C11 +platform. POSIX, C11, and illumos threads require different source and include +files. See \fBSYNOPSIS\fR. +.SS "Similarities" +Most of the POSIX and illumos threading functions have counterparts with each +other. POSIX function names, with the exception of the semaphore names, have a +"\fBpthread\fR" prefix. Function names for similar POSIX and illumos functions +have similar endings. Typically, similar POSIX and illumos functions have the +same number and use of arguments. +.SS "Differences" +POSIX pthreads and illumos threads differ in the following ways: +.RS +4 +.TP +.ie t \(bu +.el o +POSIX threads are more portable. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +POSIX threads establish characteristics for each thread according to +configurable attribute objects. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +POSIX pthreads implement thread cancellation. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +POSIX pthreads enforce scheduling algorithms. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +POSIX pthreads allow for clean-up handlers for \fBfork\fR(2) calls. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +illumos threads can be suspended and continued. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +illumos threads implement daemon threads, for whose demise the process does not +wait. +.RE +.SS "Comparison to C11 Threads" +C11 threads are not as functional as either POSIX or illumos threads. C11 +threads only support intra-process locking and do not have any form of +readers/writer locking or semaphores. In general, POSIX threads will be more +portable than C11 threads, all POSIX-compliant systems support pthreads; +however, not all C environments support C11 Threads. +.sp +.LP +In addition to lacking other common synchronization primitives, the ISO/IEC +standard for C11 threads does not have rich error semantics. In an effort to not +extend the set of error numbers standardized in ISO/IEC C11, none of the +routines set errno and instead multiple distinguishable errors, aside from the +equivalent to ENOMEM and EBUSY, are all squashed into one. As such, users of the +platform are encouraged to use POSIX threads, unless a portability concern +dictates otherwise. + +.SH FUNCTION COMPARISON +The following table compares the POSIX pthreads, C11 threads, and illumos +threads functions. When a comparable interface is not available either in POSIX +pthreads, C11 threads or illumos threads, a hyphen (\fB-\fR) appears in the +column. +.SS "Functions Related to Creation" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_create()\fR \fBthr_create()\fR \fBthrd_create()\fR +\fBpthread_attr_init()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setdetachstate()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getdetachstate()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setinheritsched()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getinheritsched()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setschedparam()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getschedparam()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setschedpolicy()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getschedpolicy()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setscope()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getscope()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setstackaddr()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getstackaddr()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setstacksize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getstacksize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_getguardsize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_setguardsize()\fR \fB-\fR \fB-\fR +\fBpthread_attr_destroy()\fR \fB-\fR \fB-\fR +\fB-\fR \fBthr_min_stack()\fR \fB-\fR +.TE + +.SS "Functions Related to Exit" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_exit()\fR \fBthr_exit()\fR \fBthrd_exit()\fR +\fBpthread_join()\fR \fBthr_join()\fR \fBthrd_join()\fR +\fBpthread_detach()\fR \fB-\fR \fBthrd_detach()\fR +.TE + +.SS "Functions Related to Thread Specific Data" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_key_create()\fR \fBthr_keycreate()\fR \fBtss_create()\fR +\fBpthread_setspecific()\fR \fBthr_setspecific()\fR \fBtss_set()\fR +\fBpthread_getspecific()\fR \fBthr_getspecific()\fR \fBtss_get()\fR +\fBpthread_key_delete()\fR \fB-\fR \fBtss_delete()\fR +.TE + +.SS "Functions Related to Signals" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_sigmask()\fR \fBthr_sigsetmask()\fR \fB-\fR +\fBpthread_kill()\fR \fBthr_kill()\fR \fB-\fR +.TE + +.SS "Functions Related to IDs" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBc11\fR +\fBpthread_self()\fR \fBthr_self()\fR \fBthrd_current()\fR +\fBpthread_equal()\fR \fB-\fR \fBthrd_equal()\fR +\fB-\fR \fBthr_main()\fR \fB-\fR +.TE + +.SS "Functions Related to Scheduling" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fB-\fR \fBthr_yield()\fR \fBthrd_yield()\fR +\fB-\fR \fBthr_suspend()\fR \fB-\fR +\fB-\fR \fBthr_continue()\fR \fB-\fR +\fBpthread_setconcurrency()\fR \fBthr_setconcurrency()\fR \fB-\fR +\fBpthread_getconcurrency()\fR \fBthr_getconcurrency()\fR \fB-\fR +\fBpthread_setschedparam()\fR \fBthr_setprio()\fR \fB-\fR +\fBpthread_setschedprio()\fR \fBthr_setprio()\fR \fB-\fR +\fBpthread_getschedparam()\fR \fBthr_getprio()\fR \fB-\fR +.TE + +.SS "Functions Related to Cancellation" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_cancel()\fR \fB-\fR \fB-\fR +\fBpthread_setcancelstate()\fR \fB-\fR \fB-\fR +\fBpthread_setcanceltype()\fR \fB-\fR \fB-\fR +\fBpthread_testcancel()\fR \fB-\fR \fB-\fR +\fBpthread_cleanup_pop()\fR \fB-\fR \fB-\fR +\fBpthread_cleanup_push()\fR \fB-\fR \fB-\fR +.TE + +.SS "Functions Related to Mutexes" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBc11\fR +\fBpthread_mutex_init()\fR \fBmutex_init()\fR \fBmtx_init()\fR +\fBpthread_mutexattr_init()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setpshared()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getpshared()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setprotocol()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getprotocol()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_settype()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_gettype()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_setrobust()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_getrobust()\fR \fB-\fR \fB-\fR +\fBpthread_mutexattr_destroy()\fR \fB-\fR \fBmtx_destroy()\fR +\fBpthread_mutex_setprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutex_getprioceiling()\fR \fB-\fR \fB-\fR +\fBpthread_mutex_lock()\fR \fBmutex_lock()\fR \fBmtx_lock()\fR +\fBpthread_mutex_timedlock()\fR \fB-\fR \fBmtx_timedlock()\fR +\fBpthread_mutex_trylock()\fR \fBmutex_trylock()\fR \fBmtx_trylock()\fR +\fBpthread_mutex_unlock()\fR \fBmutex_unlock()\fR \fBmtx_unlock()\fR +\fBpthread_mutex_destroy()\fR \fBmutex_destroy()\fR \fBmtx_destroy()\fR +.TE + +.SS "Functions Related to Condition Variables" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_cond_init()\fR \fBcond_init()\fR \fBcnd_init()\fR +\fBpthread_condattr_init()\fR \fB-\fR \fB-\fR +\fBpthread_condattr_setpshared()\fR \fB-\fR \fB-\fR +\fBpthread_condattr_getpshared()\fR \fB-\fR \fB-\fR +\fBpthread_condattr_destroy()\fR \fB-\fR \fB-\fR +\fBpthread_cond_wait()\fR \fBcond_wait()\fR \fBcnd_wait()\fR +\fBpthread_cond_timedwait()\fR \fBcond_timedwait()\fR \fBcond_timedwait()\fR +\fBpthread_cond_signal()\fR \fBcond_signal()\fR \fBcnd_signal()\fR +\fBpthread_cond_broadcast()\fR \fBcond_broadcast()\fR \fBcnd_broadcast()\fR +\fBpthread_cond_destroy()\fR \fBcond_destroy()\fR \fBcnd_destroy()\fR +.TE + +.SS "Functions Related to Reader/Writer Locking" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_rwlock_init()\fR \fBrwlock_init()\fR \fB-\fR +\fBpthread_rwlock_rdlock()\fR \fBrw_rdlock()\fR \fB-\fR +\fBpthread_rwlock_tryrdlock()\fR \fBrw_tryrdlock()\fR \fB-\fR +\fBpthread_rwlock_wrlock()\fR \fBrw_wrlock()\fR \fB-\fR +\fBpthread_rwlock_trywrlock()\fR \fBrw_trywrlock()\fR \fB-\fR +\fBpthread_rwlock_unlock()\fR \fBrw_unlock()\fR \fB-\fR +\fBpthread_rwlock_destroy()\fR \fBrwlock_destroy()\fR \fB-\fR +\fBpthread_rwlockattr_init()\fR \fB-\fR \fB-\fR +\fBpthread_rwlockattr_destroy()\fR \fB-\fR \fB-\fR +\fBpthread_rwlockattr_getpshared()\fR \fB-\fR \fB-\fR +\fBpthread_rwlockattr_setpshared()\fR \fB-\fR \fB-\fR +.TE + +.SS "Functions Related to Semaphores" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBsem_init()\fR \fBsema_init()\fR \fB-\fR +\fBsem_open()\fR \fB-\fR \fB-\fR +\fBsem_close()\fR \fB-\fR \fB-\fR +\fBsem_wait()\fR \fBsema_wait()\fR \fB-\fR +\fBsem_trywait()\fR \fBsema_trywait()\fR \fB-\fR +\fBsem_post()\fR \fBsema_post()\fR \fB-\fR +\fBsem_getvalue()\fR \fB-\fR \fB-\fR +\fBsem_unlink()\fR \fB-\fR \fB-\fR +\fBsem_destroy()\fR \fBsema_destroy()\fR \fB-\fR +.TE + +.SS "Functions Related to fork(\|) Clean Up" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_atfork()\fR \fB-\fR \fB-\fR +.TE + +.SS "Functions Related to Limits" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fBpthread_once()\fR \fB-\fR \fBcall_once()\fR +.TE + +.SS "Functions Related to Debugging" + +.TS +l l l +l l l . +\fBPOSIX\fR \fBillumos\fR \fBC11\fR +\fB-\fR \fBthr_stksegment()\fR \fB-\fR +.TE + +.SH LOCKING +.SS "Synchronization" +Multithreaded behavior is asynchronous, and therefore, optimized for +concurrent and parallel processing. As threads, always from within the same +process and sometimes from multiple processes, share global data with each +other, they are not guaranteed exclusive access to the shared data at any point +in time. Securing mutually exclusive access to shared data requires +synchronization among the threads. Both POSIX and illumos implement four +synchronization mechanisms: mutexes, condition variables, reader/writer locking +(\fIoptimized frequent-read occasional-write mutex\fR), and semaphores, where as +C11 threads only implement two mechanisms: mutexes and condition variables. +.sp +.LP +Synchronizing multiple threads diminishes their concurrency. The coarser the +grain of synchronization, that is, the larger the block of code that is locked, +the lesser the concurrency. +.SS "MT \fBfork()\fR" +If a threads program calls \fBfork\fR(2), it implicitly calls \fBfork1\fR(2), +which replicates only the calling thread. Should there be any outstanding +mutexes throughout the process, the application should call +\fBpthread_atfork\fR(3C) to wait for and acquire those mutexes prior to calling +\fBfork()\fR. +.SH SCHEDULING +.SS "POSIX Threads" +illumos supports the following three POSIX scheduling policies: +.sp +.ne 2 +.na +\fB\fBSCHED_OTHER\fR\fR +.ad +.RS 15n +Traditional Timesharing scheduling policy. It is based on the timesharing (TS) +scheduling class. +.RE + +.sp +.ne 2 +.na +\fB\fBSCHED_FIFO\fR\fR +.ad +.RS 15n +First-In-First-Out scheduling policy. Threads scheduled to this policy, if not +preempted by a higher priority, will proceed until completion. Such threads are +in real-time (RT) scheduling class. The calling process must have a effective +user \fBID\fR of \fB0\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBSCHED_RR\fR\fR +.ad +.RS 15n +Round-Robin scheduling policy. Threads scheduled to this policy, if not +preempted by a higher priority, will execute for a time period determined by +the system. Such threads are in real-time (RT) scheduling class and the calling +process must have a effective user \fBID\fR of \fB0\fR. +.RE + +.sp +.LP +In addition to the POSIX-specified scheduling policies above, illumos also +supports these scheduling policies: +.sp +.ne 2 +.na +\fB\fBSCHED_IA\fR\fR +.ad +.RS 13n +Threads are scheduled according to the Inter-Active Class (IA) policy as +described in \fBpriocntl\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBSCHED_FSS\fR\fR +.ad +.RS 13n +Threads are scheduled according to the Fair-Share Class (FSS) policy as +described in \fBpriocntl\fR(2). +.RE + +.sp +.ne 2 +.na +\fB\fBSCHED_FX\fR\fR +.ad +.RS 13n +Threads are scheduled according to the Fixed-Priority Class (FX) policy as +described in \fBpriocntl\fR(2). +.RE + +.SS "illumos Threads" +Only scheduling policy supported is \fBSCHED_OTHER\fR, which is timesharing, +based on the \fBTS\fR scheduling class. +.SH ERRORS +In a multithreaded application, \fBEINTR\fR can be returned from blocking +system calls when another thread calls \fBforkall\fR(2). +.SH USAGE +.SS "\fB-mt\fR compiler option" +The \fB-mt\fR compiler option compiles and links for multithreaded code. It +compiles source files with \(mi\fBD_REENTRANT\fR and augments the set of +support libraries properly. +.sp +.LP +Users of other compilers such as gcc and clang should manually set +\(mi\fBD_REENTRANT\fR on the compilation line. There are no other libraries or +flags necessary. +.SH ATTRIBUTES +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +MT-Level MT-Safe, Fork 1-Safe +.TE + +.SH SEE ALSO +.BR crle (1), +.BR fork (2), +.BR priocntl (2), +.BR pthread_atfork (3C), +.BR pthread_create (3C), +.BR libpthread (3LIB), +.BR librt (3LIB), +.BR libthread (3LIB), +.BR attributes (7), +.BR standards (7) +.sp +.LP +\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man7/timerfd.7 b/usr/src/man/man7/timerfd.7 new file mode 100644 index 0000000000..c6fd34e50d --- /dev/null +++ b/usr/src/man/man7/timerfd.7 @@ -0,0 +1,47 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved. +.\" +.Dd Feb 23, 2015 +.Dt TIMERFD 7 +.Os +.Sh NAME +.Nm timerfd +.Nd Linux-compatible timer notification facility +.Sh SYNOPSIS +.In sys/timerfd.h +.Sh DESCRIPTION +.Nm +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 +.Xr poll 2 / +.Xr port_get 3C +or -- if this is deemed of unacceptably poor resolution -- create a POSIX timer +via +.Xr timer_create 3C +and use the resulting signal to induce an +.Sy EINTR +to polling threads. (For code that need not be +portable, the +.Sy SIGEV_PORT +signal notification allows for explicit, event-oriented timer notification to be +sent to a specified port; see +.Xr signal.h 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 +.Xr timerfd_create 3C , +.Xr timerfd_gettime 3C , +.Xr timerfd_settime 3C diff --git a/usr/src/man/man7/trusted_extensions.7 b/usr/src/man/man7/trusted_extensions.7 new file mode 100644 index 0000000000..049004d1ce --- /dev/null +++ b/usr/src/man/man7/trusted_extensions.7 @@ -0,0 +1,42 @@ +'\" te +.\" Copyright 2017 Peter Tribble +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH TRUSTED_EXTENSIONS 7 "Aug 3, 2017" +.SH NAME +trusted_extensions \- Trusted Extensions +.SH DESCRIPTION +.LP +Trusted Extensions software is a specific configuration +of the Operating System. Trusted Extensions +provides labels for local objects and processes, +for zones and file systems, and for network +communications. These labels are used to implement a Multilevel Security (MLS) +policy that restricts the flow of information based on label relationships. In +contrast to Discretionary Access Control (DAC) based on ownership, the MLS +policy enforced by Trusted Extensions is an example of Mandatory Access Control +(MAC). +.sp +.LP +By default, Trusted Extensions software is disabled. It is enabled and disabled +(but not configured) by the \fBlabeld\fR(8) service, identified by the FMRI: +.sp +.in +2 +.nf +svc:/system/labeld:default +.fi +.in -2 +.sp + +.sp +.LP +The system must be +rebooted after enabling or disabling \fBlabeld\fR to activate or deactivate +Trusted Extensions software. +.SH SEE ALSO +.LP +.BR label_encodings (5), +.BR labels (7), +.BR labeld (8) diff --git a/usr/src/man/man7/version.4th.7 b/usr/src/man/man7/version.4th.7 new file mode 100644 index 0000000000..cd234971cf --- /dev/null +++ b/usr/src/man/man7/version.4th.7 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2011-2013 Devin Teske +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2018 +.Dt VERSION.4TH 7 +.Os +.Sh NAME +.Nm version.4th +.Nd loader version string boot module +.Sh DESCRIPTION +The file that goes by the name of +.Nm +is a set of commands designed to draw the boot loader +version at the bottom-right of the screen. +The commands of +.Nm +by themselves are not enough for most uses. +Please refer to the +examples below for the most common situations, and to +.Xr loader 7 +for additional commands. +.Pp +Before using any of the commands provided in +.Nm , +it must be included +through the command: +.Pp +.Dl include version.4th +.Pp +This line is present in the default +.Pa /boot/forth/menu.rc +file, so it is not needed (and should not be re-issued) in a normal setup. +.Pp +The commands provided by it are: +.Pp +.Bl -tag -width disable-module_module -compact -offset indent +.It Ic print_version +Prints the contents of the +.Va loader_version +environment variable right-justified at the column +.Va loader_version_x +and row +.Va loader_version_y . +.El +.Pp +The environment variables that effect its behavior are: +.Bl -tag -width bootfile -offset indent +.It Va loader_version +Set automatically by +.Xr loader 7 , +but you can override it by setting in +.Xr loader.conf 5 . +This should be the version of boot loader used. +.It Va loader_version_x +Sets the desired ending column position of +.Va loader_version . +Default is 80. +.It Va loader_version_y +Sets the desired ending row position of +.Va loader_version . +Default is 24. +.It Va loader_color +If set to +.Dq Li NO +(case-insensitive) or +.Dq Li 0 , +causes the version to be printed without color +.Pq default is ANSI Cyan . +.El +.Sh FILES +.Bl -tag -width /boot/version.4th -compact +.It Pa /boot/loader +The +.Xr loader 7 . +.It Pa /boot/forth/version.4th +.Nm +itself. +.It Pa /boot/loader.rc +.Xr loader 7 +bootstrapping script. +.El +.Sh EXAMPLES +Override +.Xr loader 7 +version in +.Xr loader.conf 5 : +.Pp +.Bd -literal -offset indent -compact +loader_version="loader 1.1" +.Ed +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr color.4th 7 , +.Xr loader 7 diff --git a/usr/src/man/man7/vgrindefs.7 b/usr/src/man/man7/vgrindefs.7 new file mode 100644 index 0000000000..4ec0ee9db7 --- /dev/null +++ b/usr/src/man/man7/vgrindefs.7 @@ -0,0 +1,255 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH VGRINDEFS 7 "Aug 10, 1994" +.SH NAME +vgrindefs \- vgrind's language definition data base +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/vgrindefs\fR +.fi + +.SH DESCRIPTION +.sp +.LP +\fBvgrindefs\fR contains all language definitions for \fBvgrind\fR(1). +Capabilities in \fBvgrindefs\fR are of two types: Boolean capabilities which +indicate that the language has some particular feature and string capabilities +which give a regular expression or keyword list. Entries may continue onto +multiple lines by giving a \e as the last character of a line. Lines starting +with # are comments. +.SS "Capabilities" +.sp +.LP +The following table names and describes each capability. +.sp + +.sp +.TS +box; +c | c | c +l | l | l . +Name Type Description +_ +\fBab\fR \fBstr\fR T{ +Regular expression for the start of an alternate form comment +T} +_ +\fBae\fR \fBstr\fR T{ +Regular expression for the end of an alternate form comment +T} +_ +\fBbb\fR \fBstr\fR T{ +Regular expression for the start of a block +T} +_ +\fBbe\fR \fBstr\fR T{ +Regular expression for the end of a lexical block +T} +_ +\fBcb\fR \fBstr\fR T{ +Regular expression for the start of a comment +T} +_ +\fBce\fR \fBstr\fR T{ +Regular expression for the end of a comment +T} +_ +\fBid\fR \fBstr\fR T{ +String giving characters other than letters and digits that may legally occur in identifiers (default `_') +T} +_ +\fBkw\fR \fBstr\fR A list of keywords separated by spaces +_ +\fBlb\fR \fBstr\fR T{ +Regular expression for the start of a character constant +T} +_ +\fBle\fR \fBstr\fR T{ +Regular expression for the end of a character constant +T} +_ +\fBoc\fR \fBbool\fR T{ +Present means upper and lower case are equivalent +T} +_ +\fBpb\fR \fBstr\fR T{ +Regular expression for start of a procedure +T} +_ +\fBpl\fR \fBbool\fR T{ +Procedure definitions are constrained to the lexical level matched by the `px' capability +T} +_ +\fBpx\fR \fBstr\fR T{ +A match for this regular expression indicates that procedure definitions may occur at the next lexical level. Useful for lisp-like languages in which procedure definitions occur as subexpressions of defuns. +T} +_ +\fBsb\fR \fBstr\fR T{ +Regular expression for the start of a string +T} +_ +\fBse\fR \fBstr\fR T{ +Regular expression for the end of a string +T} +_ +\fBtc\fR \fBstr\fR T{ +Use the named entry as a continuation of this one +T} +_ +\fBtl\fR \fBbool\fR T{ +Present means procedures are only defined at the top lexical level +T} +.TE + +.SS "Regular Expressions" +.sp +.LP +\fBvgrindefs\fR uses regular expressions similar to those of \fBex\fR(1) and +\fBlex\fR(1). The characters `^', `$', `:', and `\e' are reserved characters +and must be `quoted' with a preceding \e if they are to be included as normal +characters. The metasymbols and their meanings are: +.sp +.ne 2 +.na +\fB\fB$\fR\fR +.ad +.RS 7n +The end of a line +.RE + +.sp +.ne 2 +.na +\fB\fB^\fR\fR +.ad +.RS 7n +The beginning of a line +.RE + +.sp +.ne 2 +.na +\fB\fB\ed\fR\fR +.ad +.RS 7n +A delimiter (space, tab, newline, start of line) +.RE + +.sp +.ne 2 +.na +\fB\fB\ea\fR\fR +.ad +.RS 7n +Matches any string of symbols (like `.*' in lex) +.RE + +.sp +.ne 2 +.na +\fB\fB\ep\fR\fR +.ad +.RS 7n +Matches any identifier. In a procedure definition (the `pb' capability) the +string that matches this symbol is used as the procedure name. +.RE + +.sp +.ne 2 +.na +\fB\fB()\fR\fR +.ad +.RS 7n +Grouping +.RE + +.sp +.ne 2 +.na +\fB\fB|\fR\fR +.ad +.RS 7n +Alternation +.RE + +.sp +.ne 2 +.na +\fB\fB?\fR\fR +.ad +.RS 7n +Last item is optional +.RE + +.sp +.ne 2 +.na +\fB\fB\ee\fR\fR +.ad +.RS 7n +Preceding any string means that the string will not match an input string if +the input string is preceded by an escape character (\e). This is typically +used for languages (like C) that can include the string delimiter in a string +by escaping it. +.RE + +.sp +.LP +Unlike other regular expressions in the system, these match words and not +characters. Hence something like `(tramp|steamer)flies?' would match `tramp', +`steamer', `trampflies', or `steamerflies'. Contrary to some forms of regular +expressions, \fBvgrindef\fR alternation binds very tightly. Grouping +parentheses are likely to be necessary in expressions involving alternation. +.SS "Keyword List" +.sp +.LP +The keyword list is just a list of keywords in the language separated by +spaces. If the `oc' boolean is specified, indicating that upper and lower case +are equivalent, then all the keywords should be specified in lower case. +.SH EXAMPLES +.LP +\fBExample 1 \fRA sample program. +.sp +.LP +The following entry, which describes the C language, is typical of a language +entry. + +.sp +.in +2 +.nf +C|c|the C programming language:\e + :pb=^\ed?*?\ed?\ep\ed?(\ea?\e)(\ed|{):bb={:be=}:cb=/*:ce=*/:sb=":se=\ee":\e + :le=\ee':tl:\e + :kw=asm auto break case char continue default do double else enum\e + extern float for fortran goto if int long register return short\e + sizeof static struct switch typedef union unsigned void while #define\e + #else #endif #if #ifdef #ifndef #include #undef # define endif\e + ifdef ifndef include undef defined: +.fi +.in -2 +.sp + +.sp +.LP +Note that the first field is just the language name (and any variants of it). +Thus the C language could be specified to \fBvgrind\fR(1) as `c' or `C'. + +.SH FILES +.sp +.ne 2 +.na +\fB\fB/usr/lib/vgrindefs\fR\fR +.ad +.RS 22n +file containing vgrind descriptions +.RE + +.SH SEE ALSO +.sp +.LP +.BR ex (1), +.BR lex (1), +.BR troff (1), +.BR vgrind (1) diff --git a/usr/src/man/man7/zones.7 b/usr/src/man/man7/zones.7 new file mode 100644 index 0000000000..2151928b13 --- /dev/null +++ b/usr/src/man/man7/zones.7 @@ -0,0 +1,257 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.\" +.\" Copyright 2020 Joyent, Inc. +.TH ZONES 7 "May 23, 2021" +.SH NAME +zones \- Solaris application containers +.SH DESCRIPTION +The zones facility in Solaris provides an isolated environment for running +applications. Processes running in a zone are prevented from monitoring or +interfering with other activity in the system. Access to other processes, +network interfaces, file systems, devices, and inter-process communication +facilities are restricted to prevent interaction between processes in different +zones. +.sp +.LP +The privileges available within a zone are restricted to prevent operations +with system-wide impact. See \fBprivileges\fR(7). +.sp +.LP +You can configure and administer zones with the \fBzoneadm\fR(8) and +\fBzonecfg\fR(8) utilities. You can specify the configuration details a zone, +install file system contents including software packages into the zone, and +manage the runtime state of the zone. You can use the \fBzlogin\fR(1) to run +commands within an active zone. You can do this without logging in through a +network-based login server such as \fBsshd\fR(8). +.sp +.LP +The autobooting of zones is enabled and disabled by the zones service, +identified by the FMRI: +.sp +.LP +svc:/system/zones:default +.sp +.LP +See \fBzoneadm\fR(8). Note that a zone has an \fBautoboot\fR property, which +can be set to \fBtrue\fR (always autoboot). However, if the zones service is +disabled, autoboot will not occur, regardless of the setting of the autoboot +property for a given zone. See \fBzonecfg\fR(8). +.sp +.LP +An alphanumeric name and numeric ID identify each active zone. Alphanumeric +names are configured using the \fBzonecfg\fR(8) utility. Numeric IDs are +automatically assigned when the zone is booted. The \fBzonename\fR(1) utility +reports the current zone name, and the \fBzoneadm\fR(8) utility can be used to +report the names and IDs of configured zones. +.sp +.LP +A zone can be in one of several states: +.sp +.ne 2 +.na +\fB\fBCONFIGURED\fR\fR +.ad +.RS 17n +Indicates that the configuration for the zone has been completely specified and +committed to stable storage. +.RE + +.sp +.ne 2 +.na +\fB\fBINCOMPLETE\fR\fR +.ad +.RS 17n +Indicates that the zone is in the midst of being installed or uninstalled, or +was interrupted in the midst of such a transition. +.RE + +.sp +.ne 2 +.na +\fB\fBINSTALLED\fR\fR +.ad +.RS 17n +Indicates that the zone's configuration has been instantiated on the system: +packages have been installed under the zone's root path. +.RE + +.sp +.ne 2 +.na +\fB\fBREADY\fR\fR +.ad +.RS 17n +Indicates that the "virtual platform" for the zone has been established. For +instance, file systems have been mounted, devices have been configured, but no +processes associated with the zone have been started. +.RE + +.sp +.ne 2 +.na +\fB\fBRUNNING\fR\fR +.ad +.RS 17n +Indicates that user processes associated with the zone application environment +are running. +.RE + +.sp +.ne 2 +.na +\fB\fBSHUTTING_DOWN\fR\fR +.ad +.br +.na +\fB\fBDOWN\fR\fR +.ad +.RS 17n +Indicates that the zone is being halted. The zone can become stuck in one of +these states if it is unable to tear down the application environment state +(such as mounted file systems) or if some portion of the virtual platform +cannot be destroyed. Such cases require operator intervention. +.RE + +.SS "Process Access Restrictions" +Processes running inside a zone (aside from the global zone) have restricted +access to other processes. Only processes in the same zone are visible through +\fB/proc\fR (see \fBproc\fR(5) or through system call interfaces that take +process IDs such as \fBkill\fR(2) and \fBpriocntl\fR(2). Attempts to access +processes that exist in other zones (including the global zone) fail with the +same error code that would be issued if the specified process did not exist. +.SS "Privilege Restrictions" +Processes running within a non-global zone are restricted to a subset of +privileges, in order to prevent one zone from being able to perform operations +that might affect other zones. The set of privileges limits the capabilities of +privileged users (such as the super-user or root user) within the zone. The +list of privileges available within a zone can be displayed using the +\fBppriv\fR(1) utility. For more information about privileges, see +\fBprivileges\fR(7). +.SS "Device Restrictions" +The set of devices available within a zone is restricted, to prevent a process +in one zone from interfering with processes in other zones. For example, a +process in a zone should not be able to modify kernel memory using +\fB/dev/kmem\fR, or modify the contents of the root disk. Thus, by default, +only a few pseudo devices considered safe for use within a zone are available. +Additional devices can be made available within specific zones using the +\fBzonecfg\fR(8) utility. +.sp +.LP +The device and privilege restrictions have a number of effects on the utilities +that can run in a non-global zone. For example, the \fBeeprom\fR(8), +\fBprtdiag\fR(8), and \fBprtconf\fR(8) utilities do not work in a zone since +they rely on devices that are not normally available. +.SS "Brands" +A zone may be assigned a brand when it is initially created. A branded zone is +one whose software does not match that software found in the global zone. The +software may include Solaris software configured or laid out differently, or it +may include non-Solaris software. The particular collection of software is +called a "brand" (see \fBbrands\fR(7)). Once installed, a zone's brand may not +be changed unless the zone is first uninstalled. +.SS "File Systems" +Each zone has its own section of the file system hierarchy, rooted at a +directory known as the zone root. Processes inside the zone can access only +files within that part of the hierarchy, that is, files that are located +beneath the zone root. This prevents processes in one zone from corrupting or +examining file system data associated with another zone. The \fBchroot\fR(8) +utility can be used within a zone, but can only restrict the process to a root +path accessible within the zone. +.sp +.LP +In order to preserve file system space, sections of the file system can be +mounted into one or more zones using the read-only option of the +\fBlofs\fR(4FS) file system. This allows the same file system data to be shared +in multiple zones, while preserving the security guarantees supplied by zones. +.sp +.LP +NFS and autofs mounts established within a zone are local to that zone; they +cannot be accessed from other zones, including the global zone. The mounts are +removed when the zone is halted or rebooted. +.sp +.LP +A zone can share filesystems using \fBnfs\fR(5) or \fBsmb\fR(5) +subject to the restrictions earlier in this section, plus the additional +restriction that file sharing can only be done from filesystems a zone +completely controls. Some \fBbrands\fR(7) do not have the zone root set to a +filesystem boundary. \fBsharefs\fR(4FS) can instantiate per-zone subject to +the brand restrictions. +.SS "Networking" +A zone has its own port number space for \fBTCP\fR, \fBUDP\fR, and \fBSCTP\fR +applications and typically one or more separate \fBIP\fR addresses (but some +configurations of Trusted Extensions share IP address(es) between zones). +.sp +.LP +For the \fBIP\fR layer (\fBIP\fR routing, \fBARP\fR, \fBIPsec\fR, \fBIP\fR +Filter, and so on) a zone can either share the configuration and state with the +global zone (a shared-\fBIP\fR zone), or have its distinct \fBIP\fR layer +configuration and state (an exclusive-\fBIP\fR zone). +.sp +.LP +If a zone is to be connected to the same datalink, that is, be on the same +\fBIP\fR subnet or subnets as the global zone, then it is appropriate for the +zone to use the shared \fBIP\fR instance. +.sp +.LP +If a zone needs to be isolated at the \fBIP\fR layer on the network, for +instance being connected to different \fBVLAN\fRs or different \fBLAN\fRs than +the global zone and other non-global zones, then for isolation reasons the zone +should have its exclusive \fBIP\fR. +.sp +.LP +A shared-\fBIP\fR zone is prevented from doing certain things towards the +network (such as changing its \fBIP\fR address or sending spoofed \fBIP\fR or +Ethernet packets), but an exclusive-\fBIP\fR zone has more or less the same +capabilities towards the network as a separate host that is connected to the +same network interface. In particular, the superuser in such a zone can change +its \fBIP\fR address and spoof \fBARP\fR packets. +.sp +.LP +The shared-\fBIP\fR zones are assigned one or more network interface names and +\fBIP\fR addresses in \fBzonecfg\fR(8). The network interface name(s) must +also be configured in the global zone. +.sp +.LP +The exclusive-\fBIP\fR zones are assigned one or more network interface names +in \fBzonecfg\fR(8). The network interface names must be exclusively assigned +to that zone, that is, it (or they) can not be assigned to some other running +zone, nor can they be used by the global zone. +.sp +.LP +The full \fBIP\fR-level functionality in the form of \fBDHCP\fR client, +\fBIPsec\fR and \fBIP\fR Filter, is available in exclusive-\fBIP\fR zones and +not in shared-\fBIP\fR zones. +.SS "Host Identifiers" +A zone is capable of emulating a 32-bit host identifier, which can be +configured via \fBzonecfg\fR(8), for the purpose of system consolidation. If a +zone emulates a host identifier, then commands such as \fBhostid\fR(1) and +\fBsysdef\fR(8) as well as C interfaces such as \fBsysinfo\fR(2) and +\fBgethostid\fR(3C) that are executed within the context of the zone will +display or return the zone's emulated host identifier rather than the host +machine's identifier. +.SH SEE ALSO +.BR hostid (1), +.BR zlogin (1), +.BR zonename (1), +.BR kill (2), +.BR priocntl (2), +.BR sysinfo (2), +.BR gethostid (3C), +.BR getzoneid (3C), +.BR ucred_get (3C), +.BR sharefs (4FS), +.BR nfs (5), +.BR proc (5), +.BR smb (5), +.BR attributes (7), +.BR brands (7), +.BR privileges (7), +.BR sshd (8), +.BR sysdef (8), +.BR zoneadm (8), +.BR zonecfg (8), +.BR crgetzoneid (9F) diff --git a/usr/src/man/man7/zpool-features.7 b/usr/src/man/man7/zpool-features.7 new file mode 100644 index 0000000000..146bfc5262 --- /dev/null +++ b/usr/src/man/man7/zpool-features.7 @@ -0,0 +1,835 @@ +'\" te +.\" Copyright (c) 2013, 2017 by Delphix. All rights reserved. +.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. +.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. +.\" Copyright (c) 2014 Integros [integros.com] +.\" 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 ZPOOL-FEATURES 7 "May 15, 2019" +.SH NAME +zpool\-features \- ZFS pool feature descriptions +.SH DESCRIPTION +.LP +ZFS pool on\-disk format versions are specified via "features" which replace +the old on\-disk format numbers (the last supported on\-disk format number is +28). To enable a feature on a pool use the \fBupgrade\fR subcommand of the +\fBzpool\fR(8) command, or set the \fBfeature@\fR\fIfeature_name\fR property +to \fBenabled\fR. +.sp +.LP +The pool format does not affect file system version compatibility or the ability +to send file systems between pools. +.sp +.LP +Since most features can be enabled independently of each other the on\-disk +format of the pool is specified by the set of all features marked as +\fBactive\fR on the pool. If the pool was created by another software version +this set may include unsupported features. +.SS "Identifying features" +.LP +Every feature has a guid of the form \fIcom.example:feature_name\fR. The reverse +DNS name ensures that the feature's guid is unique across all ZFS +implementations. When unsupported features are encountered on a pool they will +be identified by their guids. Refer to the documentation for the ZFS +implementation that created the pool for information about those features. +.sp +.LP +Each supported feature also has a short name. By convention a feature's short +name is the portion of its guid which follows the ':' (e.g. +\fIcom.example:feature_name\fR would have the short name \fIfeature_name\fR), +however a feature's short name may differ across ZFS implementations if +following the convention would result in name conflicts. +.SS "Feature states" +.LP +Features can be in one of three states: +.sp +.ne 2 +.na +\fB\fBactive\fR\fR +.ad +.RS 12n +This feature's on\-disk format changes are in effect on the pool. Support for +this feature is required to import the pool in read\-write mode. If this +feature is not read-only compatible, support is also required to import the pool +in read\-only mode (see "Read\-only compatibility"). +.RE + +.sp +.ne 2 +.na +\fB\fBenabled\fR\fR +.ad +.RS 12n +An administrator has marked this feature as enabled on the pool, but the +feature's on\-disk format changes have not been made yet. The pool can still be +imported by software that does not support this feature, but changes may be made +to the on\-disk format at any time which will move the feature to the +\fBactive\fR state. Some features may support returning to the \fBenabled\fR +state after becoming \fBactive\fR. See feature\-specific documentation for +details. +.RE + +.sp +.ne 2 +.na +\fBdisabled\fR +.ad +.RS 12n +This feature's on\-disk format changes have not been made and will not be made +unless an administrator moves the feature to the \fBenabled\fR state. Features +cannot be disabled once they have been enabled. +.RE + +.sp +.LP +The state of supported features is exposed through pool properties of the form +\fIfeature@short_name\fR. +.SS "Read\-only compatibility" +.LP +Some features may make on\-disk format changes that do not interfere with other +software's ability to read from the pool. These features are referred to as +"read\-only compatible". If all unsupported features on a pool are read\-only +compatible, the pool can be imported in read\-only mode by setting the +\fBreadonly\fR property during import (see \fBzpool\fR(8) for details on +importing pools). +.SS "Unsupported features" +.LP +For each unsupported feature enabled on an imported pool a pool property +named \fIunsupported@feature_guid\fR will indicate why the import was allowed +despite the unsupported feature. Possible values for this property are: + +.sp +.ne 2 +.na +\fB\fBinactive\fR\fR +.ad +.RS 12n +The feature is in the \fBenabled\fR state and therefore the pool's on\-disk +format is still compatible with software that does not support this feature. +.RE + +.sp +.ne 2 +.na +\fB\fBreadonly\fR\fR +.ad +.RS 12n +The feature is read\-only compatible and the pool has been imported in +read\-only mode. +.RE + +.SS "Feature dependencies" +.LP +Some features depend on other features being enabled in order to function +properly. Enabling a feature will automatically enable any features it +depends on. +.SH FEATURES +.LP +The following features are supported on this system: +.sp +.ne 2 +.na +\fB\fBasync_destroy\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:async_destroy +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +Destroying a file system requires traversing all of its data in order to +return its used space to the pool. Without \fBasync_destroy\fR the file system +is not fully removed until all space has been reclaimed. If the destroy +operation is interrupted by a reboot or power outage the next attempt to open +the pool will need to complete the destroy operation synchronously. + +When \fBasync_destroy\fR is enabled the file system's data will be reclaimed +by a background process, allowing the destroy operation to complete without +traversing the entire file system. The background process is able to resume +interrupted destroys after the pool has been opened, eliminating the need +to finish interrupted destroys as part of the open operation. The amount +of space remaining to be reclaimed by the background process is available +through the \fBfreeing\fR property. + +This feature is only \fBactive\fR while \fBfreeing\fR is non\-zero. +.RE + +.sp +.ne 2 +.na +\fB\fBempty_bpobj\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:empty_bpobj +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +This feature increases the performance of creating and using a large +number of snapshots of a single filesystem or volume, and also reduces +the disk space required. + +When there are many snapshots, each snapshot uses many Block Pointer +Objects (bpobj's) to track blocks associated with that snapshot. +However, in common use cases, most of these bpobj's are empty. This +feature allows us to create each bpobj on-demand, thus eliminating the +empty bpobjs. + +This feature is \fBactive\fR while there are any filesystems, volumes, +or snapshots which were created after enabling this feature. +.RE + +.sp +.ne 2 +.na +\fB\fBfilesystem_limits\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.joyent:filesystem_limits +READ\-ONLY COMPATIBLE yes +DEPENDENCIES extensible_dataset +.TE + +This feature enables filesystem and snapshot limits. These limits can be used +to control how many filesystems and/or snapshots can be created at the point in +the tree on which the limits are set. + +This feature is \fBactive\fR once either of the limit properties has been +set on a dataset. Once activated the feature is never deactivated. +.RE + +.sp +.ne 2 +.na +\fB\fBlz4_compress\fR\fR +.ad +.RS 4n +.TS +l l . +GUID org.illumos:lz4_compress +READ\-ONLY COMPATIBLE no +DEPENDENCIES none +.TE + +\fBlz4\fR is a high-performance real-time compression algorithm that +features significantly faster compression and decompression as well as a +higher compression ratio than the older \fBlzjb\fR compression. +Typically, \fBlz4\fR compression is approximately 50% faster on +compressible data and 200% faster on incompressible data than +\fBlzjb\fR. It is also approximately 80% faster on decompression, while +giving approximately 10% better compression ratio. + +When the \fBlz4_compress\fR feature is set to \fBenabled\fR, the +administrator can turn on \fBlz4\fR compression on any dataset on the +pool using the \fBzfs\fR(8) command. Also, all newly written metadata +will be compressed with \fBlz4\fR algorithm. Since this feature is not +read-only compatible, this operation will render the pool unimportable +on systems without support for the \fBlz4_compress\fR feature. Booting +off of \fBlz4\fR-compressed root pools is supported. + +This feature becomes \fBactive\fR as soon as it is enabled and will +never return to being \fBenabled\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBspacemap_histogram\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:spacemap_histogram +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +This features allows ZFS to maintain more information about how free space +is organized within the pool. If this feature is \fBenabled\fR, ZFS will +set this feature to \fBactive\fR when a new space map object is created or +an existing space map is upgraded to the new format. Once the feature is +\fBactive\fR, it will remain in that state until the pool is destroyed. +.RE + +.sp +.ne 2 +.na +\fB\fBmulti_vdev_crash_dump\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.joyent:multi_vdev_crash_dump +READ\-ONLY COMPATIBLE no +DEPENDENCIES none +.TE + +This feature allows a dump device to be configured with a pool comprised +of multiple vdevs. Those vdevs may be arranged in any mirrored or raidz +configuration. + +When the \fBmulti_vdev_crash_dump\fR feature is set to \fBenabled\fR, +the administrator can use the \fBdumpadm\fR(8) command to configure a +dump device on a pool comprised of multiple vdevs. +.RE + +.sp +.ne 2 +.na +\fB\fBextensible_dataset\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:extensible_dataset +READ\-ONLY COMPATIBLE no +DEPENDENCIES none +.TE + +This feature allows more flexible use of internal ZFS data structures, +and exists for other features to depend on. + +This feature will be \fBactive\fR when the first dependent feature uses it, +and will be returned to the \fBenabled\fR state when all datasets that use +this feature are destroyed. + +.RE + +.sp +.ne 2 +.na +\fB\fBbookmarks\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:bookmarks +READ\-ONLY COMPATIBLE yes +DEPENDENCIES extensible_dataset +.TE + +This feature enables use of the \fBzfs bookmark\fR subcommand. + +This feature is \fBactive\fR while any bookmarks exist in the pool. +All bookmarks in the pool can be listed by running +\fBzfs list -t bookmark -r \fIpoolname\fR\fR. + +.RE + +.sp +.ne 2 +.na +\fB\fBenabled_txg\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:enabled_txg +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +Once this feature is enabled ZFS records the transaction group number +in which new features are enabled. This has no user-visible impact, +but other features may depend on this feature. + +This feature becomes \fBactive\fR as soon as it is enabled and will +never return to being \fBenabled\fR. + +.RE + +.sp +.ne 2 +.na +\fB\fBhole_birth\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:hole_birth +READ\-ONLY COMPATIBLE no +DEPENDENCIES enabled_txg +.TE + +This feature improves performance of incremental sends ("zfs send -i") +and receives for objects with many holes. The most common case of +hole-filled objects is zvols. + +An incremental send stream from snapshot \fBA\fR to snapshot \fBB\fR +contains information about every block that changed between \fBA\fR and +\fBB\fR. Blocks which did not change between those snapshots can be +identified and omitted from the stream using a piece of metadata called +the 'block birth time', but birth times are not recorded for holes (blocks +filled only with zeroes). Since holes created after \fBA\fR cannot be +distinguished from holes created before \fBA\fR, information about every +hole in the entire filesystem or zvol is included in the send stream. + +For workloads where holes are rare this is not a problem. However, when +incrementally replicating filesystems or zvols with many holes (for +example a zvol formatted with another filesystem) a lot of time will +be spent sending and receiving unnecessary information about holes that +already exist on the receiving side. + +Once the \fBhole_birth\fR feature has been enabled the block birth times +of all new holes will be recorded. Incremental sends between snapshots +created after this feature is enabled will use this new metadata to avoid +sending information about holes that already exist on the receiving side. + +This feature becomes \fBactive\fR as soon as it is enabled and will +never return to being \fBenabled\fR. + +.RE + +.sp +.ne 2 +.na +\fB\fBembedded_data\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:embedded_data +READ\-ONLY COMPATIBLE no +DEPENDENCIES none +.TE + +This feature improves the performance and compression ratio of +highly-compressible blocks. Blocks whose contents can compress to 112 bytes +or smaller can take advantage of this feature. + +When this feature is enabled, the contents of highly-compressible blocks are +stored in the block "pointer" itself (a misnomer in this case, as it contains +the compresseed data, rather than a pointer to its location on disk). Thus +the space of the block (one sector, typically 512 bytes or 4KB) is saved, +and no additional i/o is needed to read and write the data block. + +This feature becomes \fBactive\fR as soon as it is enabled and will +never return to being \fBenabled\fR. + +.RE +.sp +.ne 2 +.na +\fB\fBdevice_removal\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:device_removal +READ\-ONLY COMPATIBLE no +DEPENDENCIES none +.TE + +This feature enables the "zpool remove" subcommand to remove top-level +vdevs, evacuating them to reduce the total size of the pool. + +This feature becomes \fBactive\fR when the "zpool remove" command is used +on a top-level vdev, and will never return to being \fBenabled\fR. + +.RE +.sp +.ne 2 +.na +\fB\fBobsolete_counts\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:obsolete_counts +READ\-ONLY COMPATIBLE yes +DEPENDENCIES device_removal +.TE + +This feature is an enhancement of device_removal, which will over time +reduce the memory used to track removed devices. When indirect blocks +are freed or remapped, we note that their part of the indirect mapping +is "obsolete", i.e. no longer needed. See also the \fBzfs remap\fR +subcommand in \fBzfs\fR(8). + +This feature becomes \fBactive\fR when the "zpool remove" command is +used on a top-level vdev, and will never return to being \fBenabled\fR. + +.RE +.sp +.ne 2 +.na +\fB\fBzpool_checkpoint\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:zpool_checkpoint +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +This feature enables the "zpool checkpoint" subcommand that can +checkpoint the state of the pool at the time it was issued and later +rewind back to it or discard it. + +This feature becomes \fBactive\fR when the "zpool checkpoint" command +is used to checkpoint the pool. +The feature will only return back to being \fBenabled\fR when the pool +is rewound or the checkpoint has been discarded. + +.RE +.sp +.ne 2 +.na +\fB\fBspacemap_v2\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:spacemap_v2 +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +This feature enables the use of the new space map encoding which +consists of two words (instead of one) whenever it is advantageous. +The new encoding allows space maps to represent large regions of +space more efficiently on-disk while also increasing their maximum +addressable offset. + +This feature becomes \fBactive\fR once it is \fBenabled\fR, and never +returns back to being \fBenabled\fR. + +.RE +.sp +.ne 2 +.na +\fB\fBlarge_blocks\fR\fR +.ad +.RS 4n +.TS +l l . +GUID org.open-zfs:large_block +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +The \fBlarge_block\fR feature allows the record size on a dataset to be +set larger than 128KB. + +This feature becomes \fBactive\fR once a \fBrecordsize\fR property has been +set larger than 128KB, and will return to being \fBenabled\fR once all +filesystems that have ever had their recordsize larger than 128KB are destroyed. +.RE + +.ne 2 +.na +\fB\fBlarge_dnode\fR\fR +.ad +.RS 4n +.TS +l l . +GUID org.zfsonlinux:large_dnode +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +The \fBlarge_dnode\fR feature allows the size of dnodes in a dataset to be +set larger than 512B. + +This feature becomes \fBactive\fR once a dataset contains an object with a +dnode larger than 512B, which occurs as a result of setting the \fBdnodesize\fR +dataset property to a value other than \fBlegacy\fR. The feature will return to +being \fBenabled\fR once all filesystems that have ever contained a dnode larger +than 512B are destroyed. Large dnodes allow more data to be stored in the +bonus buffer, thus potentially improving performance by avoiding the use of +spill blocks. +.RE + +.sp +.ne 2 +.na +\fB\fBsha512\fR\fR +.ad +.RS 4n +.TS +l l . +GUID org.illumos:sha512 +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +This feature enables the use of the SHA-512/256 truncated hash algorithm +(FIPS 180-4) for checksum and dedup. The native 64-bit arithmetic of +SHA-512 provides an approximate 50% performance boost over SHA-256 on +64-bit hardware and is thus a good minimum-change replacement candidate +for systems where hash performance is important, but these systems +cannot for whatever reason utilize the faster \fBskein\fR and +\fBedonr\fR algorithms. + +When the \fBsha512\fR feature is set to \fBenabled\fR, the administrator +can turn on the \fBsha512\fR checksum on any dataset using the +\fBzfs set checksum=sha512\fR command. This feature becomes +\fBactive\fR once a \fBchecksum\fR property has been set to \fBsha512\fR, +and will return to being \fBenabled\fR once all filesystems that have +ever had their checksum set to \fBsha512\fR are destroyed. + +Booting off of pools utilizing SHA-512/256 is supported. + +.RE + +.sp +.ne 2 +.na +\fB\fBskein\fR\fR +.ad +.RS 4n +.TS +l l . +GUID org.illumos:skein +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +This feature enables the use of the Skein hash algorithm for checksum +and dedup. Skein is a high-performance secure hash algorithm that was a +finalist in the NIST SHA-3 competition. It provides a very high security +margin and high performance on 64-bit hardware (80% faster than +SHA-256). This implementation also utilizes the new salted checksumming +functionality in ZFS, which means that the checksum is pre-seeded with a +secret 256-bit random key (stored on the pool) before being fed the data +block to be checksummed. Thus the produced checksums are unique to a +given pool, preventing hash collision attacks on systems with dedup. + +When the \fBskein\fR feature is set to \fBenabled\fR, the administrator +can turn on the \fBskein\fR checksum on any dataset using the +\fBzfs set checksum=skein\fR command. This feature becomes +\fBactive\fR once a \fBchecksum\fR property has been set to \fBskein\fR, +and will return to being \fBenabled\fR once all filesystems that have +ever had their checksum set to \fBskein\fR are destroyed. + +Booting off of pools using \fBskein\fR is supported. + +.RE + +.sp +.ne 2 +.na +\fB\fBbookmark_v2\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.datto:bookmark_v2 +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +This feature enables the creation and management of larger bookmarks which are +needed for other features in ZFS. + +This feature becomes \fBactive\fR when a v2 bookmark is created and will be +returned to the \fBenabled\fR state when all v2 bookmarks are destroyed. + +.RE + +.sp +.ne 2 +.na +\fB\fBedonr\fR\fR +.ad +.RS 4n +.TS +l l . +GUID org.illumos:edonr +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +This feature enables the use of the Edon-R hash algorithm for checksum, +including for nopwrite (if compression is also enabled, an overwrite of +a block whose checksum matches the data being written will be ignored). +In an abundance of caution, Edon-R can not be used with dedup +(without verification). + +Edon-R is a very high-performance hash algorithm that was part +of the NIST SHA-3 competition. It provides extremely high hash +performance (over 350% faster than SHA-256), but was not selected +because of its unsuitability as a general purpose secure hash algorithm. +This implementation utilizes the new salted checksumming functionality +in ZFS, which means that the checksum is pre-seeded with a secret +256-bit random key (stored on the pool) before being fed the data block +to be checksummed. Thus the produced checksums are unique to a given +pool. + +When the \fBedonr\fR feature is set to \fBenabled\fR, the administrator +can turn on the \fBedonr\fR checksum on any dataset using the +\fBzfs set checksum=edonr\fR command. This feature becomes +\fBactive\fR once a \fBchecksum\fR property has been set to \fBedonr\fR, +and will return to being \fBenabled\fR once all filesystems that have +ever had their checksum set to \fBedonr\fR are destroyed. + +Booting off of pools using \fBedonr\fR is supported. + +.RE + +.sp +.ne 2 +.na +\fB\fBallocation_classes\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.intel:allocation_classes +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +This feature enables support for separate allocation classes. + +This feature becomes \fBactive\fR when a dedicated allocation class vdev +(dedup or special) is created with zpool create or zpool add. With device +removal, it can be returned to the \fBenabled\fR state if all the top-level +vdevs from an allocation class are removed. +.RE + +.sp +.ne 2 +.na +\fB\fBencryption\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.datto:encryption +READ\-ONLY COMPATIBLE no +DEPENDENCIES extensible_dataset +.TE + +This feature enables the creation and management of natively encrypted datasets. + +This feature becomes \fBactive\fR when an encrypted dataset is created +and will be returned to the \fBenabled\fR state when all datasets that +use this feature are destroyed. + +.RE +.sp +.ne 2 +.na +\fB\fBresilver_defer\fR\fR +.ad +.RS 4n +.TS +l l . +GUID com.datto:resilver_defer +READ\-ONLY COMPATIBLE yes +DEPENDENCIES none +.TE + +This feature allows zfs to postpone new resilvers if an existing one is already +in progress. Without this feature, any new resilvers will cause the currently +running one to be immediately restarted from the beginning. + +This feature becomes \fBactive\fR once a resilver has been deferred, and +returns to being \fBenabled\fR when the deferred resilver begins. +.RE + +.sp +.ne 2 +.na +\fBuserobj_accounting\fR +.ad +.RS 4n +.TS +l l . +GUID org.zfsonlinux:userobj_accounting +READ\-ONLY COMPATIBLE yes +DEPENDENCIES extensible_dataset +.TE + +This feature allows administrators to account the object usage information +by user and group. + +This feature becomes \fBactive\fR as soon as it is enabled and will never +return to being \fBenabled\fR. +Each filesystem will be upgraded automatically when remounted, or when new +files are created under that filesystem. +The upgrade can also be started manually on filesystems by running +`zfs set version=current <pool/fs>`. +The upgrade process runs in the background and may take a while to complete +for filesystems containing a large number of files. +.RE + +.sp +.ne 2 +.na +\fBproject_quota\fR +.ad +.RS 4n +.TS +l l . +GUID org.zfsonlinux:project_quota +READ\-ONLY COMPATIBLE yes +DEPENDENCIES extensible_dataset +.TE + +This feature allows administrators to account the space and object usage +information against the project identifier (ID). + +The project ID is a new object-based attribute. +When upgrading an existing filesystem, an object without a project ID +attribute will be assigned a zero project ID. +After this feature is enabled, a newly created object will inherit +its parent directory's project ID if the parent's inherit flag is set (via +\fBzfs project [-s|-C]\fR). +Otherwise, the new object's project ID will be set as zero. +An object's project ID can be changed at any time by the owner (or privileged +user) via \fBzfs project -p $prjid\fR. + +This feature will become \fBactive\fR as soon as it is enabled and will never +return to being \fBdisabled\fR. +Each filesystem will be upgraded automatically when remounted or when a new file +is created under that filesystem. +The upgrade can also be triggered on filesystems via `zfs set version=current +<pool/fs>`. +The upgrade process runs in the background and may take a while to complete +for the filesystems containing a large number of files. +.RE + +.sp +.ne 2 +.na +\fBlog_spacemap\fR +.ad +.RS 4n +.TS +l l . +GUID com.delphix:log_spacemap +READ\-ONLY COMPATIBLE yes +DEPENDENCIES com.delphix:spacemap_v2 +.TE + +This feature improves performance for heavily-fragmented pools, +especially when workloads are heavy in random-writes. +It does so by logging all the metaslab changes on a single spacemap every TXG +instead of scattering multiple writes to all the metaslab spacemaps. + +This feature becomes \fBactive\fR as soon as it is enabled and will never +return to being \fBenabled\fR. +.RE + +.SH "SEE ALSO" +.BR zfs (8), +.BR zpool (8) |