diff options
Diffstat (limited to 'usr/src/man/man5')
98 files changed, 38127 insertions, 0 deletions
diff --git a/usr/src/man/man5/Intro.5 b/usr/src/man/man5/Intro.5 new file mode 100644 index 0000000000..fd31a873ba --- /dev/null +++ b/usr/src/man/man5/Intro.5 @@ -0,0 +1,95 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 5 "17 Nov 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +Intro, intro \- introduction to miscellany +.SH DESCRIPTION +.sp +.LP +Among the topics presented in this section are: +.sp +.ne 2 +.mk +.na +\fBStandards\fR +.ad +.RS 16n +.rt +The POSIX (IEEE) Standards and the X/Open Specifications are described on the +\fBstandards\fR page. +.RE + +.sp +.ne 2 +.mk +.na +\fBEnvironments\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fBMacros\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fBCharacters\fR +.ad +.RS 16n +.rt +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/man5/Makefile b/usr/src/man/man5/Makefile new file mode 100644 index 0000000000..c08328e409 --- /dev/null +++ b/usr/src/man/man5/Makefile @@ -0,0 +1,194 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 5 + +MANFILES = Intro.5 \ + acl.5 \ + ad.5 \ + ascii.5 \ + attributes.5 \ + audit_binfile.5 \ + audit_remote.5 \ + audit_syslog.5 \ + brands.5 \ + cancellation.5 \ + charmap.5 \ + condition.5 \ + crypt_bsdbf.5 \ + crypt_bsdmd5.5 \ + crypt_sha256.5 \ + crypt_sha512.5 \ + crypt_sunmd5.5 \ + crypt_unix.5 \ + device_clean.5 \ + dhcp.5 \ + dhcp_modules.5 \ + environ.5 \ + eqnchar.5 \ + extendedFILE.5 \ + filesystem.5 \ + fnmatch.5 \ + formats.5 \ + fsattr.5 \ + grub.5 \ + gss_auth_rules.5 \ + hal.5 \ + iconv.5 \ + iconv_unicode.5 \ + ieee802.11.5 \ + ipfilter.5 \ + isalist.5 \ + kerberos.5 \ + krb5_auth_rules.5 \ + krb5envvar.5 \ + largefile.5 \ + lf64.5 \ + lfcompile.5 \ + lfcompile64.5 \ + locale.5 \ + man.5 \ + mansun.5 \ + me.5 \ + mech_spnego.5 \ + mm.5 \ + ms.5 \ + mutex.5 \ + nfssec.5 \ + pam_allow.5 \ + pam_authtok_check.5 \ + pam_authtok_get.5 \ + pam_authtok_store.5 \ + pam_deny.5 \ + pam_dhkeys.5 \ + pam_dial_auth.5 \ + pam_krb5.5 \ + pam_krb5_migrate.5 \ + pam_ldap.5 \ + pam_list.5 \ + pam_passwd_auth.5 \ + pam_rhosts_auth.5 \ + pam_roles.5 \ + pam_sample.5 \ + pam_smb_passwd.5 \ + pam_smbfs_login.5 \ + pam_tsol_account.5 \ + pam_unix_account.5 \ + pam_unix_auth.5 \ + pam_unix_cred.5 \ + pam_unix_session.5 \ + pkcs11_kernel.5 \ + pkcs11_softtoken.5 \ + pkcs11_tpm.5 \ + privileges.5 \ + prof.5 \ + rbac.5 \ + regex.5 \ + regexp.5 \ + resource_controls.5 \ + smf.5 \ + smf_bootstrap.5 \ + smf_method.5 \ + smf_restarter.5 \ + smf_security.5 \ + smf_template.5 \ + standards.5 \ + sticky.5 \ + tecla.5 \ + term.5 \ + threads.5 \ + trusted_extensions.5 \ + vgrindefs.5 \ + zones.5 + +MANSOFILES = ANSI.5 \ + C++.5 \ + C.5 \ + CSI.5 \ + ISO.5 \ + MT-Level.5 \ + POSIX.1.5 \ + POSIX.2.5 \ + POSIX.5 \ + RBAC.5 \ + SUS.5 \ + SUSv2.5 \ + SUSv3.5 \ + SVID.5 \ + SVID3.5 \ + XNS.5 \ + XNS4.5 \ + XNS5.5 \ + XPG.5 \ + XPG3.5 \ + XPG4.5 \ + XPG4v2.5 \ + advance.5 \ + architecture.5 \ + availability.5 \ + compile.5 \ + intro.5 \ + pthreads.5 \ + stability.5 \ + standard.5 \ + step.5 \ + teclarc.5 + +MANFILES += $(MANSOFILES) + +intro.5 := SOSRC = man5/Intro.5 + +CSI.5 := SOSRC = man5/attributes.5 +MT-Level.5 := SOSRC = man5/attributes.5 +architecture.5 := SOSRC = man5/attributes.5 +availability.5 := SOSRC = man5/attributes.5 +stability.5 := SOSRC = man5/attributes.5 +standard.5 := SOSRC = man5/attributes.5 + +RBAC.5 := SOSRC = man5/rbac.5 + +advance.5 := SOSRC = man5/regexp.5 +compile.5 := SOSRC = man5/regexp.5 +step.5 := SOSRC = man5/regexp.5 + +ANSI.5 := SOSRC = man5/standards.5 +C++.5 := SOSRC = man5/standards.5 +C.5 := SOSRC = man5/standards.5 +ISO.5 := SOSRC = man5/standards.5 +POSIX.1.5 := SOSRC = man5/standards.5 +POSIX.2.5 := SOSRC = man5/standards.5 +POSIX.5 := SOSRC = man5/standards.5 +SUS.5 := SOSRC = man5/standards.5 +SUSv2.5 := SOSRC = man5/standards.5 +SUSv3.5 := SOSRC = man5/standards.5 +SVID.5 := SOSRC = man5/standards.5 +SVID3.5 := SOSRC = man5/standards.5 +XNS.5 := SOSRC = man5/standards.5 +XNS4.5 := SOSRC = man5/standards.5 +XNS5.5 := SOSRC = man5/standards.5 +XPG.5 := SOSRC = man5/standards.5 +XPG3.5 := SOSRC = man5/standards.5 +XPG4.5 := SOSRC = man5/standards.5 +XPG4v2.5 := SOSRC = man5/standards.5 + +teclarc.5 := SOSRC = man5/tecla.5 + +pthreads.5 := SOSRC = man5/threads.5 + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man5/acl.5 b/usr/src/man/man5/acl.5 new file mode 100644 index 0000000000..24daabdd3d --- /dev/null +++ b/usr/src/man/man5/acl.5 @@ -0,0 +1,932 @@ +'\" 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 acl 5 "29 Sep 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +acl \- Access Control Lists +.SH DESCRIPTION +.sp +.LP +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 the Solaris 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 "\fBPOSIX\fR-draft \fBACL\fRs" +.sp +.LP +POSIX-draft ACLs provide an alternative security mechanism to basic UNIX file +permissions in the Solaris release. 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 +.mk +.na +\fB\fIuser\fR:[\fIuid\fR]:\fIperms\fR\fR +.ad +.RS 21n +.rt +If \fIuid\fR blank, it represents the file owner. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIgroup\fR:[\fIgid\fR]:\fIperms\fR\fR +.ad +.RS 21n +.rt +If \fIgid\fR is blank, it represents the owning group. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIother\fR:\fIperms\fR\fR +.ad +.RS 21n +.rt +Represents the file other class. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImask\fR:\fIperms\fR\fR +.ad +.RS 21n +.rt +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 "\fBNFS\fRv4 \fBACL\fRs" +.sp +.LP +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, Solaris does not support this mechanism. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +NFSv4 ACLs enable adminstrators 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 hypen (\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 +.mk +.na +\fBread_data (\fBr\fR)\fR +.ad +.RS 24n +.rt +Permission to read the data of the file +.RE + +.sp +.ne 2 +.mk +.na +\fBlist_directory (\fBr\fR)\fR +.ad +.RS 24n +.rt +Permission to list the contents of a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBwrite_data (\fBw\fR)\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fBadd_file (\fBw\fR)\fR +.ad +.RS 24n +.rt +Permission to add a new file to a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBappend_data (\fBp\fR)\fR +.ad +.RS 24n +.rt +The ability to modify the file's data, but only starting at EOF. Currently, +this permission is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fBadd_subdirectory (\fBp\fR)\fR +.ad +.RS 24n +.rt +Permission to create a subdirectory to a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBread_xattr (\fBR\fR)\fR +.ad +.RS 24n +.rt +The ability to read the extended attributes of a file or do a lookup in the +extended attributes directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBwrite_xattr (\fBW\fR)\fR +.ad +.RS 24n +.rt +The ability to create extended attributes or write to the extended attributes +directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBexecute (\fBx\fR)\fR +.ad +.RS 24n +.rt +Permission to execute a file. +.RE + +.sp +.ne 2 +.mk +.na +\fBread_attributes (\fBa\fR)\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fBwrite_attributes (\fBA\fR)\fR +.ad +.RS 24n +.rt +Permission to change the times associated with a file or directory to an +arbitrary value. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete (\fBd\fR)\fR +.ad +.RS 24n +.rt +Permission to delete the file. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete_child (\fBD\fR)\fR +.ad +.RS 24n +.rt +Permission to delete a file within a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBread_acl (\fBc\fR)\fR +.ad +.RS 24n +.rt +Permission to read the ACL. +.RE + +.sp +.ne 2 +.mk +.na +\fBwrite_acl (\fBC\fR)\fR +.ad +.RS 24n +.rt +Permission to write the ACL or the ability to execute \fBchmod\fR(1) or +\fBsetfacl\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fBwrite_owner (\fBo\fR)\fR +.ad +.RS 24n +.rt +Permission to change the owner or the ability to execute \fBchown\fR(1) or +\fBchgrp\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fBsynchronize (\fBs\fR)\fR +.ad +.RS 24n +.rt +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: +.sp +.ne 2 +.mk +.na +\fBfile_inherit (\fBf\fR)\fR +.ad +.RS 26n +.rt +Inherit to all newly created files in a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBdir_inherit (\fBd\fR)\fR +.ad +.RS 26n +.rt +Inherit to all newly created directories in a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fBinherit_only (\fBi\fR)\fR +.ad +.RS 26n +.rt +Placed on a directory, but does not apply to the directory itself, only to +newly created created files and directories. This flag requires file_inherit +and or dir_inherit to indicate what to inherit. +.RE + +.sp +.ne 2 +.mk +.na +\fBno_propagate (\fBn\fR)\fR +.ad +.RS 26n +.rt +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 +.mk +.na +\fBsuccessful_access (\fBS)\fR)\fR +.ad +.RS 26n +.rt +Indicates if an alarm or audit record should be initiated upon successful +accesses. Used with audit/alarm ACE types. +.RE + +.sp +.ne 2 +.mk +.na +\fBfailed_access (\fBF\fR)\fR +.ad +.RS 26n +.rt +Indicates if an alarm or audit record should be initiated when access fails. +Used with audit/alarm ACE types. +.RE + +.sp +.ne 2 +.mk +.na +\fBinherited (\fBI\fR)\fR +.ad +.RS 26n +.rt +ACE was inherited. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-\fR\fR +.ad +.RS 26n +.rt +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>[:inheritance flags]:<allow|deny> + group:<groupname>[:inheritance flags]:<allow|deny> +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fBowner@\fR +.ad +.RS 10n +.rt +File owner +.RE + +.sp +.ne 2 +.mk +.na +\fBgroup@\fR +.ad +.RS 10n +.rt +Group owner +.RE + +.sp +.ne 2 +.mk +.na +\fBuser\fR +.ad +.RS 10n +.rt +Permissions for a specific user +.RE + +.sp +.ne 2 +.mk +.na +\fBgroup\fR +.ad +.RS 10n +.rt +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 Solaris \fBAPI\fR" +.sp +.LP +The Solaris command interface supports the manipulation of ACLs. The following +Solaris utilities accommodate both ACL models: +.sp +.ne 2 +.mk +.na +\fB\fBchmod\fR\fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fBcompress\fR\fR +.ad +.RS 12n +.rt +When a file is compressed any ACL associated with the original file is +preserved with the compressed file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcp\fR\fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fBcpio\fR\fR +.ad +.RS 12n +.rt +ACLs are preserved when the \fB-P\fR option is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfind\fR\fR +.ad +.RS 12n +.rt +Find locates files with ACLs when the \fB-acl\fR flag is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBls\fR\fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fBmv\fR\fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fBpack\fR\fR +.ad +.RS 12n +.rt +When a file is packed, any ACL associated with the original file is preserved +with the packed file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrcp\fR\fR +.ad +.RS 12n +.rt +\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 +.mk +.na +\fB\fBtar\fR\fR +.ad +.RS 12n +.rt +ACLs are preserved when the \fB-p\fR option is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBunpack\fR\fR +.ad +.RS 12n +.rt +When a file with an ACL is unpacked, the unpacked file retains the ACL +information. +.RE + +.SS "Application-level \fBAPI\fR" +.sp +.LP +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 \fBACL\fR" +.sp +.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 retrieves 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 then only ACLs that are not +trivial are retrieved. The ACL is returned in the \fBaclp\fR argument. +.SS "Freeing \fBACL\fR structure" +.sp +.in +2 +.nf +void acl_free(acl_t *aclp)s; +.fi +.in -2 + +.sp +.LP +The \fBacl_free()\fR function frees up memory allocated for the argument +\fBaclp;\fR. +.SS "Setting an \fBACL\fR on a file" +.sp +.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) translates an POSIX-draft ACL into a NFSv4 ACL when the +target file systems 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 \fBACL\fR's trivialness" +.sp +.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. The trivialness of a file's ACL depends on the type of ACL it is. +For POSIX-draft ACLs, it implies the ACL has greater than +\fBMIN_ACL_ENTRIES\fR. For NFSv4/ZFS style ACLs, it implies that the ACL has +entries other than \fBowner@\fR, \fBgroup@\fR and \fBeveryone@\fR, inheritance +flags are set, or the ACL is not ordered in a manner that meets POSIX access +control requirements. +.SS "Removing all \fBACL\fRs from a file" +.sp +.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 \fBACL\fRs to/from external representation" +.sp +.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_text()\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 functions converts and external representation into an +internal representation. See \fBDESCRIPTION\fR for details about external +representation. +.SH EXAMPLES +.sp +.LP +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) { +error = acl_set("file2", aclp) +acl_free(aclp); +} +\&... +.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) { +error = acl_set("file4", aclp) +acl_free(aclp); +} +\&... +.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 +istrivial = acl_trivial("file") + +if (istrivial == 0) +printf("file %s has a trivial ACL\n", file); +else +printf("file %s has a NON-trivial ACL\n", file); +\&... +.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 +.sp +.LP +\fBchgrp\fR(1), \fBchmod\fR(1), \fBchown\fR(1), \fBcp\fR(1), \fBcpio\fR(1), +\fBfind\fR(1), \fBls\fR(1), \fBmv\fR(1), \fBtar\fR(1), \fBsetfacl\fR(1), +\fBchmod\fR(2), \fBacl\fR(2),\fBstat\fR(2),\fBacl_get\fR(3SEC), +\fBaclsort\fR(3SEC), \fBacl_fromtext\fR(3SEC), \fBacl_free\fR(3SEC), +\fBacl_strip\fR(3SEC), \fBacl_trivial\fR(3SEC) diff --git a/usr/src/man/man5/ad.5 b/usr/src/man/man5/ad.5 new file mode 100644 index 0000000000..73ceb03a91 --- /dev/null +++ b/usr/src/man/man5/ad.5 @@ -0,0 +1,83 @@ +'\" 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 5 "22 Oct 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +ad \- Active Directory as a naming repository +.SH DESCRIPTION +.sp +.LP +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(4) file. The +Solaris system joins the AD domain by using the \fBkclient\fR(1M) 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(4) 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(1M) 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(1M). +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 24n +.rt +Configuration file for the name-service switch. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.ad\fR\fR +.ad +.RS 24n +.rt +Sample configuration file for the name-service switch configured with ad, dns +and files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/nss_ad.so.1\fR\fR +.ad +.RS 24n +.rt +Name service switch module for AD. +.RE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBsvcs\fR(1), \fBidmap\fR(1M), \fBidmapd\fR(1M), +\fBkclient\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), \fBsvccfg\fR(1M), +\fBnsswitch.conf\fR(4), \fBuser_attr\fR(4), \fBsmf\fR(5) diff --git a/usr/src/man/man5/ascii.5 b/usr/src/man/man5/ascii.5 new file mode 100644 index 0000000000..1e7a7625c2 --- /dev/null +++ b/usr/src/man/man5/ascii.5 @@ -0,0 +1,109 @@ +'\" 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 5 "19 Apr 2002" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fB/usr/pub/ascii\fR \fR +.ad +.RS 19n +.rt +On-line chart of octal and hexadecimal values for the \fBASCII\fR character +set. +.RE + diff --git a/usr/src/man/man5/attributes.5 b/usr/src/man/man5/attributes.5 new file mode 100644 index 0000000000..a9d7cdb551 --- /dev/null +++ b/usr/src/man/man5/attributes.5 @@ -0,0 +1,754 @@ +'\" 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 5 "29 Jul 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +attributes, architecture, availability, CSI, stability, MT-Level, standard \- +attributes of interfaces +.SH DESCRIPTION +.sp +.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 + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitectureSPARC +_ +CSIEnabled +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SS "Architecture" +.sp +.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)" +.sp +.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" +.sp +.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" +.sp +.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 +tab(); +cw(1.1i) cw(1.1i) cw(3.3i) +lw(1.1i) lw(1.1i) lw(3.3i) +. +ReleaseVersionSignificance +_ +Majorx.0T{ +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} +_ +Minorx.yT{ +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} +_ +Microx.y.zT{ +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" +.sp +.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 +tab(); +cw(1.1i) cw(1.1i) cw(3.3i) +lw(1.1i) lw(1.1i) lw(3.3i) +. +StabilityReleaseComments +_ +CommittedMajor (x.0)Incompatibilities are exceptional. +_ +UncommittedMinor (x.y)Incompatibilities are common. +_ +VolatileMicro (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 +.mk +.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 +.mk +.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 subcategorizes: +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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" +.sp +.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" +.sp +.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 +tab(); +cw(1.1i) cw(1.1i) cw(3.3i) +lw(1.1i) lw(1.1i) lw(3.3i) +. +OldNewComments +_ +StandardCommittedT{ +An entry in the attributes table for the Standard attribute type should appear. +T} +StableCommittedName change. +EvolvingUncommittedActual commitments match. +UnstableUncommittedName change. +ExternalVolatileT{ +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" +.sp +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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(5)). 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 +.mk +.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" +.sp +.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 +.sp +.LP +\fBuname\fR(1), \fBpkgadd\fR(1M), \fBIntro\fR(3), \fBstandards\fR(5) diff --git a/usr/src/man/man5/audit_binfile.5 b/usr/src/man/man5/audit_binfile.5 new file mode 100644 index 0000000000..d703e3462b --- /dev/null +++ b/usr/src/man/man5/audit_binfile.5 @@ -0,0 +1,91 @@ +'\" 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 audit_binfile 5 "24 Jun 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +audit_binfile \- generation of Solaris audit logs +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/audit_binfile.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaudit_binfile\fR plugin module for Solaris audit, +\fB/usr/lib/security/audit_binfile.so\fR, writes binary audit data to files as +configured in \fBaudit_control\fR(4); it is the default plugin for the Solaris +audit daemon \fBauditd\fR(1M). Its output is described by \fBaudit.log\fR(4). +.sp +.LP +The \fBaudit_binfile\fR plugin is loaded by \fBauditd\fR if \fBaudit_control\fR +contains one or more lines defining audit directories by means of the +\fBdir:\fR specification or if \fBaudit_control\fR has a \fBplugin:\fR +specification of \fBname=audit_binfile.so\fR. +.SH OBJECT ATTRIBUTES +.sp +.LP +The \fBp_dir\fR and \fBp_minfree\fR attributes are equivalent to the \fBdir:\fR +and \fBminfree:\fR lines described in \fBaudit_control\fR. If both the +\fBdir:\fR line and the \fBp_dir\fR attribute are used, the plugin combines all +directories into a single list with those specified by means of \fBdir:\fR at +the front of the list. If both the \fBminfree\fR and the \fBp_minfree\fR +attributes are given, the \fBp_minfree\fR value is used. +.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 +.sp +.LP +The following directives cause \fBaudit_binfile.so\fR to be loaded, specify the +directories for writing audit logs, and specify the percentage of required free +space per directory. +.sp +.in +2 +.nf +flags: lo,ad,-fm +naflags: lo,ad +plugin: name=audit_binfile.so;\e +p_minfree=20;\e +p_dir=/var/audit/jedgar/eggplant,\e +/var/audit/jedgar.aux/eggplant,\e +/var/audit/global/eggplant +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +MT LevelMT-Safe +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBauditd\fR(1M), \fBaudit_control\fR(4), \fBsyslog.conf\fR(4), +\fBattributes\fR(5) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man5/audit_remote.5 b/usr/src/man/man5/audit_remote.5 new file mode 100644 index 0000000000..50213aa836 --- /dev/null +++ b/usr/src/man/man5/audit_remote.5 @@ -0,0 +1,352 @@ +'\" 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 audit_remote 5 "8 Sep 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +audit_remote \- send Solaris audit logs to a remote server +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/audit_remote.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaudit_remote\fR plugin module for Solaris audit, +\fB/usr/lib/security/audit_remote.so\fR, sends binary audit records +(\fBaudit.log\fR(4)) to audit servers specified in \fBaudit_control\fR(4). +.sp +.LP +The \fBaudit_remote\fR plugin is loaded by \fBauditd\fR(1M) if +\fBaudit_control\fR contains a \fBplugin:\fR specification of +\fBname=audit_remote.so\fR. +.SS "Object Attributes" +.sp +.LP +The following attributes specify the configuration of \fBaudit_remote\fR +plugin: +.sp +.ne 2 +.mk +.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(4)). If not specified, the local host's default mechanism is used. +The recommended mechanism is \fBkerberos_v5\fR. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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(1M). +.RE + +.SS "GSS SESSION" +.sp +.LP +The \fBaudit_remote plugin\fR is a TCP client that authenticates configured +audit servers using the GSS-API (\fBlibgss\fR(3LIB)). Binary Solaris 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(4)). +.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(4)) 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(1M) 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" +.sp +.LP +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(4)); 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 +.LP +\fBExample 1 \fRLoading \fBaudit_remote.so\fR and Specifying the Remote Audit +Servers +.sp +.LP +The following directives cause \fBaudit_remote.so\fR to be loaded and specify +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 +plugin: name=audit_remote.so;\e +p_timeout=90;p_retries=2;\e +p_hosts=eggplant.eng.sun.com::kerberos_v5,\e +purple.ebay.sun.com:4592:kerberos_v5 +.fi +.in -2 + +.LP +\fBExample 2 \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 +plugin: name=audit_remote.so;\e +p_timeout=10;p_retries=2;\e +p_hosts=jedger.eng.sun.com,\e +jbadams.ebay.sun.com:4592 +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelMT-Safe +_ +Interface StabilitySee 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(4) for +the audit record format and content stability. +.SH SEE ALSO +.sp +.LP +\fBauditd\fR(1M), \fBauditconfig\fR(1M), \fBaudit_warn\fR(1M), +\fBgetipnodebyname\fR(3SOCKET), \fBgetservbyname\fR(3XNET), +\fBgss_accept_sec_context\fR(3GSS), \fBgss_get_mic\fR(3GSS), +\fBgss_init_sec_context\fR(3GSS), \fBgss_wrap\fR(3GSS), \fBgss_unwrap\fR(3GSS), +\fBlibgss\fR(3LIB), \fBlibsocket\fR(3LIB), \fBaudit_control\fR(4), +\fBaudit.log\fR(4), \fBkrb5.conf\fR(4), \fBmech\fR(4), \fBattributes\fR(5), +\fBkerberos\fR(5), \fBtcp\fR(7P) +.SH NOTES +.sp +.LP +\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/man5/audit_syslog.5 b/usr/src/man/man5/audit_syslog.5 new file mode 100644 index 0000000000..0b89b5c504 --- /dev/null +++ b/usr/src/man/man5/audit_syslog.5 @@ -0,0 +1,299 @@ +'\" 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 audit_syslog 5 "25 Sep 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +audit_syslog \- realtime conversion of Solaris audit data to syslog messages +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/audit_syslog.so\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaudit_syslog\fR plugin module for Solaris audit, +\fB/usr/lib/security/audit_syslog.so\fR, provides realtime conversion of +Solaris audit data to syslog-formatted (text) data and sends it to a syslog +daemon as configured in \fBsyslog.conf\fR(4). The plugin's path is specified in +the audit configuration file, \fBaudit_control\fR(4). +.sp +.LP +Messages to \fBsyslog\fR are written if selected via the \fBplugin\fR option in +\fBaudit_control\fR. Syslog messages are generated with the facility code of +\fBLOG_AUDIT\fR (\fBaudit\fR in \fBsyslog.conf\fR(4)) 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(4)). 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 +.mk +.na +\fB\fBok\fR or \fBfailed\fR\fR +.ad +.RS 21n +.rt +Comes from the return or exit token. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsession \fI<#>\fR\fR\fR +.ad +.RS 21n +.rt +\fI<#>\fR is the session ID from the subject token. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBby \fI<name>\fR\fR\fR +.ad +.RS 21n +.rt +\fI<name>\fR is the audit ID from the subject token. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBas \fI<name>\fR:\fI<group>\fR\fR\fR +.ad +.RS 21n +.rt +\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 +.mk +.na +\fB\fBin\fR \fI<zone name>\fR\fR +.ad +.RS 21n +.rt +The zone name. This field is generated only if the \fBzonename\fR audit policy +is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfrom \fI<terminal>\fR\fR\fR +.ad +.RS 21n +.rt +\fI<terminal>\fR is the text machine address from the subject token. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBobj \fI<path>\fR\fR\fR +.ad +.RS 21n +.rt +\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 +.mk +.na +\fB\fBproc_uid \fI<owner>\fR\fR\fR +.ad +.RS 21n +.rt +\fI<owner>\fR is the effective user ID of the process owner. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproc_auid \fI<owner>\fR\fR\fR +.ad +.RS 21n +.rt +\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 +.sp +.LP +The \fBp_flag\fR attribute, specified by means of the \fBplugin\fR directive +(see \fBaudit_control\fR(4)), is used to further filter audit data being sent +to the \fBsyslog\fR daemon beyond the classes specified through the \fBflags\fR +and \fBnaflags\fR lines of \fBaudit_control\fR and through the user-specific +lines of \fBaudit_user\fR(4). The parameter is a comma-separated list; each +item represents an audit class (see \fBaudit_class\fR(4)) and is specified +using the same syntax used in \fBaudit_control\fR for the \fBflags\fR and +\fBnaflags\fR lines. The default (no \fBp_flags\fR listed) is that no audit +records are generated. +.SH EXAMPLES +.LP +\fBExample 1 \fROne Use of the \fBplugin\fR Line +.sp +.LP +In the specification shown below, the \fBplugin\fR line (in conjunction with +\fBflags\fR and \fBnaflags\fR) is used to allow class records for \fBlo\fR but +allows class records for \fBam\fR for failures only. Omission of the \fBfm\fR +class records results in no \fBfm\fR class records being output. The \fBpc\fR +parameter has no effect because you cannot add classes to those defined by +means of \fBflags\fR and \fBnaflags\fR and by \fBaudit_user\fR(4). You can only +remove them. + +.sp +.in +2 +.nf +flags: lo,am,fm +naflags: lo +plugin: name=audit_syslog.so; p_flags=lo,-am +.fi +.in -2 +.sp + +.LP +\fBExample 2 \fRUse of \fBall\fR +.sp +.LP +In the specification shown below, with one exception, \fBall\fR allows all +flags defined by means of \fBflags\fR and \fBnaflags\fR (and +\fBaudit_user\fR(4)). The exception the \fBam\fR metaclass, which is equivalent +to \fBss,as,ua\fR, which is modified to output all \fBua\fR events but only +failure events for \fBss\fR and \fBas\fR. + +.sp +.in +2 +.nf +flags: lo,am +naflags: lo +plugin: name=audit_syslog.so; p_flags=all,^+ss,^+as +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +MT LevelMT-Safe +_ +Interface StabilitySee below. +.TE + +.sp +.LP +The message format and message content are Uncommitted. The configuration +parameters are Committed. +.SH SEE ALSO +.sp +.LP +\fBauditd\fR(1M), \fBaudit_class\fR(4), \fBaudit_control\fR(4), +\fBsyslog.conf\fR(4), \fBattributes\fR(5) +.sp +.LP +\fISystem Administration Guide: Security Services\fR +.SH NOTES +.sp +.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 Solaris 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 parameters specified for the \fBplugin\fR line result 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/man5/brands.5 b/usr/src/man/man5/brands.5 new file mode 100644 index 0000000000..f3686eb643 --- /dev/null +++ b/usr/src/man/man5/brands.5 @@ -0,0 +1,88 @@ +'\" 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 5 "29 Jul 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +brands \- alternate operating environments for non-global zones +.SH DESCRIPTION +.sp +.LP +The branded zone (BrandZ) framework extends the Solaris Zones infrastructure +described in \fBzones\fR(5) 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(1M)) 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(1M)) is used to report a zone's brand type +and administer the zone. +.RE +.SS "Device Support" +.sp +.LP +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 +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBmdb\fR(1), \fBzlogin\fR(1), \fBzonename\fR(1), \fBdtrace\fR(1M), +\fBin.rlogind\fR(1M), \fBsshd\fR(1M), \fBzoneadm\fR(1M), \fBzonecfg\fR(1M), +\fBkill\fR(2), \fBpriocntl\fR(2), \fBgetzoneid\fR(3C), \fBucred_get\fR(3C), +\fBgetzoneid\fR(3C), \fBproc\fR(4), \fBattributes\fR(5), \fBlx\fR(5), +\fBnative\fR(5), \fBprivileges\fR(5), \fBzones\fR(5), \fBlx_systrace\fR(7D), +\fBcrgetzoneid\fR(9F) diff --git a/usr/src/man/man5/cancellation.5 b/usr/src/man/man5/cancellation.5 new file mode 100644 index 0000000000..09755d6d1a --- /dev/null +++ b/usr/src/man/man5/cancellation.5 @@ -0,0 +1,409 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text +.\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" 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] +.TH cancellation 5 "4 Oct 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +cancellation \- overview of concepts related to POSIX thread cancellation +.SH DESCRIPTION +.sp + +.sp +.TS +tab() box; +cw(2.18i) |cw(3.32i) +lw(2.18i) |lw(3.32i) +. +FUNCTIONACTION +_ +\fBpthread_cancel()\fRCancels thread execution. +\fBpthread_setcancelstate()\fRSets the cancellation \fIstate\fR of a thread. +\fBpthread_setcanceltype()\fRSets the cancellation \fItype\fR of a thread. +\fBpthread_testcancel()\fRT{ +Creates a cancellation point in the calling thread. +T} +\fBpthread_cleanup_push()\fRPushes a cleanup handler routine. +\fBpthread_cleanup_pop()\fRPops a cleanup handler routine. +.TE + +.SS "Cancellation" +.sp +.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" +.sp +.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" +.sp +.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" +.sp +.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" +.sp +.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" +.sp +.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 +tab() box; +cw(1.83i) |cw(1.83i) |cw(1.83i) +lw(1.83i) |lw(1.83i) |lw(1.83i) +. +Cancellation Type/State Table +TypeState +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} +AsynchronousT{ +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 executedimmediately. +T} +.TE + +.SS "Cancel-Safe" +.sp +.LP +With the arrival of POSIX cancellation, the Cancel-Safe level has been added to +the list of MT-Safety levels. See \fBattributes\fR(5). 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" +.sp +.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 +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBsigwait\fR(2), \fBwrite\fR(2), \fBIntro\fR(3), +\fBcondition\fR(5), \fBpthread_cleanup_pop\fR(3C), +\fBpthread_cleanup_push\fR(3C), \fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C), +\fBpthread_testcancel\fR(3C), \fBsetjmp\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man5/charmap.5 b/usr/src/man/man5/charmap.5 new file mode 100644 index 0000000000..e2c2ff5ca9 --- /dev/null +++ b/usr/src/man/man5/charmap.5 @@ -0,0 +1,338 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH charmap 5 "1 Dec 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +tab() box; +lw(.92i) lw(.92i) lw(.92i) lw(.92i) lw(.92i) lw(.92i) +lw(.92i) lw(.92i) lw(.92i) lw(.92i) lw(.92i) lw(.92i) +. +<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 +.mk +.na +\fB<\fIcode_set_name\fR>\fR +.ad +.RS 19n +.rt +The name of the coded character set for which the character set description +file is defined. +.RE + +.sp +.ne 2 +.mk +.na +\fB<\fImb_cur_max\fR>\fR +.ad +.RS 19n +.rt +The maximum number of bytes in a multi-byte character. This defaults to +\fB1\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB<\fImb_cur_min\fR>\fR +.ad +.RS 19n +.rt +An unsigned positive integer value that defines the minimum number of bytes in +a character for the encoded character set. +.RE + +.sp +.ne 2 +.mk +.na +\fB<\fIescape_char\fR>\fR +.ad +.RS 19n +.rt +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 +.mk +.na +\fB<\fIcomment_char\fR>\fR +.ad +.RS 19n +.rt +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 +.mk +.na +\fB\fBWIDTH\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBWIDTH_DEFAULT\fR\fR +.ad +.RS 17n +.rt +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 +\fBlocale\fR(1), \fBlocaledef\fR(1), \fBnl_langinfo\fR(3C), +\fBextensions\fR(5), \fBlocale\fR(5) diff --git a/usr/src/man/man5/condition.5 b/usr/src/man/man5/condition.5 new file mode 100644 index 0000000000..b232e4c473 --- /dev/null +++ b/usr/src/man/man5/condition.5 @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of +.\" Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH condition 5 "20 Jul 1998" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +condition \- concepts related to condition variables +.SH DESCRIPTION +.sp +.LP +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" +.sp +.LP +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" +.sp +.LP +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" +.sp +.LP +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" +.sp +.LP +The condition destroy functions destroy any state, but not the space, +associated with the condition variable. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2), +\fBcond_broadcast\fR(3C), \fBcond_destroy\fR(3C), \fBcond_init\fR(3C), +\fBcond_signal\fR(3C), \fBcond_timedwait\fR(3C), \fBcond_wait\fR(3C), +\fBpthread_cond_broadcast\fR(3C), \fBpthread_cond_destroy\fR(3C), +\fBpthread_cond_init\fR(3C), \fBpthread_cond_signal\fR(3C), +\fBpthread_cond_timedwait\fR(3C), \fBpthread_cond_wait\fR(3C), +\fBpthread_condattr_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5), +\fBmutex\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +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 mapplings 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/man5/crypt_bsdbf.5 b/usr/src/man/man5/crypt_bsdbf.5 new file mode 100644 index 0000000000..a19e020ca6 --- /dev/null +++ b/usr/src/man/man5/crypt_bsdbf.5 @@ -0,0 +1,46 @@ +'\" 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 5 "13 Sep 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) and \fBpolicy.conf\fR(4) is \fB2a\fR. +.sp +.LP +The maximum password length for \fBcrypt_bsdbf\fR is 72 characters. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), +\fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man5/crypt_bsdmd5.5 b/usr/src/man/man5/crypt_bsdmd5.5 new file mode 100644 index 0000000000..98094f8da0 --- /dev/null +++ b/usr/src/man/man5/crypt_bsdmd5.5 @@ -0,0 +1,47 @@ +'\" 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 5 "6 Aug 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) and \fBpolicy.conf\fR(4) 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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), +\fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man5/crypt_sha256.5 b/usr/src/man/man5/crypt_sha256.5 new file mode 100644 index 0000000000..38335cbf1c --- /dev/null +++ b/usr/src/man/man5/crypt_sha256.5 @@ -0,0 +1,85 @@ +'\" 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 5 "8 May 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) and \fBpolicy.conf\fR(4) 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(4): +.sp +.ne 2 +.mk +.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(4) is greater than +that in the old salt, the value from \fBcrypt.conf\fR(4) 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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), +\fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man5/crypt_sha512.5 b/usr/src/man/man5/crypt_sha512.5 new file mode 100644 index 0000000000..576bc5f4d6 --- /dev/null +++ b/usr/src/man/man5/crypt_sha512.5 @@ -0,0 +1,85 @@ +'\" 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 5 "8 May 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) and \fBpolicy.conf\fR(4) 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(4): +.sp +.ne 2 +.mk +.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(4) is greater than +that in the old salt, the value from \fBcrypt.conf\fR(4) 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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), +\fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man5/crypt_sunmd5.5 b/usr/src/man/man5/crypt_sunmd5.5 new file mode 100644 index 0000000000..38a24a30b6 --- /dev/null +++ b/usr/src/man/man5/crypt_sunmd5.5 @@ -0,0 +1,83 @@ +'\" 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 5 "23 Dec 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) and \fBpolicy.conf\fR(4) 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(4): +.sp +.ne 2 +.mk +.na +\fB\fBrounds=\fR\fI<positive_number>\fR\fR +.ad +.RS 28n +.rt +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(4) is greater than +that in the old salt, the value from \fBcrypt.conf\fR(4) 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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), +\fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man5/crypt_unix.5 b/usr/src/man/man5/crypt_unix.5 new file mode 100644 index 0000000000..8e2fae5df0 --- /dev/null +++ b/usr/src/man/man5/crypt_unix.5 @@ -0,0 +1,65 @@ +'\" 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 5 "6 Aug 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5), \fBcrypt_bsdmd5\fR(5), or +\fBcrypt_bsdbf\fR(5) algorithm should be used instead. +.sp +.LP +The algorithm identifier for \fBpolicy.conf\fR(4) is \fB__unix__\fR. There is +no entry in \fBcrypt.conf\fR(4) 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(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), +\fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), +\fBattributes\fR(5), \fBcrypt_bsdbf\fR(5), \fBcrypt_bsdmd5\fR(5), +\fBcrypt_sunmd5\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man5/device_clean.5 b/usr/src/man/man5/device_clean.5 new file mode 100644 index 0000000000..dbd9fb283a --- /dev/null +++ b/usr/src/man/man5/device_clean.5 @@ -0,0 +1,348 @@ +'\" 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 5 "14 Jun 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBaudio_clean\fR\fR +.ad +.RS 15n +.rt +audio devices +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfd_clean\fR\fR +.ad +.RS 15n +.rt +floppy devices +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBst_clean\fR\fR +.ad +.RS 15n +.rt +tape devices +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsr_clean\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBdisk_clean\fR\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\fBaudio_clean_wrapper\fR\fR +.ad +.RS 23n +.rt +wrapper to make audio_clean work with CDE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBwdwwrapper\fR\fR +.ad +.RS 23n +.rt +wrapper to make other cleaning programs work with CDE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBwdwmsg\fR\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\fIdevice-name\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fB-i\fR\fR +.ad +.RS 15n +.rt +Invoke boot-time initialization. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-f\fR\fR +.ad +.RS 15n +.rt +Force cleanup by the administrator. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-s\fR\fR +.ad +.RS 15n +.rt +Invoke standard cleanup by the user. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-I\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fB-m\fR \fImode\fR\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fB-u\fR \fIuser-name\fR\fR +.ad +.RS 16n +.rt +Specify the name of user who executes the device clean program. The default +user is the caller. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-z\fR \fIzone-name\fR\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fB-p\fR \fIzone-path\fR\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fB0\fR\fR +.ad +.sp .6 +.RS 4n +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.sp .6 +.RS 4n +An error. Caller can place device in error state. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB4\fR\fR +.ad +.sp .6 +.RS 4n +Mounting of device succeeded. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/security/lib/*\fR\fR +.ad +.RS 23n +.rt +device clean programs +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +.TE + +.sp +.LP +The Invocation is Uncommitted. The Output is Not-an-interface. +.SH SEE ALSO +.sp +.LP +\fBallocate\fR(1), \fBdeallocate\fR(1), \fBlist_devices\fR(1), +\fBattributes\fR(5) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man5/dhcp.5 b/usr/src/man/man5/dhcp.5 new file mode 100644 index 0000000000..bf88f65296 --- /dev/null +++ b/usr/src/man/man5/dhcp.5 @@ -0,0 +1,127 @@ +'\" te +.\" 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 5 "5 Jan 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +dhcp \- Dynamic Host Configuration Protocol +.SH DESCRIPTION +.sp +.LP +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. +.sp +.LP +This manual page provides a brief summary of the Solaris \fBDHCP\fR +implementation. +.SS "Solaris DHCP Client" +.sp +.LP +The Solaris DHCP client is implemented as background daemon, +\fBdhcpagent\fR(1M). +.sp +.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. +.sp +.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. +.sp +.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(1M) utility. Check the status of the daemon +using the \fBnetstat\fR(1M) and \fBifconfig\fR(1M) commands. +.SS "Solaris DHCP Server" +.sp +.LP +The Solaris \fBDHCP\fR server is implemented as a background daemon, +\fBin.dhcpd\fR(1M). This daemon can deliver network configuration information +to either \fBBOOTP\fR or \fBDHCP\fR clients. The Solaris \fBDHCP\fR service can +be managed using the \fBdhcpmgr\fR(1M) \fBGUI\fR or the command line utilities +\fBdhcpconfig\fR(1M), \fBdhtadm\fR(1M), and \fBpntadm\fR(1M). +.SS "DHCP Configuration Tables" +.sp +.LP +The Solaris \fBDHCP\fR server stores client configuration information in the +following two types of tables: +.sp +.ne 2 +.mk +.na +\fB\fBdhcptab\fR tables\fR +.ad +.RS 23n +.rt +Contain macros and options (also known as symbols), used to construct a package +of configuration information to send to each \fBDHCP\fR client. There exists +only one \fBdhcptab\fR for the \fBDHCP\fR service. The \fBdhcptab\fR(4) can be +viewed and modified using the \fBdhtadm\fR(1M) command or \fBdhcpmgr\fR(1M) +graphical utility. See \fBdhcptab\fR(4) for more information about the syntax +of \fBdhcptab\fR records. See \fBdhcp_inittab\fR(4) for more information about +the \fBDHCP\fR options and symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDHCP\fR network tables\fR +.ad +.RS 23n +.rt +\fBDHCP\fR network tables, which contain mappings of client \fBID\fRs to +\fBIP\fR addresses and parameters associated with those addresses. Network +tables are named with the \fBIP\fR address of the network, and can be created, +viewed, and modified using the \fBpntadm\fR command or \fBdhcpmgr\fR graphical +utility. See \fBdhcp_network\fR(4) for more information about network tables. +.RE + +.SH SEE ALSO +.sp +.LP +\fBdhcpinfo\fR(1), \fBdhcpagent\fR(1M), \fBdhcpconfig\fR(1M), +\fBdhcpmgr\fR(1M), \fBdhtadm\fR(1M), \fBifconfig\fR(1M), \fBin.dhcpd\fR(1M), +\fBin.ndpd\fR(1M), \fBnetstat\fR(1M), \fBpntadm\fR(1M), \fBsyslog\fR(3C), +\fBdhcp_network\fR(4), \fBdhcptab\fR(4), \fBdhcpsvc.conf\fR(4), +\fBdhcp_inittab\fR(4), \fBndpd.conf\fR(4), \fBdhcp_modules\fR(5) +.sp +.LP +\fISolaris DHCP Service Developer\&'s Guide\fR +.sp +.LP +Alexander, S., and R. Droms. \fIRFC 2132, DHCP Options and BOOTP Vendor +Extensions\fR. Silicon Graphics, Inc. Bucknell University. March 1997. +.sp +.LP +Droms, R. \fIRFC 1534, Interoperation Between DHCP and BOOTP\fR. Bucknell +University. October 1993. +.sp +.LP +Droms, R. \fIRFC 2131, Dynamic Host Configuration Protocol\fR. Bucknell +University. March 1997. +.sp +.LP +Wimer, W. \fIRFC 1542, Clarifications and Extensions for the Bootstrap +Protocol\fR. Carnegie Mellon University. October 1993. +.sp +.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. +.sp +.LP +Droms, R. \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6 +(DHCPv6)\fR. Cisco Systems. July 2003. diff --git a/usr/src/man/man5/dhcp_modules.5 b/usr/src/man/man5/dhcp_modules.5 new file mode 100644 index 0000000000..7f5c001d26 --- /dev/null +++ b/usr/src/man/man5/dhcp_modules.5 @@ -0,0 +1,89 @@ +'\" 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 dhcp_modules 5 "24 Jan 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +dhcp_modules \- data storage modules for the DHCP service +.SH DESCRIPTION +.sp +.LP +This man page describes the characteristics of data storage modules (public +modules) for use by the Solaris Dynamic Host Configuration Protocol +(\fBDHCP\fR) service. +.sp +.LP +Public modules are the part of the \fBDHCP\fR service architecture that +encapsulate the details of storing \fBDHCP\fR service data in a data storage +service. Examples of data storage services are \fBNIS+\fR, Oracle, and +\fBufs\fR file systems. +.sp +.LP +Public modules are dynamic objects which can be shipped separately from the +Solaris \fBDHCP\fR service. Once installed, a public module is visible to the +\fBDHCP\fR service, and can be selected for use by the service through the +\fBDHCP\fR service management interfaces (\fBdhcpmgr\fR(1M), +\fBdhcpconfig\fR(1M), \fBdhtadm\fR(1M), and \fBpntadm\fR(1M)). +.sp +.LP +Public modules may be provided by Sun Microsystems, Inc or by third parties. +.sp +.LP +The Solaris \fBDHCP\fR service management architecture provides a mechanism for +plugging in public module-specific administration functionality into the +\fBdhcpmgr\fR(1M) and \fBdhcpconfig\fR(1M) utilities. This functionality is in +the form of a Java Bean, which is provided by the public module vendor. This +Java Bean collects public module-specific configuration from the user (you) and +provides it to the Solaris \fBDHCP\fR service. +.sp +.LP +The Solaris \fBDHCP\fR service bundles three modules with the service, which +are described below. There are three \fBdhcpsvc.conf\fR(4) \fBDHCP\fR service +configuration parameters pertaining to public modules: \fBRESOURCE\fR, +\fBPATH\fR, and \fBRESOURCE_CONFIG\fR. See \fBdhcpsvc.conf\fR(4) for more +information about these parameters. +.SS "SUNWfiles" +.sp +.LP +This module stores its data in \fBASCII\fR files. Although the format is +\fBASCII\fR, hand-editing is discouraged. It is useful for \fBDHCP\fR service +environments that support several hundred to a couple thousand of clients and +lease times are a few hours or more. +.sp +.LP +This module's data may be shared between \fBDHCP\fR servers through the use of +\fBNFS\fR. +.SS "SUNWbinfiles" +.sp +.LP +This module stores its data in binary files. It is useful for \fBDHCP\fR +service environments with many networks and many thousands of clients. This +module provides an order of magnitude increase in performance and capacity over +SUNWfiles. +.sp +.LP +This module's data cannot be shared between \fBDHCP\fR servers. +.SS "SUNWnisplus" +.sp +.LP +This module stores its data within a \fBNIS+\fR domain. It is useful in +environments where \fBNIS+\fR is already deployed and facilitates sharing among +multiple \fBDHCP\fR servers. This module suports several hundred to a few +thousand clients with lease times of several hours or more. +.sp +.LP +The \fBNIS+\fR service should be hosted on a machine with ample \fBCPU\fR +power, memory, and disk space, as the load on \fBNIS+\fR is significant when it +is used to store \fBDHCP\fR data. Periodic checkpointing of the \fBNIS+\fR +service is necessary in order to roll the transaction logs and keep the +\fBNIS+\fR service operating at its highest efficiency. See \fBnisping\fR(1M) +and \fBcrontab\fR(1) for more information. +.SH SEE ALSO +.sp +.LP +\fBcrontab\fR(1), \fBdhcpconfig\fR(1M), \fBdhcpmgr\fR(1M), \fBdhtadm\fR(1M), +\fBnisping\fR(1M), \fBpntadm\fR(1M), \fBdhcpsvc.conf\fR(4), \fBdhcp\fR(5) +.sp +.LP +\fISolaris DHCP Service Developer\&'s Guide\fR diff --git a/usr/src/man/man5/environ.5 b/usr/src/man/man5/environ.5 new file mode 100644 index 0000000000..e3d9187834 --- /dev/null +++ b/usr/src/man/man5/environ.5 @@ -0,0 +1,558 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 environ 5 "19 Nov 2002" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +environ \- user environment +.SH DESCRIPTION +.sp +.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. +.sp +.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(4). +.sp +.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 +.mk +.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(4). +.RE + +.sp +.ne 2 +.mk +.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) function +checks the \fBLANG\fR environment variable when it is 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. +.sp +The following environment variables correspond to each category of +\fBsetlocale\fR(3C): +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB%N\fR +.ad +.sp .6 +.RS 4n +The value of the \fIname\fR parameter passed to \fBcatopen()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB%L\fR +.ad +.sp .6 +.RS 4n +The value of \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB%l\fR +.ad +.sp .6 +.RS 4n +The language element from \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB%t\fR +.ad +.sp .6 +.RS 4n +The territory element from \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB%c\fR +.ad +.sp .6 +.RS 4n +The codeset element from \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.sp +.LP +\fBcat\fR(1), \fBdate\fR(1), \fBed\fR(1), \fBfmtmsg\fR(1), \fBlocaledef\fR(1), +\fBlogin\fR(1), \fBls\fR(1), \fBmkmsgs\fR(1), \fBnice\fR(1), \fBnohup\fR(1), +\fBsh\fR(1), \fBsort\fR(1), \fBtime\fR(1), \fBvi\fR(1), \fBexec\fR(2), +\fBaddseverity\fR(3C), \fBcatopen\fR(3C), \fBctime\fR(3C), \fBctype\fR(3C), +\fBfmtmsg\fR(3C), \fBgetdate\fR(3C), \fBgetnetpath\fR(3NSL), \fBgettext\fR(3C), +\fBgettxt\fR(3C), \fBlocaleconv\fR(3C), \fBmblen\fR(3C), \fBmktime\fR(3C), +\fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C), +\fBstrtod\fR(3C), \fBstrxfrm\fR(3C), \fBTIMEZONE\fR(4), \fBnetconfig\fR(4), +\fBpasswd\fR(4), \fBprofile\fR(4) diff --git a/usr/src/man/man5/eqnchar.5 b/usr/src/man/man5/eqnchar.5 new file mode 100644 index 0000000000..702b2fe8f2 --- /dev/null +++ b/usr/src/man/man5/eqnchar.5 @@ -0,0 +1,39 @@ +'\" 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 5 "12 Jul 2002" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +\fBeqn\fR(1), \fBnroff\fR(1), \fBtroff\fR(1), \fBattributes\fR(5) diff --git a/usr/src/man/man5/extendedFILE.5 b/usr/src/man/man5/extendedFILE.5 new file mode 100644 index 0000000000..db526d3bc0 --- /dev/null +++ b/usr/src/man/man5/extendedFILE.5 @@ -0,0 +1,195 @@ +'\" 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 5 "18 Apr 2006" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fB_STDIO_BADFD\fR\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\fB_STDIO_BADFD_SIGNAL\fR\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\fB/usr/lib/extendedFILE.so.1\fR\fR +.ad +.RS 30n +.rt +enabling library +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlimit\fR(1), \fBopen\fR(2), \fBenable_extended_FILE_stdio\fR(3C), +\fBfdopen\fR(3C), \fBfopen\fR(3C), \fBpopen\fR(3C), \fBsignal.h\fR(3HEAD), +\fBstdio\fR(3C), \fBattributes\fR(5) +.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/man5/filesystem.5 b/usr/src/man/man5/filesystem.5 new file mode 100644 index 0000000000..9191878056 --- /dev/null +++ b/usr/src/man/man5/filesystem.5 @@ -0,0 +1,4024 @@ +'\" te +.\" Copyright (c) 2008, 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 filesystem 5 "24 Aug 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +filesystem \- File system organization +.SH SYNOPSIS +.LP +.nf +/ +.fi + +.LP +.nf +/usr +.fi + +.SH DESCRIPTION +.sp +.LP +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. +.sp +.LP +In the following file or directory descriptions, GNOME stands for GNU Network +Object Model Environment. The GNOME Desktop is shipped with the Solaris +operating system. +.SS "Root File System" +.sp +.LP +The root file system contains files that are unique to each machine. It +contains the following directories: +.sp +.ne 2 +.mk +.na +\fB\fB/\fR\fR +.ad +.sp .6 +.RS 4n +Root of the overall file system name space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev\fR\fR +.ad +.sp .6 +.RS 4n +Primary location for special files. Typically, device files are built to match +the kernel and hardware configuration of the machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/cfg\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic links to physical \fBap_ids.\fR +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/dev/cua\fR\fR +.ad +.sp .6 +.RS 4n +Device files for \fBuucp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/dsk\fR\fR +.ad +.sp .6 +.RS 4n +Block disk devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/dtrace\fR\fR +.ad +.sp .6 +.RS 4n +Pseudo-devices used by the DTrace framework. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/dev/fbs\fR\fR +.ad +.sp .6 +.RS 4n +Frame buffer device files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/fd\fR\fR +.ad +.sp .6 +.RS 4n +File descriptors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/md\fR\fR +.ad +.sp .6 +.RS 4n +Logical volume management meta-disk devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/net\fR\fR +.ad +.sp .6 +.RS 4n +Network data-link interface devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/printers\fR\fR +.ad +.sp .6 +.RS 4n +USB printer device files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/pts\fR\fR +.ad +.sp .6 +.RS 4n +Pseudo-terminal devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/rdsk\fR\fR +.ad +.sp .6 +.RS 4n +Raw disk devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/rmt\fR\fR +.ad +.sp .6 +.RS 4n +Raw tape devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/sad\fR\fR +.ad +.sp .6 +.RS 4n +Entry points for the \fBSTREAMS\fR Administrative driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/sound\fR\fR +.ad +.sp .6 +.RS 4n +Audio device and audio device control files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/swap\fR\fR +.ad +.sp .6 +.RS 4n +Default swap device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/dev/term\fR\fR +.ad +.sp .6 +.RS 4n +Terminal devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/devices\fR\fR +.ad +.sp .6 +.RS 4n +Physical device files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/X11\fR\fR +.ad +.sp .6 +.RS 4n +Xorg Xserver (X11) configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/acct\fR\fR +.ad +.sp .6 +.RS 4n +Accounting system configuration information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/apache\fR\fR +.ad +.sp .6 +.RS 4n +Apache configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/apoc\fR\fR +.ad +.sp .6 +.RS 4n +Files for configuring Sun Java Desktop System Configuration Manager remote +access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/bonobo-activation\fR\fR +.ad +.sp .6 +.RS 4n +GNOME XML configuration file for identifying CORBA servers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/cron.d\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for \fBcron\fR(1M). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/default\fR\fR +.ad +.sp .6 +.RS 4n +Defaults information for various programs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/devices\fR\fR +.ad +.sp .6 +.RS 4n +Contains device-related data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/dfs\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for shared file systems. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/dhcp\fR\fR +.ad +.sp .6 +.RS 4n +Dynamic Host Configuration Protocol (\fBDHCP\fR) configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/dmi\fR\fR +.ad +.sp .6 +.RS 4n +Solstice Enterprise Agents configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/dt\fR\fR +.ad +.sp .6 +.RS 4n +Desktop configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/flash\fR\fR +.ad +.sp .6 +.RS 4n +Solaris Flash Archive configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/fm\fR\fR +.ad +.sp .6 +.RS 4n +Fault manager configuration files. For more information, see \fBfmd\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/fonts\fR\fR +.ad +.sp .6 +.RS 4n +Font configuration information. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/ftpd\fR\fR +.ad +.sp .6 +.RS 4n +\fBftpd\fR configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gconf\fR\fR +.ad +.sp .6 +.RS 4n +GConf system configuration (including system defaults and system mandatory +settings) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gimp\fR\fR +.ad +.sp .6 +.RS 4n +GNU Image Manipulation Program (GIMP) configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gnome\fR\fR +.ad +.sp .6 +.RS 4n +GNOME Desktop configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gnome-vfs-2.0\fR\fR +.ad +.sp .6 +.RS 4n +Files for customizing GNOME 2.0 desktop menus. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gnopernicus-1.0\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for GNOME's Gnopernicus, an Assistive Technology (AT) +screen reader. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/gtk\fR\fR +.ad +.sp .6 +.RS 4n +GTK+ configuration files +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gtk-2.0\fR\fR +.ad +.sp .6 +.RS 4n +GTK+ Pixbuf loaders and Input Method modules +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/imq\fR\fR +.ad +.sp .6 +.RS 4n +Sun Java System Message Queue security configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/inet\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for Internet services. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/init.d\fR\fR +.ad +.sp .6 +.RS 4n +Shell scripts for transitioning between run levels. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/krb5\fR\fR +.ad +.sp .6 +.RS 4n +Kerberos configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/lib\fR\fR +.ad +.sp .6 +.RS 4n +Shared libraries needed during booting. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/llc2\fR\fR +.ad +.sp .6 +.RS 4n +Logical link control (\fBllc2\fR) driver configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/lp\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for the printer subsystem. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/lvm\fR\fR +.ad +.sp .6 +.RS 4n +Solaris Logical Volume Manager configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/mail\fR\fR +.ad +.sp .6 +.RS 4n +Mail subsystem configuration. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/net\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for transport independent network services. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nfs\fR\fR +.ad +.sp .6 +.RS 4n +NFS server logging configuration file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/opt\fR\fR +.ad +.sp .6 +.RS 4n +Configuration information for optional packages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/pango\fR\fR +.ad +.sp .6 +.RS 4n +Pango configuration and module information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/patch\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for patch management. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/ppp\fR\fR +.ad +.sp .6 +.RS 4n +Solaris \fBPPP\fR configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rc0.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 0. See \fBinit\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rc1.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 1. See \fBinit\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rc2.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 2. See \fBinit\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rc3.d\fR\fR +.ad +.sp .6 +.RS 4n +Scripts for entering or leaving run level 3. See \fBinit\fR(1M). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/rcm\fR\fR +.ad +.sp .6 +.RS 4n +Directory for reconfiguration manager (RCM) custom scripts. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rpcsec\fR\fR +.ad +.sp .6 +.RS 4n +This directory might contain an \fBNIS+\fR authentication configuration file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/saf\fR\fR +.ad +.sp .6 +.RS 4n +Service Access Facility files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/etc/sfw\fR\fR +.ad +.sp .6 +.RS 4n +Platform-dependent administrative, configuration files and databases for +subsystems from \fB/usr/sfw\fR that are not shared among systems. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/sfw/samba\fR\fR +.ad +.sp .6 +.RS 4n +Samba configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/skel\fR\fR +.ad +.sp .6 +.RS 4n +Default profile scripts for new user accounts. See \fBuseradd\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/sma\fR\fR +.ad +.sp .6 +.RS 4n +Systems Management Agent (SMA) configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/smartcard\fR\fR +.ad +.sp .6 +.RS 4n +Solaris Smart Card configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/snmp\fR\fR +.ad +.sp .6 +.RS 4n +Solstice Enterprise Agents configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/sound\fR\fR +.ad +.sp .6 +.RS 4n +Sound Events configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/ssh\fR\fR +.ad +.sp .6 +.RS 4n +Secure Shell configuration files. See \fBssh\fR(1) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/svc\fR\fR +.ad +.sp .6 +.RS 4n +SMF service repository. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/sysevent\fR\fR +.ad +.sp .6 +.RS 4n +\fBsyseventd\fR configuration files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/etc/tm\fR\fR +.ad +.sp .6 +.RS 4n +Trademark files; contents displayed at boot time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/usb\fR\fR +.ad +.sp .6 +.RS 4n +\fBUSB\fR configuration information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/uucp\fR\fR +.ad +.sp .6 +.RS 4n +\fBUUCP\fR configuration information. See \fBuucp\fR(1C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/xml\fR\fR +.ad +.sp .6 +.RS 4n +Extensible Markup Language (XML) catalog. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/zones\fR\fR +.ad +.sp .6 +.RS 4n +Solaris Zones configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/export\fR\fR +.ad +.sp .6 +.RS 4n +Default root of the shared file system tree. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/home\fR\fR +.ad +.sp .6 +.RS 4n +Default root of a subtree for user directories. +.RE + +.sp +.ne 2 +.mk +.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(1M) An approved +installation location for bundled Solaris software and for add-on system +software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/kernel/drv\fR\fR +.ad +.sp .6 +.RS 4n +32-bit x86 device drivers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/kernel/drv/sparcv9\fR\fR +.ad +.sp .6 +.RS 4n +64-bit \fBSPARC\fR device drivers. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/kernel/dtrace\fR\fR +.ad +.sp .6 +.RS 4n +Kernel modules representing components in the DTrace framework. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/kernel/genunix\fR\fR +.ad +.sp .6 +.RS 4n +Platform-independent kernel. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/kernel/amd64/genunix\fR\fR +.ad +.sp .6 +.RS 4n +64-bit, platform-independent kernel. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/opt\fR\fR +.ad +.sp .6 +.RS 4n +Root of a subtree for add-on application packages. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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(1M). An approved installation location for bundled Solaris +software and for add-on system software. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/proc\fR\fR +.ad +.sp .6 +.RS 4n +Root of a subtree for the process file system. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/system\fR\fR +.ad +.sp .6 +.RS 4n +Mount point for the contract (CTFS) and object (OBJFS) file systems. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/tmp\fR\fR +.ad +.sp .6 +.RS 4n +Temporary files; cleared during the boot operation. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/var/adm\fR\fR +.ad +.sp .6 +.RS 4n +System logging and accounting files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/apache\fR\fR +.ad +.sp .6 +.RS 4n +Scripts, icons, logs, and cache pages for Apache web server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/appserver\fR\fR +.ad +.sp .6 +.RS 4n +Sun Java System Application Server administrative domain files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/audit\fR\fR +.ad +.sp .6 +.RS 4n +Default location for Solaris Audit log files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/cores\fR\fR +.ad +.sp .6 +.RS 4n +Directory provided for global core files storage. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/crash\fR\fR +.ad +.sp .6 +.RS 4n +Default depository for kernel crash dumps. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/cron\fR\fR +.ad +.sp .6 +.RS 4n +Log files for \fBcron\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/dmi\fR\fR +.ad +.sp .6 +.RS 4n +Solstice Enterprise Agents (\fBSEA\fR) Desktop Management Interface (\fBDMI\fR) +run-time components. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/dt\fR\fR +.ad +.sp .6 +.RS 4n +\fBdtlogin\fR configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/fm\fR\fR +.ad +.sp .6 +.RS 4n +Fault manager state files. For more information, see \fBfmd\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/imq\fR\fR +.ad +.sp .6 +.RS 4n +Message queue broker instance configuration file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/ftp\fR\fR +.ad +.sp .6 +.RS 4n +\fBFTP\fR server directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/inet\fR\fR +.ad +.sp .6 +.RS 4n +IPv6 router state files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/krb5\fR\fR +.ad +.sp .6 +.RS 4n +Database and log files for Kerberos. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/ld\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for runtime linker. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/ldap\fR\fR +.ad +.sp .6 +.RS 4n +LDAP client configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/lib\fR\fR +.ad +.sp .6 +.RS 4n +Directory for variable state information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/log\fR\fR +.ad +.sp .6 +.RS 4n +System log files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/lp\fR\fR +.ad +.sp .6 +.RS 4n +Line printer subsystem logging information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/mail\fR\fR +.ad +.sp .6 +.RS 4n +Directory where users' mail is kept. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/mysql\fR\fR +.ad +.sp .6 +.RS 4n +Dynamic database directory for MySQL Database Management System. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/var/nfs\fR\fR +.ad +.sp .6 +.RS 4n +NFS server log files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/nis\fR\fR +.ad +.sp .6 +.RS 4n +NIS+ databases. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/ntp\fR\fR +.ad +.sp .6 +.RS 4n +Network Time Protocol (\fBNTP\fR) server state directory. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/var/patchsrv\fR\fR +.ad +.sp .6 +.RS 4n +Patch management log files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/var/sadm\fR\fR +.ad +.sp .6 +.RS 4n +Databases maintained by the software package management utilities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/sadm/system/logs\fR\fR +.ad +.sp .6 +.RS 4n +Status log files produced by software management functions and/or applications. +For example, log files produced for product installation. An approved +installation location for bundled Solaris software and for add-on system +software and applications. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/saf\fR\fR +.ad +.sp .6 +.RS 4n +Service access facility logging and accounting files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/samba\fR\fR +.ad +.sp .6 +.RS 4n +Log and lock files for Samba. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/sma_snmp\fR\fR +.ad +.sp .6 +.RS 4n +Systems Management Agent (SMA) security and MIB component information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/snmp\fR\fR +.ad +.sp .6 +.RS 4n +SNMP status and configuration information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool\fR\fR +.ad +.sp .6 +.RS 4n +Contains directories for files used in printer spooling, mail delivery, +\fBcron\fR(1M), \fBat\fR(1), and so forth. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/clientmqueue\fR\fR +.ad +.sp .6 +.RS 4n +\fBsendmail\fR(1M) client files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/cron\fR\fR +.ad +.sp .6 +.RS 4n +\fBcron\fR(1M) and \fBat\fR(1) spooling files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/locks\fR\fR +.ad +.sp .6 +.RS 4n +Spooling lock files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/var/spool/mqueue\fR\fR +.ad +.sp .6 +.RS 4n +Mail queued for delivery. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/pkg\fR\fR +.ad +.sp .6 +.RS 4n +Spooled packages. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/var/spool/samba\fR\fR +.ad +.sp .6 +.RS 4n +Samba print queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/uucp\fR\fR +.ad +.sp .6 +.RS 4n +Queued \fBuucp\fR(1C) jobs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/uucppublic\fR\fR +.ad +.sp .6 +.RS 4n +Files deposited by \fBuucp\fR(1C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/statmon\fR\fR +.ad +.sp .6 +.RS 4n +Network status monitor files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/svc/log\fR\fR +.ad +.sp .6 +.RS 4n +SMF log files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/var/svc/manifest/site\fR\fR +.ad +.sp .6 +.RS 4n +Site-local SMF service manifests. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/var/uucp\fR\fR +.ad +.sp .6 +.RS 4n +\fBuucp\fR(1C) log and status files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/yp\fR\fR +.ad +.sp .6 +.RS 4n +Databases needed for backwards compatibility with \fBNIS\fR and +\fBypbind\fR(1M); unnecessary after full transition to \fBNIS+\fR. +.RE + +.SS "\fB/usr\fR File System" +.sp +.LP +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 +.mk +.na +\fB\fB/usr/4lib\fR\fR +.ad +.sp .6 +.RS 4n +\fBa.out\fR libraries for the Binary Compatibility Package. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/SUNWale\fR\fR +.ad +.sp .6 +.RS 4n +Configuration files for Asian Lanuguage Environment (ALE). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/X\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to the \fB/usr/openwin\fR directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/X11\fR\fR +.ad +.sp .6 +.RS 4n +Xorg Xserver (X11) executables and documentation. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/apache\fR\fR +.ad +.sp .6 +.RS 4n +Apache executables, loadable modules, and documentation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/appserver\fR\fR +.ad +.sp .6 +.RS 4n +Sun Java System Application Server software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/benchmarks\fR\fR +.ad +.sp .6 +.RS 4n +Directory for benchmarks. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/bin/amd64\fR\fR +.ad +.sp .6 +.RS 4n +x86 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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/ccs\fR\fR +.ad +.sp .6 +.RS 4n +C compilation system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/ccs/bin\fR\fR +.ad +.sp .6 +.RS 4n +C compilation commands and system utilities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/ccs/lib\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to \fB/usr/lib\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/demo\fR\fR +.ad +.sp .6 +.RS 4n +Demo programs and data. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/dt\fR\fR +.ad +.sp .6 +.RS 4n +root of a subtree for CDE software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/dt/bin\fR\fR +.ad +.sp .6 +.RS 4n +Primary location for CDE system utilities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/dt/include\fR\fR +.ad +.sp .6 +.RS 4n +Header files for CDE software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/dt/lib\fR\fR +.ad +.sp .6 +.RS 4n +Libraries for CDE software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/dt/share/man\fR\fR +.ad +.sp .6 +.RS 4n +On-line reference manual pages for CDE software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/games\fR\fR +.ad +.sp .6 +.RS 4n +An empty directory, a remnant of the SunOS 4.0/4.1 software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/gnome\fR\fR +.ad +.sp .6 +.RS 4n +This is an obsolete directory where 3rd party programs can install their +applications and \fBpixmap\fR files. It is supported for backwards +compatibility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/include\fR\fR +.ad +.sp .6 +.RS 4n +Include headers (for C programs). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/j2se\fR\fR +.ad +.sp .6 +.RS 4n +Java 2 SDK executables, loadable modules, and documentation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/java\fI*\fR\fR\fR +.ad +.sp .6 +.RS 4n +Directories containing Java programs and libraries. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/32\fR\fR +.ad +.sp .6 +.RS 4n +Symbolic link to \fB/usr/lib\fR. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/acct\fR\fR +.ad +.sp .6 +.RS 4n +Accounting scripts and binaries. See \fBacct\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/adb\fR\fR +.ad +.sp .6 +.RS 4n +\fBadb\fR accounting scripts. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/autofs\fR\fR +.ad +.sp .6 +.RS 4n +Contains the \fBautomountd\fR executable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/cfgadm\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBcfgadm\fR hardware-specific driver plugins. +.RE + +.sp +.ne 2 +.mk +.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(1M). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/dict\fR\fR +.ad +.sp .6 +.RS 4n +Database files for \fBspell\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/dns\fR\fR +.ad +.sp .6 +.RS 4n +Contains DNS resolver libraries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/dtrace\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBdtrace\fR D source files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/flash\fR\fR +.ad +.sp .6 +.RS 4n +Contains Solaris flash archive deployment scripts. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/font\fR\fR +.ad +.sp .6 +.RS 4n +\fBtroff\fR(1) font description files. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/gss\fR\fR +.ad +.sp .6 +.RS 4n +Secure services-related libraries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv\fR\fR +.ad +.sp .6 +.RS 4n +Conversion tables for \fBiconv\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/inet\fR\fR +.ad +.sp .6 +.RS 4n +Contains many network-related daemons and libraries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/ipf\fR\fR +.ad +.sp .6 +.RS 4n +Contains \fBIPFILTER.LICENCE\fR and \fBipftest\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/ipqosconf\fR\fR +.ad +.sp .6 +.RS 4n +IPQoS configuration utility. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/ldap\fR\fR +.ad +.sp .6 +.RS 4n +Contains LDAP client configuration utilities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/libp\fR\fR +.ad +.sp .6 +.RS 4n +Profiled libraries. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/locale\fR\fR +.ad +.sp .6 +.RS 4n +Localization databases. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/netsvc\fR\fR +.ad +.sp .6 +.RS 4n +Internet network services. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/nfs\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary NFS-related programs and daemons. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/nis\fR\fR +.ad +.sp .6 +.RS 4n +Contains NIS+ administrative commands. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/picl\fR\fR +.ad +.sp .6 +.RS 4n +Platform Information and Control Library. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/power\fR\fR +.ad +.sp .6 +.RS 4n +Power management daemon, \fBpowerd\fR. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/rcap\fR\fR +.ad +.sp .6 +.RS 4n +Resource cap enforcement daemon, \fBrcapd\fR. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/refer\fR\fR +.ad +.sp .6 +.RS 4n +Auxiliary programs for \fBrefer\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/rmmount\fR\fR +.ad +.sp .6 +.RS 4n +Removable media mounter shared objects. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/secure\fR\fR +.ad +.sp .6 +.RS 4n +Default trusted libraries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/security\fR\fR +.ad +.sp .6 +.RS 4n +Solaris security plug-in modules. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/smartcard\fR\fR +.ad +.sp .6 +.RS 4n +IFD handler libraries. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/ssh\fR\fR +.ad +.sp .6 +.RS 4n +Contains the Secure Shell daemon (\fBsshd\fR) and supporting programs. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/lib/webconsole\fR\fR +.ad +.sp .6 +.RS 4n +Sun Java web console programs and scripts. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/zones\fR\fR +.ad +.sp .6 +.RS 4n +Zone administration daemon (\fBzoneamd\fR). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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(1M). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/old\fR\fR +.ad +.sp .6 +.RS 4n +Programs that are being phased out. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/openwin\fR\fR +.ad +.sp .6 +.RS 4n +Installation or mount point for the OpenWindows software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/perl5\fR\fR +.ad +.sp .6 +.RS 4n +Perl 5 programs and documentation +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/proc\fR\fR +.ad +.sp .6 +.RS 4n +Directory for the \fBproc\fR tools. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/sadm\fR\fR +.ad +.sp .6 +.RS 4n +System administration files and directories. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/sadm/bin\fR\fR +.ad +.sp .6 +.RS 4n +Binaries for the Form and Menu Language Interpreter (\fBFMLI\fR) scripts. See +\fBfmli\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/sadm/install\fR\fR +.ad +.sp .6 +.RS 4n +Executables and scripts for package management. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/sbin/install.d\fR\fR +.ad +.sp .6 +.RS 4n +Custom Jumpstart scripts and executables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/sbin/sparc7\fR and \fBsparc9\fR\fR +.ad +.sp .6 +.RS 4n +32-bit and 64-bit versions of commands. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/sbin/amd64\fR\fR +.ad +.sp .6 +.RS 4n +64-bit x86versions of commands. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/sfw\fR\fR +.ad +.sp .6 +.RS 4n +\fBGNU\fR and open source executables, libraries, and documentation. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/share/aclocal\fR\fR +.ad +.sp .6 +.RS 4n +Open source \fBm4\fR files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/applications\fR\fR +.ad +.sp .6 +.RS 4n +Open source desktop applications files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/audio\fR\fR +.ad +.sp .6 +.RS 4n +Sample audio files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/glib-2.0\fR\fR +.ad +.sp .6 +.RS 4n +Makefile for \fBglib\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/gnome\fR\fR +.ad +.sp .6 +.RS 4n +GNOME desktop and application data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/gtk-2.0\fR\fR +.ad +.sp .6 +.RS 4n +GTK+ application data and demos +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/gtk-doc\fR\fR +.ad +.sp .6 +.RS 4n +API documentation for libraries which use gtk-doc documentation format, which +mostly includes desktop interfaces. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/icons\fR\fR +.ad +.sp .6 +.RS 4n +Sun Java Desktop icons. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/idl\fR\fR +.ad +.sp .6 +.RS 4n +Open source Interface Definition Language (IDL) files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/intltool\fR\fR +.ad +.sp .6 +.RS 4n +XML translation tools. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/ipfilter\fR\fR +.ad +.sp .6 +.RS 4n +Open source IP Filter sample files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/javadoc\fR\fR +.ad +.sp .6 +.RS 4n +Help files for Message Queue broker and Smart Card applications. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/share/lib/keytables\fR\fR +.ad +.sp .6 +.RS 4n +Keyboard layout description tables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/mailx\fR\fR +.ad +.sp .6 +.RS 4n +Help files for \fBmailx\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/nterm\fR\fR +.ad +.sp .6 +.RS 4n +\fBnroff\fR(1) terminal tables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/pub\fR\fR +.ad +.sp .6 +.RS 4n +Character set data files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/tabset\fR\fR +.ad +.sp .6 +.RS 4n +Tab setting escape sequences. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/terminfo\fR\fR +.ad +.sp .6 +.RS 4n +Terminal description files for \fBterminfo\fR(4). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/share/lib/zoneinfo\fR\fR +.ad +.sp .6 +.RS 4n +Time zone information. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/share/omf\fR\fR +.ad +.sp .6 +.RS 4n +GNOME Scrollkeeper database files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/pixmaps\fR\fR +.ad +.sp .6 +.RS 4n +Sun Java graphics. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/scrollkeeper\fR\fR +.ad +.sp .6 +.RS 4n +GNOME Scrollkeeper templates and \fBxslt\fR files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/sgml\fR\fR +.ad +.sp .6 +.RS 4n +Open source SGML files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/sounds\fR\fR +.ad +.sp .6 +.RS 4n +Sound files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/src\fR\fR +.ad +.sp .6 +.RS 4n +Source code for kernel, utilities, and libraries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/themes\fR\fR +.ad +.sp .6 +.RS 4n +GNOME 2.0 Desktop themes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/webconsole\fR\fR +.ad +.sp .6 +.RS 4n +Sun Web Console status files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/xml\fR\fR +.ad +.sp .6 +.RS 4n +GNOME Scrollkeeper DTD files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/snadm\fR\fR +.ad +.sp .6 +.RS 4n +Files related to system and network administration. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fB/usr/ucb\fR\fR +.ad +.sp .6 +.RS 4n +Berkeley compatibility package binaries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/ucbinclude\fR\fR +.ad +.sp .6 +.RS 4n +Berkeley compatibility package headers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/ucblib\fR\fR +.ad +.sp .6 +.RS 4n +Berkeley compatibility package libraries. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/xpg4\fR\fR +.ad +.sp .6 +.RS 4n +Directory for POSIX-compliant utilities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/xpg6\fR\fR +.ad +.sp .6 +.RS 4n +Directory for newer versions of POSIX-compliant utilities. +.RE + +.SH SEE ALSO +.sp +.LP +\fBat\fR(1), \fBex\fR(1), \fBfmli\fR(1), \fBiconv\fR(1), \fBlp\fR(1), +\fBisainfo\fR(1), \fBmail\fR(1), \fBmailx\fR(1), \fBnroff\fR(1), +\fBpriocntl\fR(1), \fBrefer\fR(1), \fBsar\fR(1), \fBsh\fR(1), \fBspell\fR(1), +\fBsvcs\fR(1), \fBtroff\fR(1), \fBuname\fR(1), \fBuucp\fR(1C), \fBvi\fR(1), +\fBacct\fR(1M), \fBcron\fR(1M), \fBdispadmin\fR(1M), \fBdladm\fR(1M), +\fBfmd\fR(1M), \fBfsck\fR(1M), \fBinit\fR(1M), \fBkernel\fR(1M), +\fBmknod\fR(1M), \fBmount\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), +\fBuseradd\fR(1M), \fBypbind\fR(1M), \fBmount\fR(2), \fBIntro\fR(4), +\fBterminfo\fR(4) diff --git a/usr/src/man/man5/fnmatch.5 b/usr/src/man/man5/fnmatch.5 new file mode 100644 index 0000000000..3dff89c01c --- /dev/null +++ b/usr/src/man/man5/fnmatch.5 @@ -0,0 +1,328 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited +.\" All Rights Reserved Portions Copyright (c) 1995, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH fnmatch 5 "28 Mar 1995" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +fnmatch \- file name pattern matching +.SH DESCRIPTION +.sp +.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(5) manual page. +.SS "Patterns Matching a Single Character" +.sp +.LP +The following \fIpatterns matching a single character\fR 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 +.mk +.na +\fB\fB?\fR \fR +.ad +.RS 6n +.rt +A question-mark is a pattern that will match any character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB*\fR \fR +.ad +.RS 6n +.rt +An asterisk is a pattern that will match multiple characters, as described in +\fBPatterns Matching Multiple Characters\fR, below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB[\fR \fR +.ad +.RS 6n +.rt +The open bracket will introduce a pattern bracket expression. +.RE + +.sp +.LP +The description of basic regular expression bracket expressions on the +\fBregex\fR(5) 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 +tab(); +lw(1.01i) lw(1.18i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.01i) lw(1.18i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\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 +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +. +\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" +.sp +.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 +.mk +.na +\fB\fBa[bc]\fR \fR +.ad +.RS 10n +.rt +matches the strings \fBab\fR and \fBac\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa*d\fR \fR +.ad +.RS 10n +.rt +matches the strings \fBad\fR, \fBabd\fR and \fBabcd\fR, but not the string +\fBabc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa*d*\fR \fR +.ad +.RS 10n +.rt +matches the strings \fBad\fR, \fBabcd\fR, \fBabcdef\fR, \fBaaaad\fR and +\fBadddd\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB*a*d\fR \fR +.ad +.RS 10n +.rt +matches the strings \fBad\fR, \fBabcd\fR, \fBefabcd\fR, \fBaaaad\fR and +\fBadddd\fR. +.RE + +.SS "Patterns Used for Filename Expansion" +.sp +.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 +.sp +.LP +\fBfind\fR(1), \fBksh\fR(1), \fBfnmatch\fR(3C), \fBregex\fR(5) diff --git a/usr/src/man/man5/formats.5 b/usr/src/man/man5/formats.5 new file mode 100644 index 0000000000..3817067871 --- /dev/null +++ b/usr/src/man/man5/formats.5 @@ -0,0 +1,486 @@ +'\" te +.\" Copyright 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH formats 5 "28 Mar 1995" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fI\fR\fIcharacters\fR\fI\fR \fR +.ad +.RS 30n +.rt +Characters that are not \fIescape sequences\fR or \fIconversion +specifications\fR, as described below, are copied to the output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI\fR\fIescape sequences\fR\fI\fR \fR +.ad +.RS 30n +.rt +Represent non-graphic characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI\fR\fIconversion specifications\fR\fI\fR \fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB`` \&''\fR +.ad +.RS 11n +.rt +(An empty character position.) One or more blank characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB/\e \fR +.ad +.RS 11n +.rt +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 +tab(); +cw(1.21i) cw(1.15i) cw(3.14i) +lw(1.21i) lw(1.15i) lw(3.14i) +. +\fBSequence\fR\fBCharacter\fR\fBTerminal Action\fR +_ +\fB\e\e\fRbackslashNone. +\fB\ea\fRalertT{ +Attempts to alert the user through audible or visible notification. +T} +\fB\eb\fRbackspaceT{ +Moves the printing position to one column before the current position, unless the current position is the start of a line. +T} +\fB\ef\fRform-feedT{ +Moves the printing position to the initial printing position of the next logical page. +T} +\fB\en\fRnewlineT{ +Moves the printing position to the start of the next line. +T} +\fB\er\fRcarriage-returnT{ +Moves the printing position to the start of the current line. +T} +\fB\et\fRtabT{ +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\fRvertical-tabT{ +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 +.mk +.na +\fB\fI\fR\fIflags\fR\fI\fR \fR +.ad +.RS 26n +.rt +Zero or more \fIflags\fR, in any order, that modify the meaning of the +conversion specification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI\fR\fIfield width\fR\fI\fR \fR +.ad +.RS 26n +.rt +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 +.mk +.na +\fB\fI\fR\fIprecision\fR\fI\fR \fR +.ad +.RS 26n +.rt +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 +.mk +.na +\fB\fI\fR\fIconversion characters\fR\fI\fR \fR +.ad +.RS 26n +.rt +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 +.mk +.na +\fB\fI\(mi\fR \fR +.ad +.RS 12n +.rt +The result of the conversion is left-justified within the field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI+\fR \fR +.ad +.RS 12n +.rt +The result of a signed conversion always begins with a sign (+ or \(mi). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI<space>\fR \fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fI#\fR \fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fI0\fR \fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fB\fId,i,o,u,x,X\fR \fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fIf\fR \fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fIe,E\fR \fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fIg,G\fR \fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fIc\fR \fR +.ad +.RS 16n +.rt +The integer argument is converted to an \fBunsigned char\fR and the resulting +byte is written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIs\fR \fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fI%\fR \fR +.ad +.RS 16n +.rt +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 +\fBawk\fR(1), \fBprintf\fR(1), \fBprintf\fR(3C), \fBscanf\fR(3C) diff --git a/usr/src/man/man5/fsattr.5 b/usr/src/man/man5/fsattr.5 new file mode 100644 index 0000000000..492b8d174e --- /dev/null +++ b/usr/src/man/man5/fsattr.5 @@ -0,0 +1,831 @@ +'\" 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 5 "10 Oct 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBlink\fR\fR +.ad +.RS 25n +.rt +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 +.mk +.na +\fB\fBrename\fR\fR +.ad +.RS 25n +.rt +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 +.mk +.na +\fB\fBmkdir\fR, \fBsymlink\fR, \fBmknod\fR\fR +.ad +.RS 25n +.rt +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 +.mk +.na +\fB\fBcp\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBcpio\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBdu\fR\fR +.ad +.RS 8n +.rt +File sizes computed include the space allocated for any extended attributes +present. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfind\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBfsck\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBfsdb\fR\fR +.ad +.RS 8n +.rt +This \fBfsdb\fR utility is able to find the inode for the "hidden" extended +attribute directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBls\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBmv\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBpax\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBtar\fR\fR +.ad +.RS 8n +.rt +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(5). +.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 +tab(); +cw(1.83i) cw(1.83i) cw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +Field NameLength (in Octets)Description +Name100File name string +Mode812 file mode bits +Uid8User ID of file owner +Gid8Group ID of file owner +Size12Size of file +Mtime12File modification time +Chksum8File contents checksum +Typeflag1File type flag +Linkname100Link target name if file linked +Magic6"ustar" +Version2"00" +Uname32User name of file owner +Gname32Group name of file owner +Devmajor8Major device ID if special file +Devminor8Minor device ID if special file +Prefix155Path 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 +tab(); +cw(1.83i) cw(1.83i) cw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +\fBField Name\fRLength (in Octets)Description +\fBc_magic\fR670707 +\fBc_dev\fR6First half of unique file ID +\fBc_ino\fR6Second half of unique file ID +\fBc_mode\fR6File mode bits +\fBc_uid\fR6User ID of file owner +\fBc_gid\fR6Group ID of file owner +\fBc_nlink\fR6Number of links referencing file +\fBc_rdev\fR6Information for special files +\fBc_mtime\fR11Modification time of file +\fBc_namesize\fR6Length of file pathname +\fBc_filesize\fR11Length of file content +\fBc_name\fR\fBc_namesize\fRFile pathname +\fBc_filedata\fR\fBc_filesize\fRFile 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 +tab(); +cw(1.7i) cw(1.76i) cw(2.04i) +lw(1.7i) lw(1.76i) lw(2.04i) +. +Field NameLength (in Octets)Description +\fBh_version\fR7Name file version +\fBh_size\fR10Length of data file +\fBh_component_len\fR10Total length of all path segments +\fBh_link_comp_len\fR10Total length of all link segments +\fBpath\fR\fBh_component_len\fRComplex path +\fBlink_path\fR\fBh_link_comp_len\fRComplex 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 +tab(); +cw(1.57i) cw(1.74i) cw(2.19i) +lw(1.57i) lw(1.74i) lw(2.19i) +. +Field NameLength (in Octets)Description +_ +\fBh_namesz\fR7Length of segment path +\fBh_typeflag\fR1Actual file type of attribute file +\fBh_names\fR\fBh_namesz\fRParent 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 +\fBcp\fR(1), \fBcpio\fR(1), \fBfind\fR(1), \fBls\fR(1), \fBmv\fR(1), +\fBpax\fR(1), \fBrunat\fR(1), \fBtar\fR(1), \fBdu\fR(1), \fBfsck\fR(1M), +\fBchown\fR(2), \fBlink\fR(2), \fBopen\fR(2), \fBpathconf\fR(2), +\fBrename\fR(2), \fBstat\fR(2), \fBunlink\fR(2), \fButimes\fR(2), +\fBattropen\fR(3C), \fBstandards\fR(5) diff --git a/usr/src/man/man5/grub.5 b/usr/src/man/man5/grub.5 new file mode 100644 index 0000000000..f4a6311811 --- /dev/null +++ b/usr/src/man/man5/grub.5 @@ -0,0 +1,89 @@ +'\" 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 5 "21 Apr 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBbootadm\fR(1M)\fR +.ad +.RS 19n +.rt +Enables you to manage the boot archive and make changes to the GRUB menu. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinstallgrub\fR(1M)\fR +.ad +.RS 19n +.rt +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 +\fBboot\fR(1M), \fBbootadm\fR(1M), \fBinstallgrub\fR(1M) +.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/man5/gss_auth_rules.5 b/usr/src/man/man5/gss_auth_rules.5 new file mode 100644 index 0000000000..1c3417536a --- /dev/null +++ b/usr/src/man/man5/gss_auth_rules.5 @@ -0,0 +1,79 @@ +'\" 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 5 "13 Apr 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5), 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 +.mk +.na +\fB\fB/etc/passwd\fR\fR +.ad +.RS 15n +.rt +System account file. This information may also be in a directory service. See +\fBpasswd\fR(4). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBftp\fR(1), \fBssh\fR(1), \fBgsscred\fR(1M), \fBgss_compare_name\fR(3GSS), +\fBpasswd\fR(4), \fBattributes\fR(5), \fBkrb5_auth_rules\fR(5) diff --git a/usr/src/man/man5/hal.5 b/usr/src/man/man5/hal.5 new file mode 100644 index 0000000000..6a603b4748 --- /dev/null +++ b/usr/src/man/man5/hal.5 @@ -0,0 +1,40 @@ +'\" 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 5 "11 Sep 2006" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +hal \- overview of hardware abstraction layer +.SH DESCRIPTION +.sp +.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 +identifer 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(1M), +and a set of utilities that enable the adding and removing of devices and the +modification of their properties. +.SH SEE ALSO +.sp +.LP +\fBhald\fR(1M), \fBfdi\fR(4) +.sp +.LP +See the HAL pages, including the HAL specification, under +http://freedesktop.org. diff --git a/usr/src/man/man5/iconv.5 b/usr/src/man/man5/iconv.5 new file mode 100644 index 0000000000..4974b31215 --- /dev/null +++ b/usr/src/man/man5/iconv.5 @@ -0,0 +1,281 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH iconv 5 "5 Dec 2001" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +tab() box; +cw(1.83i) |cw(1.83i) |cw(1.83i) +lw(1.83i) |lw(1.83i) |lw(1.83i) +. +\fBIndex of Conversion Code Tables\fR +_ +\fBCode\fR\fBTarget Code\fR\fBSee Manual Page\fR +_ +ISO 646ISO 8859-1iconv_646 (5) +_ +ISO 646deISO 8859-1 +_ +ISO 646daISO 8859-1 +_ +ISO 646enISO 8859-1 +_ +ISO 646esISO 8859-1 +_ +ISO 646frISO 8859-1 +_ +ISO 646itISO 8859-1 +_ +ISO 646svISO 8859-1 +_ +ISO 8859-1ISO 646iconv_8859-1 (5) +_ +ISO 8859-1ISO 646de +_ +ISO 8859-1ISO 646da +_ +ISO 8859-1ISO 646en +_ +ISO 8859-1ISO 646es +_ +ISO 8859-1ISO 646fr +_ +ISO 8859-1ISO 646it +_ +ISO 8859-1ISO 646sv +_ +ISO 8859-2MS 1250iconv_8859-2 (5) +_ +ISO 8859-2MS 852 +_ +ISO 8859-2Mazovia +_ +ISO 8859-2DHN +_ +MS 1250ISO 8859-2iconv_1250 (5) +_ +MS 1250MS 852 +_ +MS 1250Mazovia +_ +MS 1250DHN +_ +MS 852ISO 8859-2iconv_852 (5) +_ +MS 852MS 1250 +_ +MS 852Mazovia +_ +MS 852DHN +_ +MazoviaISO 8859-2iconv_maz (5) +_ +MazoviaMS 1250 +_ +MazoviaMS 852 +_ +MazoviaDHN +.TE + +.sp + +.sp +.TS +tab() box; +cw(1.83i) |cw(1.83i) |cw(1.83i) +lw(1.83i) |lw(1.83i) |lw(1.83i) +. +\fBIndex of Conversion Code Tables\fR +_ +\fBCode\fR\fBTarget Code\fR\fBSee Manual Page\fR +_ +DHNISO 8859-2 iconv_dhn (5) +_ +DHNMS 1250 +_ +DHNMS 852 +_ +DHNMazovia +_ +ISO 8859-5KOI8-R iconv_8859-5 (5) +_ +ISO 8859-5PC Cyrillic +_ +ISO 8859-5MS 1251 +_ +ISO 8859-5Mac Cyrillic +_ +KOI8-RISO 8859-5iconv_koi8-r (5) +_ +KOI8-RPC Cyrillic +_ +KOI8-RMS 1251 +_ +KOI8-RMac Cyrillic +_ +PC CyrillicISO 8859-5iconv_pc_cyr (5) +_ +PC CyrillicKOI8-R +_ +PC CyrillicMS 1251 +_ +PC CyrillicMac Cyrillic +_ +MS 1251ISO 8859-5iconv_1251 (5) +_ +MS 1251KOI8-R +_ +MS 1251PC Cyrillic +_ +MS 1251Mac Cyrillic +_ +Mac CyrillicISO 8859-5iconv_mac_cyr (5) +_ +Mac CyrillicKOI8-R +_ +Mac CyrillicPC Cyrillic +_ +Mac CyrillicMS 1251 +.TE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/*.so\fR\fR +.ad +.sp .6 +.RS 4n +conversion modules +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/*.t\fR\fR +.ad +.sp .6 +.RS 4n +Conversion tables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/geniconvtbl/binarytables/*.bt\fR\fR +.ad +.sp .6 +.RS 4n +Conversion binary tables. +.RE + +.sp +.ne 2 +.mk +.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 +\fBiconv\fR(1), \fBiconv\fR(3C), \fBiconv_1250\fR(5), \fBiconv_1251\fR(5), +\fBiconv_646\fR(5), \fBiconv_852\fR(5), \fBiconv_8859-1\fR(5), +\fBiconv_8859-2\fR(5), \fBiconv_8859-5\fR(5), \fBiconv_dhn\fR(5), +\fBiconv_koi8-r\fR(5), \fBiconv_mac_cyr\fR(5), \fBiconv_maz\fR(5), +\fBiconv_pc_cyr\fR(5), \fBiconv_unicode\fR(5) diff --git a/usr/src/man/man5/iconv_unicode.5 b/usr/src/man/man5/iconv_unicode.5 new file mode 100644 index 0000000000..cef2dc6c3b --- /dev/null +++ b/usr/src/man/man5/iconv_unicode.5 @@ -0,0 +1,341 @@ +'\" 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 5 "18 Apr 1997" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fB/usr/lib/iconv/*.so\fR\fR +.ad +.RS 23n +.rt +conversion modules +.RE + +.SH SEE ALSO +.sp +.LP +\fBiconv\fR(1), \fBiconv\fR(3C), \fBiconv\fR(5) +.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 +.mk +.na +\fB\fBISO\fR \fB8859-1\fR \fB(Latin\fR \fB1)\fR\fR +.ad +.RS 25n +.rt +For most West European languages, including: +.sp + +.sp +.TS +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +AlbanianFinnishItalian +CatalanFrenchNorwegian +DanishGermanPortuguese +DutchGalicianSpanish +EnglishIrishSwedish +FaeroeseIcelandic +.TE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBISO\fR \fB8859-2\fR \fB(Latin\fR \fB2)\fR\fR +.ad +.RS 25n +.rt +For most Latin-written Slavic and Central European languages: +.sp + +.sp +.TS +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +CzechPolishSlovak +GermanRumanianSlovene +HungarianCroatian +.TE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBISO\fR \fB8859-3\fR \fB(Latin\fR \fB3)\fR\fR +.ad +.RS 25n +.rt +Popularly used for Esperanto, Galician, Maltese, and Turkish. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBISO\fR \fB8859-4\fR \fB(Latin\fR \fB4)\fR\fR +.ad +.RS 25n +.rt +Introduces letters for Estonian, Latvian, and Lithuanian. It is an incomplete +predecessor of ISO 8859-10 (Latin 6). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBISO\fR \fB8859-9\fR \fB(Latin\fR \fB5)\fR\fR +.ad +.RS 25n +.rt +Replaces the rarely needed Icelandic letters in ISO 8859-1 (Latin 1) with the +Turkish ones. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBISO\fR \fB8859-10\fR \fB(Latin\fR \fB6)\fR\fR +.ad +.RS 25n +.rt +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/man5/ieee802.11.5 b/usr/src/man/man5/ieee802.11.5 new file mode 100644 index 0000000000..6ce0f1cd42 --- /dev/null +++ b/usr/src/man/man5/ieee802.11.5 @@ -0,0 +1,166 @@ +'\" 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 5 "28 Nov 2006" "SunOS 5.11" "Standards, Environments, and Macros" +.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(1M). Not all 802.11 devices will support all +statistics. +.sp +.ne 2 +.mk +.na +\fB\fBtx_frags\fR\fR +.ad +.RS 16n +.rt +Count of data and management fragments transmitted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrx_frags\fR\fR +.ad +.RS 16n +.rt +Count of data and management fragments received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrx_dups\fR\fR +.ad +.RS 16n +.rt +Count of duplicate frames received. Duplicates are determined by the sequence +control field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmcast_tx\fR\fR +.ad +.RS 16n +.rt +Count of broadcast and multicast frames transmitted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmcast_rx\fR\fR +.ad +.RS 16n +.rt +Count of broadcast and multicast frames received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtx_failed\fR\fR +.ad +.RS 16n +.rt +Count of frames that could not be transmitted due to the retransmission limit +being reached. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtx_retrans\fR\fR +.ad +.RS 16n +.rt +Count of frames successfully retransmitted after one or more retransmissions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtx_reretrans\fR\fR +.ad +.RS 16n +.rt +Count of frames successfully retransmitted after more than one retransmission. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrts_success\fR\fR +.ad +.RS 16n +.rt +Count of times a \fBCTS\fR was received in response to an \fBRTS\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrts_failure\fR\fR +.ad +.RS 16n +.rt + Count of times a \fBCTS\fR was not received in response to an \fBRTS\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBack_failure\fR\fR +.ad +.RS 16n +.rt +Count of times an \fBACK\fR was expected but was not received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfcs_errors\fR\fR +.ad +.RS 16n +.rt +Count of frames received with \fBFCS\fR errors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBwep_errors\fR\fR +.ad +.RS 16n +.rt +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 +\fBkstat\fR(1M) diff --git a/usr/src/man/man5/ipfilter.5 b/usr/src/man/man5/ipfilter.5 new file mode 100644 index 0000000000..cc5dc1722e --- /dev/null +++ b/usr/src/man/man5/ipfilter.5 @@ -0,0 +1,263 @@ +'\" 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. +.TH ipfilter 5 "20 May 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +ipfilter \- IP packet filtering software +.SH DESCRIPTION +.sp +.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(1M) for a procedure +to enable and activate the IP Filter feature. +.SH HOST-BASED FIREWALL +.sp +.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(1M) and \fBipf\fR(4). +.RE +.SS "Model" +.sp +.LP +This section describes the host-based firewall framework. See svc.ipfd(1M) for +details on how to configure firewall policies. +.sp +.LP +A three-layer approach with different precedence levels helps the user achieve +the desired behaviors. +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fBNone\fR +.ad +.sp .6 +.RS 4n +No firewall, allow all incoming traffic. +.RE + +.sp +.ne 2 +.mk +.na +\fBDeny\fR +.ad +.sp .6 +.RS 4n +Allow all incoming traffic but deny from specified source(s). +.RE + +.sp +.ne 2 +.mk +.na +\fBAllow\fR +.ad +.sp .6 +.RS 4n +Deny all incoming traffic but allow from specified source(s). +.RE + +.SS "Layers in Detail" +.sp +.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" +.sp +.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(1M) 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(1M)) +.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 +.RE +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBsvcs\fR(1), \fBipf\fR(1M), \fBipnat\fR(1M), \fBsvcadm\fR(1M), +\fBsvc.ipfd\fR(1M), \fBipf\fR(4), \fBipnat\fR(4), \fBattributes\fR(5), +\fBsmf\fR(5) +.sp +.LP +\fISystem Administration Guide: IP Services\fR +.SH NOTES +.sp +.LP +The \fBipfilter\fR service is managed by the service management facility, +\fBsmf\fR(5), 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(1M). 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/man5/isalist.5 b/usr/src/man/man5/isalist.5 new file mode 100644 index 0000000000..f32c5df9bc --- /dev/null +++ b/usr/src/man/man5/isalist.5 @@ -0,0 +1,261 @@ +'\" 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 5 "20 Mar 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB1a. \fBsparc\fR\fR +.ad +.RS 27n +.rt +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 +.mk +.na +\fB1b. \fBsparcv7\fR\fR +.ad +.RS 27n +.rt +Same as sparc. This corresponds to code produced with the -xarch=v7 option of +Sun's C 4.0 compiler. +.RE + +.sp +.ne 2 +.mk +.na +\fB2. \fBsparcv8-fsmuld\fR\fR +.ad +.RS 27n +.rt +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 +.mk +.na +\fB3. \fBsparcv8\fR\fR +.ad +.RS 27n +.rt +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 +.mk +.na +\fB4. \fBsparcv8plus\fR\fR +.ad +.RS 27n +.rt +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 +.mk +.na +\fB5a. \fBsparcv8plus+vis\fR\fR +.ad +.RS 27n +.rt +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 +.mk +.na +\fB5b. \fBsparcv8plus+fmuladd\fR\fR +.ad +.RS 27n +.rt +Like sparcv8plus, with the addition of the Fujitsu SPARC64 floating +multiply-add and multiply-subtract instructions. +.RE + +.sp +.ne 2 +.mk +.na +\fB6. \fBsparcv9\fR\fR +.ad +.RS 27n +.rt +Indicates the SPARC V9 instruction set, as defined in \fI\fR The SPARC +Architecture Manual, Version 9, Prentice-Hall, 1994. +.RE + +.sp +.ne 2 +.mk +.na +\fB7a. \fBsparcv9+vis\fR\fR +.ad +.RS 27n +.rt +Like sparcv9, with the addition of the UltraSPARC I Visualization Instructions. +.RE + +.sp +.ne 2 +.mk +.na +\fB7b. \fBsparcv9+vis2\fR\fR +.ad +.RS 27n +.rt +Like sparcv9, with the addition of the UltraSPARC III Visualization +Instructions. +.RE + +.sp +.ne 2 +.mk +.na +\fB7c. \fBsparcv9+fmuladd\fR\fR +.ad +.RS 27n +.rt +Like sparcv9, with the addition of the Fujitsu SPARC64 floating multiply-add +and multiply-subtract instructions. +.RE + +.SS "x86 Platforms" +.sp +.ne 2 +.mk +.na +\fB1. \fBi386\fR\fR +.ad +.RS 22n +.rt +The Intel 80386 instruction set, as described in \fI\fR The i386 Microprocessor +Programmer's Reference Manual. +.RE + +.sp +.ne 2 +.mk +.na +\fB2. \fBi486\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB3. \fBpentium\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB4. \fBpentium+mmx\fR\fR +.ad +.RS 22n +.rt +Like pentium, with the MMX instructions guaranteed present. +.RE + +.sp +.ne 2 +.mk +.na +\fB5. \fBpentium_pro\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB6. \fBpentium_pro+mmx\fR\fR +.ad +.RS 22n +.rt +Like pentium_pro, with the MMX instructions guaranteed present. +.RE + +.sp +.ne 2 +.mk +.na +\fB7. \fBamd64\fR\fR +.ad +.RS 22n +.rt +The AMD Opteron instruction set, as described in the \fIAMD64 Architecture +Programmer's Manual\fR. +.RE + +.SH SEE ALSO +.sp +.LP +\fBisalist\fR(1), \fBgetisax\fR(2), \fBsysinfo\fR(2) diff --git a/usr/src/man/man5/kerberos.5 b/usr/src/man/man5/kerberos.5 new file mode 100644 index 0000000000..fa89a9c7b9 --- /dev/null +++ b/usr/src/man/man5/kerberos.5 @@ -0,0 +1,170 @@ +'\" 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 kerberos 5 "1 Oct 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +kerberos \- overview of Solaris Kerberos implementation +.SH DESCRIPTION +.sp +.LP +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(5)). \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 +.mk +.na +\fBprimary\fR +.ad +.RS 12n +.rt +A user, a host, or a service. +.RE + +.sp +.ne 2 +.mk +.na +\fBinstance\fR +.ad +.RS 12n +.rt +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 +.mk +.na +\fBrealm\fR +.ad +.RS 12n +.rt +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 +.LP +\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.ACME.COM + joe/admin@ENG.ACME.COM + rlogin/bigmachine.eng.acme.com@ENG.ACME.COM + host/bigmachine.eng.acme.com@ENG.ACME.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\fRand \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 +.sp +.LP +\fBkdestroy\fR(1), \fBkinit\fR(1), \fBklist\fR(1), \fBkpasswd\fR(1), +\fBkrb5.conf\fR(4), \fBkrb5envvar\fR(5) +.sp +.LP +\fISystem Administration Guide: Security Services\fR +.SH NOTES +.sp +.LP +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/man5/krb5_auth_rules.5 b/usr/src/man/man5/krb5_auth_rules.5 new file mode 100644 index 0000000000..5c0a83949d --- /dev/null +++ b/usr/src/man/man5/krb5_auth_rules.5 @@ -0,0 +1,133 @@ +'\" 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 5 "07 Apr 2006" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +krb5_auth_rules \- overview of Kerberos V5 authorization +.SH DESCRIPTION +.sp +.LP +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.ACME.COM\fR and \fBjdb/happy.eng.acme.com@ENG.ACME.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 \fBgkadmin\fR(1M) and +\fBkadm5.acl\fR(4) 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(1M). +.sp +.LP +For example, an originating user listed in the \fBgsscred\fR table with the +principal name \fBjdb@ENG.ACME.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(4). +.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(4) \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.ACME.COM\fR and if the server is in realm \fBSALES.ACME.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.ACME.COM\fR and \fBENG.ACME.COM\fR +differ. +.sp +.LP +The \fBkrb5.conf\fR(4) \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 +.sp +.ne 2 +.mk +.na +\fB\fB~/.k5login\fR\fR +.ad +.RS 15n +.rt +Per user-account authorization file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/passwd\fR\fR +.ad +.RS 15n +.rt +System account file. This information may also be in a directory service. See +\fBpasswd\fR(4). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBftp\fR(1), \fBrcp\fR(1), \fBrdist\fR(1), \fBrlogin\fR(1), \fBrsh\fR(1), +\fBtelnet\fR(1), \fBgkadmin\fR(1M), \fBgsscred\fR(1M), \fBkadm5.acl\fR(4), +\fBkrb5.conf\fR(4), \fBpasswd\fR(4), \fBattributes\fR(5), +\fBgss_auth_rules\fR(5) diff --git a/usr/src/man/man5/krb5envvar.5 b/usr/src/man/man5/krb5envvar.5 new file mode 100644 index 0000000000..663683d3f3 --- /dev/null +++ b/usr/src/man/man5/krb5envvar.5 @@ -0,0 +1,233 @@ +'\" 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 5 "13 Feb 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.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(1M) 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 +.mk +.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 +.mk +.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(4)). +.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 +.mk +.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(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityUncommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBchmod\fR(1), \fBkinit\fR(1), \fBklist\fR(1), \fBksh\fR(1), \fBkadmin\fR(1M), +\fBkadmind\fR(1M), \fBkrb5.conf\fR(4), \fBattributes\fR(5), \fBkerberos\fR(5) diff --git a/usr/src/man/man5/largefile.5 b/usr/src/man/man5/largefile.5 new file mode 100644 index 0000000000..8fe19da99f --- /dev/null +++ b/usr/src/man/man5/largefile.5 @@ -0,0 +1,310 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved +.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures +.\" 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 5 "2 Nov 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +largefile \- large file status of utilities +.SH DESCRIPTION +.sp +.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" +.sp +.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. +.sp +.LP +The following \fB/usr/bin\fR utilities are large file aware: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\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 +\fBuudcode\fR\fBuuencode\fR\fBvacation\fR\fBwc\fR\fBzcat\fR +.TE + +.sp +.LP +The following \fB/usr/xpg4/bin\fR utilities are large file aware: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\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\fRsorttailtr +.TE + +.sp +.LP +The following \fB/usr/xpg6/bin\fR utilities are large file aware: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBgetconf\fR\fBls\fR\fBtr\fR +.TE + +.sp +.LP +The following \fB/usr/sbin\fR utilities are large file aware: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBeditmap\fR\fBinstall\fR\fBmakemap\fR\fBmkfile\fR\fBmknod\fR +\fBmvdir\fR\fBswap\fR +.TE + +.sp +.LP +The following \fB/usr/lib\fR utilities are large file aware: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBmail.local\fR\fBsendmail\fR\fBsmrsh\fR +.TE + +.sp +.LP +See the USAGE section of the \fBswap\fR(1M) 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 +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBchown\fR\fBfrom\fR\fBln\fR\fBls\fR\fBsed\fR +\fBsum\fR\fBtouch\fR +.TE + +.sp +.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. +.sp +.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 "cachefs file systems" +.sp +.LP +The following \fB/usr/bin\fR utilities are large file aware for \fBcachefs\fR +file systems: +.sp + +.sp +.TS +tab(); +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +. +\fBcachefspack\fR\fBcachefsstat\fR +.TE + +.sp +.LP +The following \fB/usr/sbin\fR utilities are large file aware for \fBcachefs\fR +file systems: +.sp + +.sp +.TS +tab(); +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +. +\fBcachefslog\fR\fBcachefswssize\fR\fBcfsadmin\fR\fBfsck\fR +\fBmount\fR\fBumount\fR +.TE + +.SS "nfs file systems" +.sp +.LP +The following utilities are large file aware for \fBnfs\fR file systems: +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fB/usr/lib/autofs/automountd\fR\fB/usr/sbin/mount\fR +\fB/usr/lib/nfs/rquotad\fR +.TE + +.SS "ufs file systems" +.sp +.LP +The following \fB/usr/bin\fR utility is large file aware for \fBufs\fR file +systems: +.sp +.LP +\fBdf\fR +.sp +.LP +The following \fB/usr/lib/nfs\fR utility is large file aware for \fBufs\fR file +systems: +.sp +.LP +\fBrquotad\fR +.sp +.LP +The following \fB/usr/xpg4/bin\fR utility is large file aware for \fBufs\fR +file systems: +.sp +.LP +\fBdf\fR +.sp +.LP +The following \fB/usr/sbin\fR utilities are large file aware for \fBufs\fR file +systems: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\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" +.sp +.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. +.sp +.LP +The following \fB/usr/bin\fR utilities are large file safe: +.sp + +.sp +.TS +tab(); +lw(1.36i) lw(1.04i) lw(1.21i) lw(1.11i) lw(.78i) +lw(1.36i) lw(1.04i) lw(1.21i) lw(1.11i) lw(.78i) +. +\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 + +.sp +.LP +The following \fB/usr/xpg4/bin\fR utilities are large file safe: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBed\fR\fBvi\fR\fBview\fR +.TE + +.sp +.LP +The following \fB/usr/xpg6/bin\fR utility is large file safe: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBed\fR +.TE + +.sp +.LP +The following \fB/usr/sbin\fR utilities are large file safe: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +lpfilter lpforms +.TE + +.sp +.LP +The following \fB/usr/ucb\fR utilities are large file safe: +.sp + +.sp +.TS +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\fBMail\fR\fBlpr\fR +.TE + +.SH SEE ALSO +.sp +.LP +\fBlf64\fR(5), \fBlfcompile\fR(5), \fBlfcompile64\fR(5) diff --git a/usr/src/man/man5/lf64.5 b/usr/src/man/man5/lf64.5 new file mode 100644 index 0000000000..c0344502df --- /dev/null +++ b/usr/src/man/man5/lf64.5 @@ -0,0 +1,460 @@ +'\" 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 lf64 5 "14 Jul 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +lf64 \- transitional interfaces for 64-bit file offsets +.SH DESCRIPTION +.sp +.LP +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(5) 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" +.sp +.LP +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +struct \fBaiocb\fRstruct \fBaiocb64\fR + \fBoff_t\fR aio_offset; \fBoff64_t\fR aio_offset; +.TE + +.SS "<\fBsys/dirent.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +struct \fBdirent\fRstruct \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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +struct \fBflock\fRstruct \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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +. +\fBfpos_t\fR\fBfpos64_t\fR +.TE + +.SS "<\fBsys/resource.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBrlim_t\fR\fBrlim64_t\fR +struct \fBrlimit\fRstruct \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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +struct \fBstat\fRstruct \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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +struct \fBstatvfs\fRstruct \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_bavial; \fBfsblkcnt64_t\fR f_bavial; + \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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fB_LFS64_LARGEFILE\fR +\fB_LFS64_STDIO\fR +.TE + +.SS "<\fBsys/unistd.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fB_CS_LFS64_CFLAGS\fR +\fB_CS_LFS64_LDFLAGS\fR +\fB_CS_LFS64_LIBS\fR +\fB_CS_LFS64_LINTFLAGS\fR +.TE + +.SS "System Interfaces" +.sp +.LP +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.74i) lw(2.76i) +lw(2.74i) lw(2.76i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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()\fRint \fBposix_fadvise64()\fR +int \fBposix_fallocate()\fRint \fBposix_fallocate64()\fR +.TE + +.SS "<\fBftw.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +. +char *\fBcopylist\fR(..., \fBoff_t\fR);char *\fBcopylist64\fR(..., \fBoff64_t\fR); +.TE + +.SS "<\fBstdio.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +. +int \fBmkstemp()\fR;int \fBmkstemp64()\fR; +.TE + +.SS "<\fBsys/async.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +int \fBgetdents\fR(..., \fBdirent\fR);int \fBgetdents64\fR(..., \fBdirent64\fR); + +.TE + +.SS "<\fBsys/mman.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +. +void \fBmmap\fR(..., \fBoff_t\fR);void \fBmmap64\fR(..., \fBoff64_t\fR); +.TE + +.SS "<\fBsys/resource.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +FILE *\fBfopen()\fRFILE *\fBfopen64()\fR +FILE *\fBfreopen()\fRFILE *\fBfreopen64()\fR +.TE + +.SS "<\fBucbinclude/sys/dir.h\fR>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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>" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +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); +int \fBtruncate\fR(..., \fBoff_t\fR);int \fBtruncate64\fR(..., \fBoff64_t\fR); +.TE + +.SH SEE ALSO +.sp +.LP +\fBlfcompile\fR(5), \fBlfcompile64\fR(5) diff --git a/usr/src/man/man5/lfcompile.5 b/usr/src/man/man5/lfcompile.5 new file mode 100644 index 0000000000..c6800eaea1 --- /dev/null +++ b/usr/src/man/man5/lfcompile.5 @@ -0,0 +1,217 @@ +'\" 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 5 "24 Aug 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) 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 +tab() box; +cw(1.68i) |cw(3.82i) +lw(1.68i) |lw(3.82i) +. +\fBargument\fR\fBpurpose\fR +_ +\fBLFS_CFLAGS\fRT{ +obtain compilation flags necessary to enable the large file compilation environment +T} +\fBLFS_LDFLAGS\fRobtain link editor options +\fBLFS_LIBS\fRobtain link library names +\fBLFS_LINTFLAGS\fRobtain 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(5)). +.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 +\fBcsh\fR(1), \fBgetconf\fR(1), \fBksh\fR(1), \fByacc\fR(1), \fBsh\fR(1), +\fBfseek\fR(3C), \fBftell\fR(3C), \fBlf64\fR(5), \fBlfcompile64\fR(5), +\fBstandards\fR(5) +.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/man5/lfcompile64.5 b/usr/src/man/man5/lfcompile64.5 new file mode 100644 index 0000000000..ed6ed11afd --- /dev/null +++ b/usr/src/man/man5/lfcompile64.5 @@ -0,0 +1,135 @@ +'\" 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 5 "26 Jan 1998" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) 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(5) 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(5)). +.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 +tab() box; +cw(1.67i) |cw(3.83i) +lw(1.67i) |lw(3.83i) +. +\fBargument\fR\fBpurpose\fR +_ +\fBLFS64_CFLAGS\fRT{ +obtain compilation flags necessary to enable the transitional compilation environment +T} +\fBLFS64_LDFLAGS\fRobtain link editor options +\fBLFS64_LIBS\fRobtain link library names +\fBLFS64_LINTFLAGS\fRobtain 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 +\fBgetconf\fR(1), \fBlseek\fR(2), \fBfopen\fR(3C), \fBlf64\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man5/locale.5 b/usr/src/man/man5/locale.5 new file mode 100644 index 0000000000..a87eba976a --- /dev/null +++ b/usr/src/man/man5/locale.5 @@ -0,0 +1,2683 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text +.\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" 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] +.TH locale 5 "1 Dec 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +locale \- subset of a user's environment that depends on language and cultural +conventions +.SH DESCRIPTION +.sp +.LP +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 +.mk +.na +\fB\fBLC_CTYPE\fR\fR +.ad +.RS 15n +.rt +Character classification and case conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLC_COLLATE\fR\fR +.ad +.RS 15n +.rt +Collation order. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLC_TIME\fR\fR +.ad +.RS 15n +.rt +Date and time formats. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLC_NUMERIC\fR\fR +.ad +.RS 15n +.rt +Numeric formatting. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLC_MONETARY\fR\fR +.ad +.RS 15n +.rt +Monetary formatting. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLC_MESSAGES\fR\fR +.ad +.RS 15n +.rt +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" +.sp +.LP +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" +.sp +.LP +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 +.mk +.na +\fB\fBupper\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBlower\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBalpha\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBdigit\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBalnum\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBspace\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBcntrl\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBpunct\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBgraph\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBprint\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBxdigit\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBblank\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBcharclass\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBcharclass-name\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBtoupper\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBtolower\fR\fR +.ad +.RS 18n +.rt +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" +.sp +.LP +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(5)), 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 explicity 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 +.mk +.na +\fB\fBcopy\fR\fR +.ad +.RS 21n +.rt +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 +.mk +.na +\fB\fBcollating-element\fR\fR +.ad +.RS 21n +.rt +Define a collating-element symbol representing a multi-character collating +element. This keyword is optional. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcollating-symbol\fR\fR +.ad +.RS 21n +.rt +Define a collating symbol for use in collation order statements. This keyword +is optional. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBorder_start\fR\fR +.ad +.RS 21n +.rt +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 +.mk +.na +\fB\fBorder_end\fR\fR +.ad +.RS 21n +.rt +Specify the end of the collation-order statements. +.RE + +.SS "collating-element \fIkeyword\fR" +.sp +.LP +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" +.sp +.LP +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" +.sp +.LP +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 +.mk +.na +\fB\fBforward\fR\fR +.ad +.RS 12n +.rt +Specifies that comparison operations for the weight level proceed from start of +string towards the end of string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbackward\fR\fR +.ad +.RS 12n +.rt +Specifies that comparison operations for the weight level proceed from end of +string towards the beginning of string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBposition\fR\fR +.ad +.RS 12n +.rt +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" +.sp +.LP +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 beween 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 +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\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" +.sp +.LP +The collating order entries must be terminated with an \fBorder_end\fR keyword. +.SS "LC_MONETARY" +.sp +.LP +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 +.mk +.na +\fB\fBint_curr_symbol\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBcurrency_symbol\fR\fR +.ad +.RS 22n +.rt +The string used as the local currency symbol. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmon_decimal_point\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBmon_thousands_sep\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBmon_grouping\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBpositive_sign\fR\fR +.ad +.RS 22n +.rt +A string used to indicate a non-negative-valued formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnegative_sign\fR\fR +.ad +.RS 22n +.rt +A string used to indicate a negative-valued formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBint_frac_digits\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBfrac_digits\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBp_cs_precedes\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBp_sep_by_space\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBn_cs_precedes\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBn_sep_by_space\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBp_sign_posn\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Parentheses enclose the quantity and the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the quantity and the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB2\fR\fR +.ad +.RS 5n +.rt +The sign string succeeds the quantity and the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB3\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the \fBcurrency_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB4\fR\fR +.ad +.RS 5n +.rt +The sign string succeeds the \fBcurrency_symbol\fR. +.RE + +In an application \fBnot\fR conforming to the SUSv3 standard: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Parentheses enclose the quantity and the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the quantity and the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB2\fR\fR +.ad +.RS 5n +.rt +The sign string succeeds the quantity and the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB3\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the \fBcurrency_symbol\fR or \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB4\fR\fR +.ad +.RS 5n +.rt +The sign string succeeds the \fBcurrency_symbol\fR or \fBint_curr_symbol\fR. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn_sign_posn\fR\fR +.ad +.RS 22n +.rt +An integer set to a value indicating the positioning of the \fBnegative_sign\fR +for a negative formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBint_p_cs_precedes\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBint_n_cs_precedes\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBint_p_sep_by_space\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBint_n_sep_by_space\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fBint_p_sign_posn\fR\fR +.ad +.RS 22n +.rt +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 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Parentheses enclose the quantity and the \fB\fR\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the quantity and the \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB2\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the quantity and the \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB3\fR\fR +.ad +.RS 5n +.rt +The sign string precedes the \fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB4\fR\fR +.ad +.RS 5n +.rt +The sign string succeeds the \fBint_curr_symbol\fR. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBint_n_sign_posn\fR\fR +.ad +.RS 22n +.rt +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 +tab(); +lw(1.48i) lw(1.48i) lw(.8i) lw(.8i) lw(.8i) lw(.13i) +lw(1.48i) lw(1.48i) lw(.8i) lw(.8i) lw(.8i) lw(.13i) +. +\fBp_sep_by_space\fR +210 +\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" +.sp +.LP +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 +.mk +.na +\fB\fBdecimal_point\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBthousands_sep\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBgrouping\fR\fR +.ad +.RS 17n +.rt +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 +tab(); +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +lw(1.1i) lw(1.1i) lw(1.1i) lw(1.1i) lw(1.11i) +. +\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" +.sp +.LP +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 +.mk +.na +\fB\fBabday\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBday\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBabmon\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBmon\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBd_t_fmt\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBdate_fmt\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBd_fmt\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBt_fmt\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBam_pm\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBt_fmt_ampm\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBera\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fIdirection\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIstart_date\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIend_date\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIera_name\fR\fR +.ad +.RS 14n +.rt +A string representing the name of the era, corresponding to the \fB%EC\fR field +descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIera_format\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fBera_d_fmt\fR\fR +.ad +.RS 15n +.rt +Define the format of the date in alternative era notation, corresponding to the +\fB%Ex\fR field descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBera_t_fmt\fR\fR +.ad +.RS 15n +.rt +Define the locale's appropriate alternative time format, corresponding to the +\fB%EX\fR field descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBera_d_t_fmt\fR\fR +.ad +.RS 15n +.rt +Define the locale's appropriate alternative date and time format, corresponding +to the \fB%Ec\fR field descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBalt_digits\fR\fR +.ad +.RS 15n +.rt +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" +.sp +.LP +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 +.mk +.na +\fB\fBABDAY_\fIx\fR\fR\fR +.ad +.RS 15n +.rt +The abbreviated weekday names (for example Sun), where \fIx\fR is a number from +1 to 7. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDAY_\fIx\fR\fR\fR +.ad +.RS 15n +.rt +The full weekday names (for example Sunday), where \fIx\fR is a number from 1 +to 7. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBABMON_\fIx\fR\fR\fR +.ad +.RS 15n +.rt +The abbreviated month names (for example Jan), where \fIx\fR is a number from 1 +to 12. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMON_\fIx\fR\fR\fR +.ad +.RS 15n +.rt +The full month names (for example January), where \fIx\fR is a number from 1 to +12. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBD_T_FMT\fR\fR +.ad +.RS 15n +.rt +The appropriate date and time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBD_FMT\fR\fR +.ad +.RS 15n +.rt +The appropriate date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_FMT\fR\fR +.ad +.RS 15n +.rt +The appropriate time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAM_STR\fR\fR +.ad +.RS 15n +.rt +The appropriate ante-meridiem affix. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPM_STR\fR\fR +.ad +.RS 15n +.rt +The appropriate post-meridiem affix. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_FMT_AMPM\fR\fR +.ad +.RS 15n +.rt +The appropriate time representation in the 12-hour clock format with +\fBAM_STR\fR and \fBPM_STR.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERA\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fIdirection\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 14n +.rt +The number of the year closest to the start_date in the era. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstart_date\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIend_date\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fIera_name\fR\fR +.ad +.RS 14n +.rt +The era, corresponding to the \fB%EC\fR conversion specification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIera_format\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fBERA_D_FMT\fR\fR +.ad +.RS 15n +.rt +The era date format. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERA_T_FMT\fR\fR +.ad +.RS 15n +.rt +The locale's appropriate alternative time format, corresponding to the +\fB%EX\fR field descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERA_D_T_FMT\fR\fR +.ad +.RS 15n +.rt +The locale's appropriate alternative date and time format, corresponding to the +\fB%Ec\fR field descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBALT_DIGITS\fR\fR +.ad +.RS 15n +.rt +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 +tab() box; +cw(1.83i) |cw(1.83i) |cw(1.83i) +cw(1.83i) |cw(1.83i) |cw(1.83i) +. +\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" +.sp +.LP +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" +.sp +.LP +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 +.mk +.na +\fB\fByesexpr\fR\fR +.ad +.RS 11n +.rt +The operand consists of an extended regular expression (see \fBregex\fR(5)) +that describes the acceptable affirmative response to a question expecting an +affirmative or negative response. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnoexpr\fR\fR +.ad +.RS 11n +.rt +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 +.mk +.na +\fB\fByesstr\fR\fR +.ad +.RS 11n +.rt +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 +.mk +.na +\fB\fBnostr\fR\fR +.ad +.RS 11n +.rt +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 +tab() box; +lw(1.83i) |lw(1.83i) |lw(1.83i) +lw(1.83i) |lw(1.83i) |lw(1.83i) +. +\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 +.sp +.LP +\fBdate\fR(1), \fBlocale\fR(1), \fBlocaledef\fR(1), \fBsort\fR(1), \fBtr\fR(1), +\fBuniq\fR(1), \fBlocaleconv\fR(3C), \fBnl_langinfo\fR(3C), +\fBsetlocale\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C), \fBstrptime\fR(3C), +\fBstrxfrm\fR(3C), \fBwcscoll\fR(3C), \fBwcsftime\fR(3C), \fBwcsxfrm\fR(3C), +\fBwctype\fR(3C), \fBattributes\fR(5), \fBcharmap\fR(5), \fBextensions\fR(5), +\fBregex\fR(5) diff --git a/usr/src/man/man5/man.5 b/usr/src/man/man5/man.5 new file mode 100644 index 0000000000..f01d87b15d --- /dev/null +++ b/usr/src/man/man5/man.5 @@ -0,0 +1,383 @@ +'\" te +.\" 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] +.TH man 5 "30 Jan 1995" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +man \- macros to format Reference Manual pages +.SH SYNOPSIS +.LP +.nf +\fBnroff\fR \fB-man\fR \fIfilename\fR... +.fi + +.LP +.nf +\fBtroff\fR \fB-man\fR \fIfilename\fR... +.fi + +.SH DESCRIPTION +.sp +.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 the \fBman\fR(1) command. 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-man\fR: +.sp +.ne 2 +.mk +.na +\fB\fB\e*R\fR\fR +.ad +.RS 8n +.rt +`\(rg', `(Reg)' in \fBnroff\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\e*S\fR\fR +.ad +.RS 8n +.rt +Change to default type size. +.RE + +.SS "Requests" +.sp +.LP +* n.t.l. = next text line; p.i. = prevailing indent +.sp + +.sp +.TS +tab(); +cw(1i) cw(1i) cw(1i) cw(2.5i) +cw(1i) cw(1i) cw(1i) cw(2.5i) +. +\fIRequest\fR\fICause\fR\fIIf no\fR\fIExplanation\fR +\fIBreak\fR\fIArgument\fR +\fB\&.B \fR\fIt\fRno\fIt\fR=n.t.l.*Text is in bold font. +\fB\&.BI \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating bold and italic. +\fB\&.BR \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating bold and roman. +\fB\&.DT\fRno\&.5i 1i...Restore default tabs. +\fB\&.HP \fR\fIi\fRyes\fIi\fR=p.i.*T{ +Begin paragraph with hanging indent. Set prevailing indent to \fIi\fR. +T} +\fB\&.I \fR\fIt\fRno\fIt\fR=n.t.l.Text is italic. +\fB\&.IB \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating italic and bold. +\fB\&.IP \fR\fIx i\fRyes\fIx\fR=""Same as \fB\&.TP\fR with tag \fIx\fR. +\fB\&.IR \fR\fIt\fRno\fIt\fR=n.t.l.T{ +Join words, alternating italic and roman. +T} +\fB\&.IX \fR\fIt\fRno-Index macro, for SunSoft internal use. +\fB\&.LP\fRyes-T{ +Begin left-aligned paragraph. Set prevailing indent to .5i. +T} +\fB\&.P\fRyes-Same as \fB\&.LP\fR. +\fB\&.PD \fR\fId\fRno\fId\fR=.4vT{ +Set vertical distance between paragraphs. +T} +\fB\&.PP\fRyes-Same as \fB\&.LP\fR. +\fB\&.RE\fRyes-T{ +End of relative indent. Restores prevailing indent. +T} +\fB\&.RB \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating roman and bold. +\fB\&.RI \fR\fIt\fRno\fIt\fR=n.t.l.T{ +Join words, alternating roman and italic. +T} +\fB\&.RS \fR\fIi\fRyes\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\fRno-T{ +Reduce size of text by 1 point, make text bold. +T} +\fB\&.SH \fR\fIt\fRyes-Section Heading. +\fB\&.SM \fR\fIt\fRno\fIt\fR=n.t.l.Reduce size of text by 1 point. +\fB\&.SS \fR\fIt\fRyes\fIt\fR=n.t.l.Section Subheading. +\fB\&.TH \fR\fIn s d f m\fRyes-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\fRyes\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\fRno-T{ +Resolve the title abbreviation \fIt\fR; join to punctuation mark (or text) \fIp\fR. +T} +.TE + +.SS "Conventions" +.sp +.LP +When formatting a manual page, \fBman\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 +.mk +.na +\fB\&.TH\fI title \fR[1-9]\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\&.SH NAME\fR +.ad +.RS 23n +.rt +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 \fBwindex\fR database, which is used by the +\fBwhatis\fR(1) command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH SYNOPSIS\fR +.ad +.RS 23n +.rt +.sp +.ne 2 +.mk +.na +\fBCommands:\fR +.ad +.RS 13n +.rt +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 +.mk +.na +\fB[ ]\fR +.ad +.RS 13n +.rt +An argument, when surrounded by brackets is optional. +.RE + +.sp +.ne 2 +.mk +.na +\fB|\fR +.ad +.RS 13n +.rt +Arguments separated by a vertical bar are exclusive. You can supply only one +item from such a list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.\|.\|.\fR +.ad +.RS 13n +.rt +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 +.mk +.na +\fBFunctions:\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\&.SH DESCRIPTION\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\&.SH OPTIONS\fR +.ad +.RS 23n +.rt +The list of options along with a description of how each affects the command's +operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH RETURN VALUES\fR +.ad +.RS 23n +.rt +A list of the values the library routine will return to the calling program +and the conditions that cause these values to be returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH EXIT STATUS\fR +.ad +.RS 23n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH FILES\fR +.ad +.RS 23n +.rt +A list of files associated with the command or function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH SEE ALSO\fR +.ad +.RS 23n +.rt +A comma-separated list of related manual pages, followed by references to other +published materials. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH DIAGNOSTICS\fR +.ad +.RS 23n +.rt +A list of diagnostic messages and an explanation of each. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH BUGS\fR +.ad +.RS 23n +.rt +A description of limitations, known defects, and possible problems associated +with the command or function. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/tmac/an\fR \fR +.ad +.RS 27n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/man/windex\fR\fR +.ad +.RS 27n +.rt + +.RE + +.SH SEE ALSO +.sp +.LP +\fBman\fR(1), \fBnroff\fR(1), \fBtroff\fR(1), \fBwhatis\fR(1) +.sp +.LP +Dale Dougherty and Tim O'Reilly, \fIUnix\fR \fIText\fR \fIProcessing\fR diff --git a/usr/src/man/man5/mansun.5 b/usr/src/man/man5/mansun.5 new file mode 100644 index 0000000000..dc10a29cc3 --- /dev/null +++ b/usr/src/man/man5/mansun.5 @@ -0,0 +1,360 @@ +'\" 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 mansun 5 "11 Jun 1992" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.sp +.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 +.mk +.na +\fB\fB\e*R\fR\fR +.ad +.RS 8n +.rt +`\(rg', `(Reg)' in \fBnroff\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\e*S\fR\fR +.ad +.RS 8n +.rt +Change to default type size. +.RE + +.SS "Requests" +.sp +.LP +* n.t.l. = next text line; p.i. = prevailing indent +.sp + +.sp +.TS +tab(); +cw(1i) cw(1i) cw(1i) cw(2.5i) +cw(1i) cw(1i) cw(1i) cw(2.5i) +. +\fIRequest\fR\fICause\fR\fIIf no\fR\fIExplanation\fR +\fIBreak\fR\fIArgument\fR +\fB\&.B \fR\fIt\fRno\fIt\fR=n.t.l.*Text is in bold font. +\fB\&.BI \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating bold and italic. +\fB\&.BR \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating bold and Roman. +\fB\&.DT\fRno\&.5i 1i...Restore default tabs. +\fB\&.HP \fR\fIi\fRyes\fIi\fR=p.i.*T{ +Begin paragraph with hanging indent. Set prevailing indent to \fIi\fR. +T} +\fB\&.I \fR\fIt\fRno\fIt\fR=n.t.l.Text is italic. +\fB\&.IB \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating italic and bold. +\fB\&.IP \fR\fIx i\fRyes\fIx\fR=""Same as \fB\&.TP\fR with tag \fIx\fR. +\fB\&.IR \fR\fIt\fRno\fIt\fR=n.t.l.T{ +Join words, alternating italic and Roman. +T} +\fB\&.IX \fR\fIt\fRno-Index macro, for SunSoft internal use. +\fB\&.LP\fRyes-T{ +Begin left-aligned paragraph. Set prevailing indent to .5i. +T} +\fB\&.P\fRyes-Same as \fB\&.LP\fR. +\fB\&.PD \fR\fId\fRno\fId\fR=.4vT{ +Set vertical distance between paragraphs. +T} +\fB\&.PP\fRyes-Same as \fB\&.LP\fR. +\fB\&.RE\fRyes-T{ +End of relative indent. Restores prevailing indent. +T} +\fB\&.RB \fR\fIt\fRno\fIt\fR=n.t.l.Join words, alternating Roman and bold. +\fB\&.RI \fR\fIt\fRno\fIt\fR=n.t.l.T{ +Join words, alternating Roman and italic. +T} +\fB\&.RS \fR\fIi\fRyes\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\fRno-T{ +Reduce size of text by 1 point, make text bold. +T} +\fB\&.SH \fR\fIt\fRyes-Section Heading. +\fB\&.SM \fR\fIt\fRno\fIt\fR=n.t.l.Reduce size of text by 1 point. +\fB\&.SS \fR\fIt\fRyes\fIt\fR=n.t.l.Section Subheading. +\fB\&.TH \fR\fIn s d f m\fRyes-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\fRyes\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\fRno-T{ +Resolve the title abbreviation \fIt\fR; join to punctuation mark (or text) \fIp\fR. +T} +.TE + +.SS "Conventions" +.sp +.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 +.mk +.na +\fB\&.TH\fI title \fR[1-8]\fR +.ad +.RS 21n +.rt +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 +.mk +.na +\fB\&.SH NAME\fR +.ad +.RS 21n +.rt +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 \fBwindex\fR database, which is used by the +\fBwhatis\fR(1) command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH SYNOPSIS\fR +.ad +.RS 21n +.rt +.sp +.ne 2 +.mk +.na +\fBCommands:\fR +.ad +.RS 13n +.rt +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 +.mk +.na +\fB[ ]\fR +.ad +.RS 13n +.rt +An argument, when surrounded by brackets is optional. +.RE + +.sp +.ne 2 +.mk +.na +\fB|\fR +.ad +.RS 13n +.rt +Arguments separated by a vertical bar are exclusive. You can supply only one +item from such a list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.\|.\|.\fR +.ad +.RS 13n +.rt +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 +.mk +.na +\fBFunctions:\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\&.SH DESCRIPTION\fR +.ad +.RS 21n +.rt +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 +.mk +.na +\fB\&.SH OPTIONS\fR +.ad +.RS 21n +.rt +The list of options along with a description of how each affects the command's +operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH FILES\fR +.ad +.RS 21n +.rt +A list of files associated with the command or function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH SEE ALSO\fR +.ad +.RS 21n +.rt +A comma-separated list of related manual pages, followed by references to other +published materials. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH DIAGNOSTICS\fR +.ad +.RS 21n +.rt +A list of diagnostic messages and an explanation of each. +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.SH BUGS\fR +.ad +.RS 21n +.rt +A description of limitations, known defects, and possible problems associated +with the command or function. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/tmac/ansun\fR\fR +.ad +.RS 29n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/man/windex\fR\fR +.ad +.RS 29n +.rt + +.RE + +.SH SEE ALSO +.sp +.LP +\fBman\fR(1), \fBnroff\fR(1), \fBtroff\fR(1), \fBwhatis\fR(1) +.sp +.LP +Dale Dougherty and Tim O'Reilly, \fIUnix\fR \fIText\fR \fIProcessing\fR diff --git a/usr/src/man/man5/me.5 b/usr/src/man/man5/me.5 new file mode 100644 index 0000000000..cc0df6e406 --- /dev/null +++ b/usr/src/man/man5/me.5 @@ -0,0 +1,264 @@ +'\" 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 5 "25 Feb 1992" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\&.bp\fR +.ad +.RS 12n +.rt +begin new page +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.br\fR +.ad +.RS 12n +.rt +break output line here +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.sp \fIn\fR\fR +.ad +.RS 12n +.rt +insert \fIn\fR spacing lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.ls \fIn\fR\fR +.ad +.RS 12n +.rt +(line spacing) \fIn\fR=1 single, \fIn\fR=2 double space +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.na\fR +.ad +.RS 12n +.rt +no alignment of right margin +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.ce \fIn\fR\fR +.ad +.RS 12n +.rt +center next \fIn\fR lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.ul \fIn\fR\fR +.ad +.RS 12n +.rt +underline next \fIn\fR lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\&.sz \fI+n\fR\fR +.ad +.RS 12n +.rt +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 +tab(); +cw(.83i) cw(.67i) cw(.67i) cw(3.33i) +cw(.83i) cw(.67i) cw(.67i) cw(3.33i) +. +\fIRequest\fR\fIInitial\fR\fICause\fR\fIExplanation\fR +\fIValue\fR\fIBreak\fR +\fB\&.(c\fR-yesBegin centered block. +\fB\&.(d\fR-noBegin delayed text. +\fB\&.(f\fR-noBegin footnote. +\fB\&.(l\fR-yesBegin list. +\fB\&.(q\fR-yesBegin major quote. +\fB\&.(x\fR\fIx\fR -noBegin indexed item in index \fIx\fR. +\fB\&.(z\fR-noBegin floating keep. +\fB\&.)c\fR-yesEnd centered block. +\fB\&.)d\fR-yesEnd delayed text. +\fB\&.)f\fR-yesEnd footnote. +\fB\&.)l\fR-yesEnd list. +\fB\&.)q\fR-yesEnd major quote. +\fB\&.)x\fR-yesEnd index item. +\fB\&.)z\fR-yesEnd floating keep. +\fB\&.++\fR \fIm H\fR -noDefine 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 -yesBegin chapter (or appendix, etc., +as set by \fB\&.++\fR). \fIT\fR is +the chapter title. +\fB\&.1c\fR1yesOne column format on a new page. +\fB\&.2c\fR1yesTwo column format. +\fB\&.EN\fR-yesSpace after equation produced by \fBeqn\fR +or \fBneqn\fR. +\fB\&.EQ\fR \fIx y\fR -yesPrecede 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-yesEnd \fIgremlin\fR picture. +\fB\&.GS\fR-yesBegin \fIgremlin\fR picture. +\fB\&.PE\fR-yesEnd \fBpic\fR picture. +\fB\&.PS\fR-yesBegin \fBpic\fR picture. +\fB\&.TE\fR-yesEnd table. +\fB\&.TH\fR-yesEnd heading section of table. +\fB\&.TS\fR \fIx\fR-yesBegin table; if \fIx\fR is \fIH\fR table +has repeated heading. +\fB\&.ac\fR \fIA N\fR -noSet 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 nonoPrint \fIx\fR in boldface; if no argument +switch to boldface. +\fB\&.ba\fR \fI+n\fR 0yesAugments the base indent by \fIn\fR. +This indent is used to set the indent +on regular text (like paragraphs). +\fB\&.bc\fRnoyesBegin new column. +\fB\&.bi\fR \fIx\fR nonoPrint \fIx\fR in bold italics +(nofill only). +\fB\&.bu\fR-yesBegin bulleted paragraph. +\fB\&.bx\fR \fIx\fRnonoPrint \fIx\fR in a box (nofill only). +\fB\&.ef\fR \fI\&'x'y'z\fR\&'''''noSet even footer to \fIx y z\fR. +\fB\&.eh\fR \fI\&'x'y'z\fR\&'''''noSet even header to \fIx y z\fR. +\fB\&.fo\fR \fI\&'x'y'z\fR\&'''''noSet footer to \fIx y z\fR. +\fB\&.hx\fR-noSuppress headers and footers on +next page. +\fB\&.he\fR \fI\&'x'y'z\fR\&'''''noSet header to \fIx y z\fR. +\fB\&.hl\fR-yesDraw a horizontal line. +\fB\&.i\fR \fIx\fR nonoItalicize \fIx\fR; if \fIx\fR missing, italic +text follows. +\fB\&.ip\fR \fIx y\fR noyesStart indented paragraph, with +hanging tag \fIx\fR. Indentation is +\fIy\fR ens (default 5). +\fB\&.lp\fRyesyesStart left-blocked paragraph. +\fB\&.lo\fR-noRead in a file of local macros +of the form \fB\&.*\fR\fIx.\fR Must be +given before initialization. +\fB\&.np\fR1yesStart numbered paragraph. +\fB\&.of\fR \fI\&'x'y'z\fR\&'''''noSet odd footer to x y z. +\fB\&.oh\fR \fI\&'x'y'z\fR\&'''''noSet odd header to x y z. +\fB\&.pd\fR-yesPrint delayed text. +\fB\&.pp\fRnoyesBegin paragraph. First line indented. +\fB\&.r\fRyesnoRoman text follows. +\fB\&.re\fR-noReset tabs to default values. +\fB\&.sc\fRnonoRead in a file of special characters +and diacritical marks. Must be +given before initialization. +\fB\&.sh\fR \fIn x\fR -yesSection head follows, font +automatically bold. \fIn\fR is level +of section, \fIx\fR is title of section. +\fB\&.sk\fRnonoLeave the next page blank. +Only one page is remembered ahead. +\fB\&.sm\fR \fIx\fR-noSet \fIx\fR in a smaller pointsize. +\fB\&.sz\fR \fI+n\fR 10pnoAugment the point size by \fIn\fR points. +\fB\&.th\fRnonoProduce the paper in thesis format. +Must be given before initialization. +\fB\&.tp\fRnoyesBegin title page. +\fB\&.u\fR \fIx\fR-noUnderline argument (even in \fBtroff\fR). +(Nofill only). +\fB\&.uh\fR-yesLike \fB\&.sh\fR but unnumbered. +\fB\&.xp\fR \fIx\fR -noPrint index \fIx\fR. +.TE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/tmac/e\fR\fR +.ad +.RS 28n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/tmac/*.me\fR\fR +.ad +.RS 28n +.rt + +.RE + +.SH SEE ALSO +.sp +.LP +\fBcol\fR(1), \fBeqn\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), +\fBtroff\fR(1) diff --git a/usr/src/man/man5/mech_spnego.5 b/usr/src/man/man5/mech_spnego.5 new file mode 100644 index 0000000000..03587dc8a3 --- /dev/null +++ b/usr/src/man/man5/mech_spnego.5 @@ -0,0 +1,123 @@ +'\" 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 5 "4 Oct 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4)), 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 +.mk +.na +\fB\fB/usr/lib/gss/mech_spnego.so.1\fR\fR +.ad +.sp .6 +.RS 4n +shared object file +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBlibgss\fR(3LIB), \fBmech\fR(4), \fBattributes\fR(5) +.sp +.LP +\fISolaris Security for Developers Guide\fR diff --git a/usr/src/man/man5/mm.5 b/usr/src/man/man5/mm.5 new file mode 100644 index 0000000000..1566c9f7af --- /dev/null +++ b/usr/src/man/man5/mm.5 @@ -0,0 +1,461 @@ +'\" 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 5 "1 Jan 1997" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fB\&.bp\fR\fR +.ad +.RS 11n +.rt +begin new page +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.br\fR \fR +.ad +.RS 11n +.rt +break output line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.sp\fR\fIn\fR \fR +.ad +.RS 11n +.rt +insert n spacing lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.ce\fR\fIn\fR \fR +.ad +.RS 11n +.rt +center next n lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.ls\fR\fIn\fR \fR +.ad +.RS 11n +.rt +line spacing: \fIn\fR\fB=1\fR single, \fIn\fR\fB=2\fR double space +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.na\fR \fR +.ad +.RS 11n +.rt +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 +tab(); +cw(1.47i) |cw(1.1i) |cw(.74i) |cw(2.19i) +lw(1.47i) |lw(1.1i) |lw(.74i) |lw(2.19i) +. +Macro NameInitial ValueBreak? Reset?Explanation +_ +\fB\&.1C\fRony,yone column format on a new page +_ +\fB\&.2C\fR [ \fIl\fR ]-y,ytwo column format \fIl\fR=line length +_ +\fB\&.AE\fR-yend abstract +_ +\fB\&.AL\fR [ \fIt\fR ] [ \fIi\fR ] [ \fIs\fR ]\fIt\fR=\fB1\fR;\fIi\fR=\fB\&.Li\fR;\fIs\fR=\fB0\fRyT{ +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\fRybegin abstract +_ +\fB\&.AU\fR-yauthor's name +_ +\fB\&.AV\fR \fIx\fR-ysignature and date line of verifier \fIx\fR +_ +\fB\&.B\fR \fIx\fR-nembolden \fIx\fR; if no \fIx\fR, switch to boldface +_ +\fB\&.BE\fR-yend block text +_ +\fB\&.BI\fR \fIx\fR \fIy\fR-nembolden \fIx\fR and underline \fIy\fR +_ +\fB\&.BL\fR-ybullet list +_ +\fB\&.BR\fR \fIx\fR \fIy\fR-nembolden \fIx\fR and use Roman font for \fIy\fR +_ +\fB\&.BS\fR-nstart block text +_ +\fB\&.CN\fR-ysame as \fB\&.DE\fR (\fBnroff\fR) +_ +\fB\&.CS\fR-ycover sheet +_ +\fB\&.CW\fR-nsame as \fB\&.DS I\fR (\fBnroff\fR) +_ +\fB\&.DE\fR-yend display +_ +\fB\&.DF\fR [ \fIp\fR ] [ \fIf\fR ] [ \fIrp\fR ]\fIp\fR=\fBL\fR;\fIf\fR=\fBN\fRyT{ +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 ]-ystart dash list +_ +\fB\&.DS\fR [ \fIp\fR ] [ \fIf\fR ] [ \fIrp\fR ]\fIp\fR=\fBL\fR;\fIf\fR=\fBN\fRyT{ +begin static display (see \fB\&.DF\fR for argument descriptions) +T} +_ +\fB\&.EC\fR \fIx\fR [ \fIn\fR ]\fIn\fR=\fB1\fRyequation title; equation \fIx\fR; number \fIn\fR +_ +\fB\&.EF\fR \fIx\fR-nT{ +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-nT{ +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-yend displayed equation produced by \fBeqn\fR +_ +\fB\&.EQ\fR-ybreak out equation produced by \fBeqn\fR +_ +\fB\&.EX\fR \fIx\fR [ \fIn\fR ]\fIn\fR=\fB1\fRyexhibit title; exhibit \fIx\fR +_ +number \fIn\fR +_ +\fB\&.FD\fR [ \fIf\fR ] [ \fIr\fR ]\fIf\fR=\fB10\fR;\fIr\fR=\fB1\fRnT{ +set footnote style format \fIf\fR=[\fB0-11\fR]; renumber \fIr\fR=[\fB0\fR,\fB1\fR] +T} +_ +\fB\&.FE\fR-yend footnote +_ +\fB\&.FG\fR \fIx\fR [ \fIn\fR ]\fIn\fR=\fB1\fRyfigure title; figure \fIx\fR; number \fIn\fR +_ +\fB\&.FS\fR-nstart footnote +_ +\fB\&.H\fR \fIl\fR [ \fIt\fR ]-yT{ +produce numbered heading level \fIl\fR=[\fB1-7\fR]; title \fIt\fR +T} +_ +\fB\&.HU\fR \fIt\fR-yproduce unnumbered heading; title \fIt\fR +_ +\fB\&.I\fR \fIx\fR-nunderline \fIx\fR +_ +\fB\&.IB\fR \fIx\fR \fIy\fR-nunderline \fIx\fR and embolden \fIy\fR +_ +\fB\&.IR\fR \fIx\fR \fIy\fR-nunderline \fIx\fR and use Roman font on \fIy\fR +_ +\fB\&.LE\fR [ \fIs\fR ]\fIs\fR=\fB0\fRyend list; separation \fIs\fR +_ +\fB\&.LI\fR [ \fIm\fR ] [ \fIp\fR ]-ystart new list item; mark \fIm\fR +_ +prefix \fIp\fR (mark only) +_ +\fB\&.ML\fR \fIm\fR [ \fIi\fR ] [ \fIs\fR ]\fIs\fR=\fB0\fRyT{ +start marked list; mark \fIm\fR indentation \fIi\fR; separation \fIs\fR=[\fB0\fR,\fB1\fR] +T} +_ +\fB\&.MT\fR \fIx\fRymemo title; title \fIx\fR +_ +\fB\&.ND\fR \fIx\fRnT{ +no date in page footer; \fIx\fR is date on cover +T} +_ +\fB\&.NE\fR-yend block text +_ +\fB\&.NS\fR-ystart block text +_ +\fB\&.OF\fR \fIx\fR-nT{ +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-nT{ +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-yskip to the top of an odd-number page +_ +\fB\&.P\fR [ \fIt\fR ]\fIt\fR=\fB0\fRy,yT{ +begin paragraph; \fIt\fR=[\fB0\fR,\fB1\fR] \fB0\fR=justified; \fB1\fR=indented +T} +_ +\fB\&.PF\fR \fIx\fR-nT{ +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-nT{ +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\fRonnreturn to Roman font +_ +\fB\&.RB\fR \fIx\fR \fIy\fR-nuse Roman on \fIx\fR and embolden \fIy\fR +_ +\fB\&.RI\fR \fIx\fR \fIy\fR-nuse Roman on \fIx\fR and underline \fIy\fR +_ +\fB\&.RP\fR \fIx\fR-y,yT{ +released paper format ? \fIx\fR=no stops title on first +T} +_ +\fB\&.RS\fR5ny,yT{ +right shift: start level of relative indentation +T} +_ +\fB\&.S\fR \fIm\fR \fIn\fR-nT{ +set character point size & vertical space character point size \fIm\fR; vertical space \fIn\fR +T} +_ +\fB\&.SA\fR \fIx\fR\fIx\fR=\fB1\fRnjustification; \fIx\fR=[\fB0\fR,\fB1\fR] +_ +\fB\&.SK\fR \fIx\fR-yskip \fIx\fR pages +_ +\fB\&.SM\fR -nsmaller; decrease point size by 2 +_ +\fB\&.SP\fR [ \fIx\fR ]-yleave \fIx\fR blank lines +_ +\fB\&.TB\fR \fIx\fR [ \fIn\fR ]\fIn\fR=\fB1\fRytable title; table \fIx\fR; number \fIn\fR +_ +\fB\&.TC\fR-yT{ +print table of contents (put at end of input file) +T} +_ +\fB\&.TE\fR-yend of table processed by tbl +_ +\fB\&.TH\fR-yend multi-page header of table +_ +\fB\&.TL\fR-ntitle in boldface and two points larger +_ +\fB\&.TM\fR-nUC Berkeley thesis mode +_ +\fB\&.TP\fR \fIi\fRyyT{ +\fIi\fR=p.i. Begin indented paragraph, with the tag given on the next text line. Set prevailing indent to \fIi\fR. +T} +_ +\fB\&.TS\fR \fIx\fR-y,yT{ +begin table; if \fIx\fR=\fBH\fR table has multi-page header +T} +_ +\fB\&.TY\fR -ydisplay centered title \fBCONTENTS\fR +_ +\fB\&.VL\fR \fIi\fR [ \fIm\fR ] [ \fIs\fR ]\fIm\fR=\fB0\fR;\fIs\fR=\fB0\fRyT{ +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 +tab(); +cw(1.1i) |cw(2.19i) |cw(1.1i) |cw(1.11i) +lw(1.1i) |lw(2.19i) |lw(1.1i) |lw(1.11i) +. +NameRegister ControlsTakes EffectDefault +_ +\fBCl\fRcontents leveltable of contents2 +_ +\fBDe\fRdisplay ejectdisplay0 +_ +\fBDf\fRdisplay floatingdisplay5 +_ +\fBDs\fRdisplay spacingdisplay1v +_ +\fBHb\fRheading breakheading2 +_ +\fBHc\fRheading centeringheading0 +_ +\fBHi\fRheading indentheading1 +_ +\fBHi\fRheading spacingheading1 +_ +\fBHu\fRheading unnumberedheading2 +_ +\fBLi\fRlist indentationlist\fB6 (\fR\fBnroff\fR\fB) 5 (\fR\fBtroff\fR\fB)\fR +_ +\fBLs\fRlist spacinglist6 +_ +\fBPi\fRparagraph indentparagraph5 +_ +\fBPt\fRparagraph typeparagraph1 +_ +\fBSi\fRstatic indentdisplay\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 +tab(); +cw(1.82i) |cw(3.68i) +lw(1.82i) |lw(3.68i) +. +NameString's Function +_ +\fB\e*Q\fRquote (\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*-\fRdash (\fB--\fR in \fBnroff,\fR \(em in \fBtroff\fR ) +_ +\fB\e*(MO\fRmonth (month of the year) +_ +\fB\e*(DY\fRday (current date) +_ +\fB\e**\fRautomatically numbered footnote +_ +\fB\e*'\fRacute accent (before letter) +_ +\fB\e*`\fRgrave accent (before letter) +_ +\fB\e*^\fRcircumflex (before letter) +_ +\fB\e*,\fRcedilla (before letter) +_ +\fB\e*:\fRumlaut (before letter) +_ +\fB\e*~\fRtilde (before letter) +_ +\fB\e(BU\fRbullet item +_ +\fB\e(DT\fRdate (\fImonth day\fR, \fIyr\fR) +_ +\fB\e(EM\fRem 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\fRtrademark 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 +.mk +.na +\fB\fB/usr/share/lib/tmac/m\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.sp +.ne 2 +.mk +.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 +\fBcol\fR(1), \fBeqn\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), +\fBtroff\fR(1), \fBattributes\fR(5) +.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/man5/ms.5 b/usr/src/man/man5/ms.5 new file mode 100644 index 0000000000..9283157580 --- /dev/null +++ b/usr/src/man/man5/ms.5 @@ -0,0 +1,454 @@ +'\" 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 5 "25 Feb 1992" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fB\&.bp\fR\fR +.ad +.RS 11n +.rt +begin new page +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.br\fR\fR +.ad +.RS 11n +.rt +break output line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.sp\fR\fI n\fR\fR +.ad +.RS 11n +.rt +insert n spacing lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.ce\fR\fI n\fR\fR +.ad +.RS 11n +.rt +center next n lines +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.ls\fR\fI n\fR\fR +.ad +.RS 11n +.rt +line spacing: \fIn\fR\fB=1\fR single, \fIn\fR\fB=2\fR double space +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\&.na\fR\fR +.ad +.RS 11n +.rt +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 +tab(); +cw(.79i) |cw(.79i) |cw(.79i) |cw(3.14i) +lw(.79i) |lw(.79i) |lw(.79i) |lw(3.14i) +. +Macro NameInitial ValueBreak? Reset?Explanation +_ +\fB\&.AB\fR \fIx\fR-yT{ +begin abstract; if \fIx\fR=no do not label abstract +T} +_ +\fB\&.AE\fR-yend abstract +_ +\fB\&.AI\fR-yauthor's institution +_ +\fB\&.AM\fR-nbetter accent mark definitions +_ +\fB\&.AU\fR-yauthor's name +_ +\fB\&.B\fR \fIx\fR-nembolden \fIx\fR; if no \fIx\fR, switch to boldface +_ +\fB\&.B1\fR-ybegin text to be enclosed in a box +_ +\fB\&.B2\fR-yend boxed text and print it +_ +\fB\&.BT\fRdatenbottom title, printed at foot of page +_ +\fB\&.BX\fR \fIx\fR-nprint word \fIx\fR in a box +_ +\fB\&.CM\fRif tncut mark between pages +_ +\fB\&.CT\fR-y,yT{ +chapter title: page number moved to CF (TM only) +T} +_ +\fB\&.DA\fR \fIx\fRif nnT{ +force date \fIx\fR at bottom of page; today if no \fIx\fR +T} +_ +\fB\&.DE\fR-yend display (unfilled text) of any kind +_ +\fB\&.DS\fR \fIx y\fRIyT{ +begin display with keep; \fIx\fR=I,\|L,\|C,\|B; \fIy\fR=indent +T} +_ +\fB\&.ID\fR\fI y\fR8n,.5iyindented display with no keep; \fIy\fR=indent +_ +\fB\&.LD\fR-yleft display with no keep +_ +\fB\&.CD\fR-ycentered display with no keep +_ +\fB\&.BD\fR-yblock display; center entire block +_ +\fB\&.EF\fR \fIx\fR-neven page footer \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.EH\fR \fIx\fR-neven page header \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.EN\fR-yend displayed equation produced by \fBeqn\fR +_ +\fB\&.EQ\fR \fIx y\fR-yT{ +break out equation; \fIx\fR=L,I,C; \fIy\fR=equation number +T} +_ +\fB\&.FE\fR-nT{ +end footnote to be placed at bottom of page +T} +_ +\fB\&.FP\fR-nT{ +numbered footnote paragraph; may be redefined +T} +_ +\fB\&.FS\fR \fIx\fR-nT{ +start footnote; \fIx\fR is optional footnote label +T} +_ +\fB\&.HD\fRundefnoptional page header below header margin +_ +\fB\&.I\fR \fIx\fR-nitalicize \fIx\fR; if no \fIx\fR, switch to italics +_ +\fB\&.IP\fR \fIx y\fR-y,yT{ +indented paragraph, with hanging tag \fIx\fR; \fIy\fR=indent +T} +_ +\fB\&.IX\fR \fIx y\fR-yT{ +index words \fIx\fR \fIy\fR and so on (up to 5 levels) +T} +_ +\fB\&.KE\fR-nend keep of any kind +_ +\fB\&.KF\fR-nT{ +begin floating keep; text fills remainder of page +T} +_ +\fB\&.KS\fR-yT{ +begin keep; unit kept together on a single page +T} +_ +\fB\&.LG\fR-nlarger; increase point size by 2 +_ +\fB\&.LP\fR-y,yleft (block) paragraph. +_ +\fB\&.MC\fR \fIx\fR-y,ymultiple columns; \fIx\fR=column width +_ +\fB\&.ND\fR \fIx\fRif tnT{ +no date in page footer; \fIx\fR is date on cover +T} +_ +\fB\&.NH\fR \fIx y\fR-y,yT{ +numbered header; \fIx\fR=level, \fIx\fR=0 resets, \fIx\fR=S sets to \fIy\fR +T} +_ +\fB\&.NL\fR10pnset point size back to normal +_ +\fB\&.OF\fR \fIx\fR-nodd page footer \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.OH\fR \fIx\fR-nodd page header \fIx\fR (3 part as for \fB\&.tl\fR) +_ +\fB\&.P1\fRif TMnprint header on first page +_ +\fB\&.PP\fR-y,yparagraph with first line indented +_ +\fB\&.PT\fR- % -npage title, printed at head of page +_ +\fB\&.PX\fR \fIx\fR-yT{ +print index (table of contents); \fIx\fR=no suppresses title +T} +_ +\fB\&.QP\fR-y,yquote paragraph (indented and shorter) +_ +\fB\&.R\fRonnreturn to Roman font +_ +\fB\&.RE\fR5ny,yT{ +retreat: end level of relative indentation +T} +_ +\fB\&.RP\fR \fIx\fR-nT{ +released paper format; \fIx\fR=no stops title on first page +T} +_ +\fB\&.RS\fR5ny,yT{ +right shift: start level of relative indentation +T} +_ +\fB\&.SH\fR-y,ysection header, in boldface +_ +\fB\&.SM\fR-nsmaller; decrease point size by 2 +_ +\fB\&.TA\fR8n,5nnT{ +set TAB characters to 8n 16n .\|.\|. (\fBnroff\fR) or 5n 10n .\|.\|. (\fBtroff\fR) +T} +_ +\fB\&.TC\fR \fIx\fR-yT{ +print table of contents at end; \fIx\fR=no suppresses title +T} +_ +\fB\&.TE\fR-yend of table processed by \fBtbl\fR +_ +\fB\&.TH\fR-yend multi-page header of table +_ +\fB\&.TL\fR-ytitle in boldface and two points larger +_ +\fB\&.TM\fRoffnUC Berkeley thesis mode +_ +\fB\&.TS\fR \fIx\fR-y,yT{ +begin table; if \fIx\fR=H table has multi-page header +T} +_ +\fB\&.UL\fR \fIx\fR-nunderline \fIx\fR, even in \fBtroff\fR +_ +\fB\&.UX\fR \fIx\fR-nT{ +UNIX; trademark message first time; \fIx\fR appended +T} +_ +\fB\&.XA\fR \fIx y\fR-yT{ +another index entry; \fIx\fR=page or no for none; y=indent +T} +_ +\fB\&.XE\fR-yT{ +end index entry (or series of \fB\&.IX\fR entries) +T} +_ +\fB\&.XP\fR-y,yT{ +paragraph with first line indented, others indented +T} +_ +\fB\&.XS\fR \fIx y\fR-yT{ +begin index entry; \fIx\fR=page or no for none; \fIy\fR=indent +T} +_ +\fB\&.1C\fRony,yone column format, on a new page +_ +\fB\&.2C\fR-y,ybegin two column format +_ +\fB\&.]\|-\fR-nbeginning of \fBrefer\fR reference +_ +\fB\&.[\|0\fR-nend of unclassifiable type of reference +_ +\fB\&.[\|N\fR-nT{ +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 +tab(); +cw(.79i) |cw(1.57i) |cw(1.57i) |cw(1.57i) +lw(.79i) |lw(1.57i) |lw(1.57i) |lw(1.57i) +. +NameRegister ControlsTakes EffectDefault +_ +\fBPS\fRpoint size paragraph10 +_ +\fBVS\fRvertical spacingparagraph12 +_ +\fBLL\fRline length paragraph6i +_ +\fBLT\fRtitle length next pagesame as \fBLL\fR +_ +\fBFL\fRfootnote length next \fB\&.FS\fR5.5i +_ +\fBPD\fRparagraph distanceparagraph1v (if n), .3v (if t) +_ +\fBDD\fRdisplay distancedisplays1v (if n), .5v (if t) +_ +\fBPI\fRparagraph indentparagraph5n +_ +\fBQI\fRquote indent next \fB\&.QP\fR5n +_ +\fBFI\fRfootnote indent next \fB\&.FS\fR2n +_ +\fBPO\fRpage offset next page0 (if n), \(ap1i (if t) +_ +\fBHM\fRheader margin next page1i +_ +\fBFM\fRfooter margin next page1i +_ +\fBFF\fRfootnote format next \fB\&.FS\fR0 (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 +tab(); +cw(1.38i) |cw(4.13i) +lw(1.38i) |lw(4.13i) +. +NameString's Function +_ +\fB\e*Q\fRquote (\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*-\fRdash (\fB--\fR in \fBnroff,\fR \fB\(em\fR in \fBtroff\fR ) +_ +\fB\e*(MO\fRmonth (month of the year) +_ +\fB\e*(DY\fRday (current date) +_ +\fB\e**\fRautomatically numbered footnote +_ +\fB\e*'\fRacute accent (before letter) +_ +\fB\e*`\fRgrave accent (before letter) +_ +\fB\e*^\fRcircumflex (before letter) +_ +\fB\e*,\fRcedilla (before letter) +_ +\fB\e*:\fRumlaut (before letter) +_ +\fB\e*~\fRtilde (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 +.mk +.na +\fB\fB/usr/share/lib/tmac/s\fR\fR +.ad +.RS 30n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/share/lib/tmac/ms.???\fR\fR +.ad +.RS 30n +.rt + +.RE + +.SH SEE ALSO +.sp +.LP +\fBcol\fR(1), \fBeqn\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), +\fBtroff\fR(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/man5/mutex.5 b/usr/src/man/man5/mutex.5 new file mode 100644 index 0000000000..fd3830ee66 --- /dev/null +++ b/usr/src/man/man5/mutex.5 @@ -0,0 +1,145 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of +.\" Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH mutex 5 "5 Jun 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +tab() box; +cw(2.19i) |cw(3.31i) +lw(2.19i) |lw(3.31i) +. +FUNCTION ACTION +_ +\fBmutex_init\fRInitialize a mutex. +\fBmutex_destroy\fRDestroy a mutex. +\fBmutex_lock\fRLock a mutex. +\fBmutex_trylock\fRAttempt to lock a mutex. +\fBmutex_unlock\fRUnlock a mutex. +\fBpthread_mutex_init\fRInitialize a mutex. +\fBpthread_mutex_destroy\fRDestroy a mutex. +\fBpthread_mutex_lock\fRLock a mutex. +\fBpthread_mutex_trylock\fRAttempt to lock a mutex. +\fBpthread_mutex_unlock\fRUnlock 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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBshmop\fR(2), \fBmutex_destroy\fR(3C), \fBmutex_init\fR(3C), +\fBmutex_lock\fR(3C), \fBmutex_trylock\fR(3C), \fBmutex_unlock\fR(3C), +\fBpthread_create\fR(3C), \fBpthread_mutex_destroy\fR(3C), +\fBpthread_mutex_init\fR(3C), \fBpthread_mutex_lock\fR(3C), +\fBpthread_mutex_trylock\fR(3C), \fBpthread_mutex_unlock\fR(3C), +\fBpthread_mutexattr_init\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.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/man5/nfssec.5 b/usr/src/man/man5/nfssec.5 new file mode 100644 index 0000000000..2993c36f91 --- /dev/null +++ b/usr/src/man/man5/nfssec.5 @@ -0,0 +1,151 @@ +'\" te +.\" 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 5 "16 Mar 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +nfssec \- overview of NFS security modes +.SH DESCRIPTION +.sp +.LP +The \fBmount_nfs\fR(1M) and \fBshare_nfs\fR(1M) 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(1M) and \fBautomount\fR(1M) do +not support \fBsec=none\fR at this time. \fBmount_nfs\fR(1M) allows you to +specify a single security mode; \fBshare_nfs\fR(1M) 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(1M) 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(5). +.sp +.ne 2 +.mk +.na +\fB\fBsys\fR\fR +.ad +.RS 9n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdh\fR\fR +.ad +.RS 9n +.rt +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 +.mk +.na +\fB\fBkrb5\fR\fR +.ad +.RS 9n +.rt +Use Kerberos V5 protocol to authenticate users before granting access to the +shared filesystem. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkrb5i\fR\fR +.ad +.RS 9n +.rt +Use Kerberos V5 authentication with integrity checking (checksums) to verify +that the data has not been tampered with. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkrb5p\fR\fR +.ad +.RS 9n +.rt +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 +.mk +.na +\fB\fBnone\fR\fR +.ad +.RS 9n +.rt +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=\fR\fInone,\fR users from the client are mapped to the +anonymous user. The \fBNFS\fR security mode \fBnone\fR is supported by +\fBshare_nfs\fR(1M), but not by \fBmount_nfs\fR(1M) or \fBautomount\fR(1M). +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nfssec.conf\fR\fR +.ad +.RS 20n +.rt +\fBNFS\fR security service configuration file +.RE + +.SH SEE ALSO +.sp +.LP +\fBautomount\fR(1M), \fBkclient\fR(1M), \fBmount_nfs\fR(1M), +\fBshare_nfs\fR(1M), \fBrpc_clnt_auth\fR(3NSL), \fBsecure_rpc\fR(3NSL), +\fBnfssec.conf\fR(4), \fBattributes\fR(5), \fBkerberos\fR(5) +.SH NOTES +.sp +.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(1M). diff --git a/usr/src/man/man5/pam_allow.5 b/usr/src/man/man5/pam_allow.5 new file mode 100644 index 0000000000..95a171ad37 --- /dev/null +++ b/usr/src/man/man5/pam_allow.5 @@ -0,0 +1,113 @@ +'\" 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 5 "25 Aug 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) module. +.sp +.LP +Proper Solaris authentication operation requires \fBpam_unix_cred\fR(5) be +stacked above \fBpam_allow\fR. +.sp +.LP +The following options are interpreted: +.sp +.ne 2 +.mk +.na +\fBdebug\fR +.ad +.RS 9n +.rt +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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_sm\fR(3PAM), \fBsyslog\fR(3C), +\fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_deny\fR(5), +\fBpam_unix_cred\fR(5) +.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/man5/pam_authtok_check.5 b/usr/src/man/man5/pam_authtok_check.5 new file mode 100644 index 0000000000..866f25de1a --- /dev/null +++ b/usr/src/man/man5/pam_authtok_check.5 @@ -0,0 +1,212 @@ +'\" 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 5 "1 Mar 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fBlength\fR +.ad +.RS 20n +.rt +The password length should not be less that the minimum specified in +\fB/etc/default/passwd\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBcircular shift\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fBcomplexity\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fBvariation\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fBdictionary check\fR +.ad +.RS 20n +.rt +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(1M) 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 +.mk +.na +\fBupper/lower case\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fBmaximum repeats\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fBforce_check\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fBdebug\fR +.ad +.RS 15n +.rt +\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 +.mk +.na +\fB/etc/default/passwd\fR +.ad +.RS 23n +.rt +See \fBpasswd\fR(1) for a description of the contents. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBpam\fR(3PAM), \fBmkpwdict\fR(1M), +\fBpam_chauthtok\fR(3PAM), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), +\fBpam.conf\fR(4), \fBpasswd\fR(4), \fBshadow\fR(4), \fBattributes\fR(5), +\fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), +\fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), +\fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). diff --git a/usr/src/man/man5/pam_authtok_get.5 b/usr/src/man/man5/pam_authtok_get.5 new file mode 100644 index 0000000000..27b27b36c0 --- /dev/null +++ b/usr/src/man/man5/pam_authtok_get.5 @@ -0,0 +1,158 @@ +'\" 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 5 "14 Dec 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +pam_authtok_get \- authentication and password management module +.SH SYNOPSIS +.LP +.nf +\fBpam_authtok_get.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpam_authtok_get\fR service module provides password prompting +funtionality 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" +.sp +.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" +.sp +.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 subsequentially +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 +.mk +.na +\fBdebug\fR +.ad +.RS 9n +.rt +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.SH ERRORS +.sp +.LP +The authentication service returns the following error codes: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +.rt +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +.rt +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 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 19n +.rt +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.RS 19n +.rt +Authentication token manipulation error +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C), +\fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5), +\fBpam_authtok_check\fR(5), pam_authtok_get(5), \fBpam_authtok_store\fR(5), +\fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), +\fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). diff --git a/usr/src/man/man5/pam_authtok_store.5 b/usr/src/man/man5/pam_authtok_store.5 new file mode 100644 index 0000000000..953849a8a0 --- /dev/null +++ b/usr/src/man/man5/pam_authtok_store.5 @@ -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 5 "26 Jan 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4). +.sp +.LP +The following option can be passed to the module: +.sp +.ne 2 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 17n +.rt +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBserver_policy\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +.rt +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +.rt +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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_chauthtok\fR(3PAM), +\fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5), +\fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), \fBpam_dhkeys\fR(5), +\fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), +\fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). +.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/man5/pam_deny.5 b/usr/src/man/man5/pam_deny.5 new file mode 100644 index 0000000000..0cb955ec58 --- /dev/null +++ b/usr/src/man/man5/pam_deny.5 @@ -0,0 +1,159 @@ +'\" 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 5 "16 Jun 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fBdebug\fR +.ad +.RS 9n +.rt +\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 +.mk +.na +\fB\fBPAM_ACCT_EXPIRED\fR\fR +.ad +.RS 20n +.rt +If \fBpam_sm_acct_mgmt\fR is called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +.rt +If \fBpam_sm_authenticate\fR is called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTHOK_ERR\fR\fR +.ad +.RS 20n +.rt +If \fBpam_sm_chauthtok\fR is called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_CRED_ERR\fR\fR +.ad +.RS 20n +.rt +If \fBpam_sm_setcred\fR is called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SESSION_ERR\fR\fR +.ad +.RS 20n +.rt +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(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsu\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), +\fBpam_sm_authenticate\fR(3PAM), \fBsyslog\fR(3C), \fBpam.conf\fR(4), +\fBnsswitch.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), +\fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), +\fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), +\fBpam_unix_session\fR(5), \fBprivileges\fR(5) +.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/man5/pam_dhkeys.5 b/usr/src/man/man5/pam_dhkeys.5 new file mode 100644 index 0000000000..720d5740dd --- /dev/null +++ b/usr/src/man/man5/pam_dhkeys.5 @@ -0,0 +1,239 @@ +'\" 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 5 "21 Jan 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +pam_dhkeys \- authentication Diffie-Hellman keys management module +.SH SYNOPSIS +.LP +.nf +\fBpam_dhkeys.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.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 NIS+ +and other \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 +.mk +.na +\fBdebug\fR +.ad +.RS 10n +.rt +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.mk +.na +\fBnowarn\fR +.ad +.RS 10n +.rt +Turn off warning messages +.RE + +.SS "Authentication Services" +.sp +.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. Not being able to establish the secret keys results in +an authentication error if the NIS+ repository is used to authenticate the user +and the NIS+ table permissions require secure RPC credentials to access the +password field. 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" +.sp +.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 +.sp +.LP +The authentication service returns the following error codes: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +.rt +Credentials set successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +.rt +Credentials not needed to access the password repository. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +\fBPAM_USER\fR is not set, or the user is unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +.rt +Module ran out of memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +.rt +The NIS\(ma+ subsystem failed . +.RE + +.sp +.LP +The authentication token management returns the following error codes: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS \fR\fR +.ad +.RS 20n +.rt +Old \fBrpc\fR password is set in \fBSUNW_OLDRPCPASS\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +User in \fBPAM_USER\fR is unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.RS 20n +.rt +User did not provide a password that decrypts the secret keys. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +.rt +Module ran out of memory. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBkeylogin\fR(1), \fBkeylogout\fR(1), \fBpam\fR(3PAM), +\fBpam_authenticate\fR(3PAM), \fBpam_chauthtok\fR(3PAM), +\fBpam_setcred\fR(3PAM), \fBpam_get_item\fR(3PAM), \fBpam_set_data\fR(3PAM), +\fBpam_get_data\fR(3PAM), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), +\fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), +\fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). diff --git a/usr/src/man/man5/pam_dial_auth.5 b/usr/src/man/man5/pam_dial_auth.5 new file mode 100644 index 0000000000..96e9ee7829 --- /dev/null +++ b/usr/src/man/man5/pam_dial_auth.5 @@ -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 5 "9 Sept 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) and \fBd_passwd\fR(4) +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(4). If there is a match, the user's shell is compared against +entries in \fBd_passwd\fR(4). 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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 9n +.rt +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.SH ERRORS +.sp +.LP +If \fBdialups\fR(4) 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 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +.rt +Authentication failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 20n +.rt +Error in the calling service, \fBPAM_TTY\fR is not set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +.rt +System error (\fBd_passwd\fR(4) is not present). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +No account is present for \fIuser\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), +\fBd_passwd\fR(4), \fBdialups\fR(4), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), +\fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). diff --git a/usr/src/man/man5/pam_krb5.5 b/usr/src/man/man5/pam_krb5.5 new file mode 100644 index 0000000000..1c6dbdfb37 --- /dev/null +++ b/usr/src/man/man5/pam_krb5.5 @@ -0,0 +1,772 @@ +'\" 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 5 "8 Apr 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) 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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +.rt +Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +.rt +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 +.mk +.na +\fBdebug\fR +.ad +.RS 10n +.rt +Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.mk +.na +\fBnowarn\fR +.ad +.RS 10n +.rt +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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 9n +.rt +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 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +.rt +Authentication failure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +.rt +Memory buffer error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +.rt +The user is "\fBroot\fR" and the root key exists in the default keytab. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +.rt +Successfully obtained Kerberos credentials . +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +.rt +System error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +An unknown Kerberos principal was requested. +.RE + +.sp +.LP +The following error codes are returned for \fBpam_sm_setcred()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 18n +.rt +Authentication failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 18n +.rt +Memory buffer error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 18n +.rt +The user is "\fBroot\fR" and the root key exists in the default keytab. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +.rt +System error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +.rt +Successfully modified the Kerberos credential cache. +.RE + +.sp +.LP +The following error codes are returned for \fBpam_sm_acct_mgmt()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 24n +.rt +Authentication failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +.rt +Obtain new authentication token from the user. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 24n +.rt +Error in underlying service module. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +.rt +Kerberos principal account is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 24n +.rt +System error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 14n +.rt +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 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 24n +.rt +Authentication failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +.rt +User's Kerberos password has expired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 24n +.rt +Error in module. At least one input parameter is missing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 24n +.rt +System error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +.rt +An unknown Kerberos principal was requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +.rt +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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBkdestroy\fR(1), \fBkinit\fR(1), \fBkpasswd\fR(1), \fBpasswd\fR(1), +\fBktkt_warnd\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_sm\fR(3PAM), +\fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), +\fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_close_session\fR(3PAM), +\fBpam_sm_open_session\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBsyslog\fR(3C), +\fBpam.conf\fR(4), \fBattributes\fR(5), \fBkerberos\fR(5), \fBkrb5envvar\fR(5) +.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(1M) will be notified, to alert the user when the initial +credentials are about to expire. diff --git a/usr/src/man/man5/pam_krb5_migrate.5 b/usr/src/man/man5/pam_krb5_migrate.5 new file mode 100644 index 0000000000..1bea56424a --- /dev/null +++ b/usr/src/man/man5/pam_krb5_migrate.5 @@ -0,0 +1,211 @@ +'\" 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 5 "Jul 29 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +pam_krb5_migrate \- authentication PAM module for the KerberosV5 auto-migration +of users feature +.SH SYNOPSIS +.LP +.nf +\fB/usr/lib/security/pam_krb5_migrate.so.1\fR +.fi + +.SH DESCRIPTION +.sp +.LP +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" +.sp +.LP +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(1M) (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(4) file. \fBkadmind\fR(1M) 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(5) 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(5) be listed in the PAM account stack of that service for +proper operation (see EXAMPLES). +.SH OPTIONS +.sp +.LP +The following options can be passed to the KerberosV5 auto-migrate +authentication module: +.sp +.ne 2 +.mk +.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 +.mk +.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(1M) 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 +.mk +.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 +.mk +.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 +.LP +\fBExample 1 \fRSample Entries from \fBpam.conf\fR +.sp +.LP +The following entries from \fBpam.conf\fR(4) 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(4) permit or deny privileges to the +host client service principal: + +.sp +.in +2 +.nf +host/*@ACME.COM U root +host/*@ACME.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 \fBACME.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(1M) 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 +.sp +.LP +See \fBattributes\fR(5) for a description of the following attribute: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBkadmind\fR(1M), \fBsyslog\fR(3C), \fBpam_authenticate\fR(3PAM), +\fBpam_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBkadm5.acl\fR(4), +\fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_krb5\fR(5) diff --git a/usr/src/man/man5/pam_ldap.5 b/usr/src/man/man5/pam_ldap.5 new file mode 100644 index 0000000000..137a936cff --- /dev/null +++ b/usr/src/man/man5/pam_ldap.5 @@ -0,0 +1,462 @@ +'\" 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 5 "21 Dec 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.sp +.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(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), +and \fBpam_unix_auth\fR(5). \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" +.sp +.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(1M) 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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +.rt +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +.rt +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" +.sp +.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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +.rt +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +.rt +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" +.sp +.LP +LDAP password management is no longer supported by \fBpam_ldap\fR. Use +\fBpam_authtok_store\fR(5) instead of \fBpam_ldap\fR for password change. +\fBpam_authtok_store\fR(5) handles both the local and LDAP accounts and updates +the passwords in all the repositories configured by \fBnsswitch.conf\fR(4). +.SH ERRORS +.sp +.LP +The authentication service returns the following error codes: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +.rt +The uthentication was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_MAXTRIES\fR\fR +.ad +.RS 20n +.rt +The maximum number of authentication attempts was exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.RS 20n +.rt +The authentication failed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +No account is present for the user. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +.rt +A memory buffer error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +.rt +A system error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +.rt +The user's account was inactivated. +.RE + +.sp +.LP +The account management service returns the following error codes: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +.rt +The user was allowed access to the account. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +.rt +A new authentication token is required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_ACCT_EXPIRED\fR\fR +.ad +.RS 24n +.rt +The user account has expired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 24n +.rt +The user was denied access to the account at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +.rt +No account is present for the user. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERROR\fR\fR +.ad +.RS 24n +.rt +A memory buffer error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 24n +.rt +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 +.sp +.ne 2 +.mk +.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 +.rt +The LDAP configuration files of the client. Do not manually modify these files, +as these files might not be human readable. Use \fBldapclient\fR(1M) to update +these files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/pam.conf\fR\fR +.ad +.RS 30n +.rt +PAM configuration file. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(1), \fBidsconfig\fR(1M), \fBldap_cachemgr\fR(1M), +\fBldapclient\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), +\fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), +\fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_close_session\fR(3PAM), +\fBpam_sm_open_session\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBsyslog\fR(3C), +\fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), +\fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5) +.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 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(4), and are silently ignored. They might be removed in a future +release. Password prompting must be provided for by stacking +\fBpam_authtok_get\fR(5) before \fBpam_ldap\fR in the \fBauth\fR and +\fBpassword\fR module stacks and \fBpam_passwd_auth\fR(5) 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/man5/pam_list.5 b/usr/src/man/man5/pam_list.5 new file mode 100644 index 0000000000..694bebf58e --- /dev/null +++ b/usr/src/man/man5/pam_list.5 @@ -0,0 +1,307 @@ +'\" 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 5 "26 Mar 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +pam_list \- PAM account management module for UNIX +.SH SYNOPSIS +.LP +.nf + pam_list.so.1 +.fi + +.SH DESCRIPTION +.sp +.LP +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 and/or netgroups in the given file. The users and +netgroups are separated by newline character. Netgroups are specified with +character '@' as prefix before name of netgroup in the list. The maximum line +lenght 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(4) 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 +.mk +.na +\fB\fBallow=\fR\fR +.ad +.RS 19n +.rt +The full pathname to a file of allowed users and/or netgroups. Only one of +\fBallow=\fR or \fBdeny=\fR can be specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcompat\fR\fR +.ad +.RS 19n +.rt +Activate \fBcompat\fR mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdeny=\fR\fR +.ad +.RS 19n +.rt +The full pathname to a file of denied users and/or netgroups. Only one of +\fBdeny=\fR or \fBallow=\fR can be specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 19n +.rt +Provide \fBsyslog\fR(3C) debugging information at the \fBLOG_AUTH\fR | +\fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuser\fR\fR +.ad +.RS 19n +.rt +The module should only perform netgroup matches on the username. This is the +default option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnouser\fR\fR +.ad +.RS 19n +.rt +The username should not be used in the netgroup match. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhost\fR\fR +.ad +.RS 19n +.rt +Only the host should be used in netgroup matches. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnohost\fR\fR +.ad +.RS 19n +.rt +The hostname should not be used in netgroup matches. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuser_host_exact\fR\fR +.ad +.RS 19n +.rt +The user and hostname must be in the same netgroup. +.RE + +.SH ERRORS +.sp +.LP +The following error values are returned: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 20n +.rt +An invalid set of module options was given in the \fBpam.conf\fR(4) for this +module, or the \fBuser/netgroup\fR file could not be opened. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +.rt +A memory buffer error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +.rt +The module is ignored, as it is not participating in the result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 20n +.rt +The user is not on the allow list or is on the deny list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 20n +.rt +The account is valid for use at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +No account is present for the user +.RE + +.SH EXAMPLES +.LP +\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/user.allow +.fi +.in -2 + +.sp +.LP +\fB/etc/users.allow\fR contains: +.sp +.in +2 +.nf +root +localloginname +remoteloginname +@netgroup +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-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 +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_sm_acct_mgmt\fR(3PAM), +\fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBnsswitch.conf\fR(4), +\fBpam.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man5/pam_passwd_auth.5 b/usr/src/man/man5/pam_passwd_auth.5 new file mode 100644 index 0000000000..336b3c7362 --- /dev/null +++ b/usr/src/man/man5/pam_passwd_auth.5 @@ -0,0 +1,160 @@ +'\" 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 5 "10 Aug 2002" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 17n +.rt +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.RS 17n +.rt +Turn off warning messages +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBserver_policy\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 18n +.rt +Memory buffer error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 18n +.rt +Ignore module, not participating in result +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 18n +.rt +Successfully obtains authentication token +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 18n +.rt +System error +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), +\fBpam_start\fR(3PAM), \fBpam_set_item\fR(3PAM), \fBsyslog\fR(3C), +\fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5), +\fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_unix_account\fR(5), +\fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). diff --git a/usr/src/man/man5/pam_rhosts_auth.5 b/usr/src/man/man5/pam_rhosts_auth.5 new file mode 100644 index 0000000000..7b64a63f96 --- /dev/null +++ b/usr/src/man/man5/pam_rhosts_auth.5 @@ -0,0 +1,69 @@ +'\" 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 5 "28 Oct 1996" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBdebug\fR \fR +.ad +.RS 10n +.rt +\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBruserok\fR(3SOCKET), +\fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5) +.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/man5/pam_roles.5 b/usr/src/man/man5/pam_roles.5 new file mode 100644 index 0000000000..8d237bfb3f --- /dev/null +++ b/usr/src/man/man5/pam_roles.5 @@ -0,0 +1,196 @@ +'\" 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 5 "6 Mar 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) 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(5) module. +.sp +.LP +The following options are interpreted: +.sp +.ne 2 +.mk +.na +\fB\fBallow_remote\fR\fR +.ad +.RS 16n +.rt +Allows a remote service to specify the user to enter as a role. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +No account is present for user. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 20n +.rt +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(4). 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(4) 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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBroles\fR(1), \fBsshd\fR(1M), \fBsu\fR(1M), \fBlibpam\fR(3LIB), +\fBpam\fR(3PAM), \fBpam_acct_mgmt\fR(3PAM), \fBpam_setcred\fR(3PAM), +\fBpam_set_item\fR(3PAM), \fBpam_sm_acct_mgmt\fR(3PAM), \fBsyslog\fR(3C), +\fBpam.conf\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5), +\fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5) +.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/man5/pam_sample.5 b/usr/src/man/man5/pam_sample.5 new file mode 100644 index 0000000000..15aac6041b --- /dev/null +++ b/usr/src/man/man5/pam_sample.5 @@ -0,0 +1,222 @@ +'\" 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 5 "4 Apr 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) 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 +.mk +.na +\fB\fBdebug\fR \fR +.ad +.RS 20n +.rt +Syslog debugging information at the \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpass=newone\fR \fR +.ad +.RS 20n +.rt +Sets the password to be "newone". +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfirst_pass_good\fR \fR +.ad +.RS 20n +.rt +The first password is always good when used with the use_first_pass or +try_first_pass option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfirst_pass_bad\fR \fR +.ad +.RS 20n +.rt +The first password is always bad when used with the use_first_pass or +try_first_pass option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBalways_fail\fR \fR +.ad +.RS 20n +.rt +Always returns \fBPAM_AUTH_ERR.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBalways_succeed\fR \fR +.ad +.RS 20n +.rt +Always returns \fBPAM_SUCCESS.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBalways_ignore\fR \fR +.ad +.RS 20n +.rt +Always returns \fBPAM_IGNORE.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuse_first_pass\fR \fR +.ad +.RS 20n +.rt +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 +.mk +.na +\fB\fBtry_first_pass\fR \fR +.ad +.RS 20n +.rt +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 +tab(); +lw(0i) lw(0i) lw(0i) lw(0i) lw(5.5i) +lw(0i) lw(0i) lw(0i) lw(0i) lw(5.5i) +. +loginaccountrequirepam_sample.so.1allow=larry +dtloginaccountrequirepam_sample.so.1allow=larry +rloginaccountrequirepam_sample.so.1allow=don allow=larry +suaccountrequirepam_sample.so.1allow=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(5) for description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM), +\fBpam_sm_close_session\fR(3PAM), \fBpam_sm_open_session\fR(3PAM), +\fBpam_sm_setcred\fR(3PAM), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), +\fBattributes\fR(5) +.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/man5/pam_smb_passwd.5 b/usr/src/man/man5/pam_smb_passwd.5 new file mode 100644 index 0000000000..43db872d4e --- /dev/null +++ b/usr/src/man/man5/pam_smb_passwd.5 @@ -0,0 +1,196 @@ +'\" 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 5 "29 Apr 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBPAM_PRELIM_CHECK\fR\fR +.ad +.sp .6 +.RS 4n +Always returns \fBPAM_IGNORE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SILENT\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses messages. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses warning messages. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Authentication token manipulation error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTHTOK_LOCK_BUSY\fR\fR +.ad +.sp .6 +.RS 4n +\fBSMB\fR password file is locked +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.sp .6 +.RS 4n +System error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.sp .6 +.RS 4n +User is unknown +.RE + +.SH ATTRIBUTES +.sp +.LP +See the \fBattributes\fR(5) man page for descriptions of the following +attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsmbd\fR(1M), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), +\fBpam_chauthtok\fR(3PAM), \fBpam_sm\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM), +\fBpam.conf\fR(4), \fBattributes\fR(5) +.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/man5/pam_smbfs_login.5 b/usr/src/man/man5/pam_smbfs_login.5 new file mode 100644 index 0000000000..32c4190bd2 --- /dev/null +++ b/usr/src/man/man5/pam_smbfs_login.5 @@ -0,0 +1,237 @@ +'\" 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 5 "25 Sep 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fB\fBPAM_REFRESH_CRED\fR\fR +.ad +.sp .6 +.RS 4n +Returns PAM_IGNORE. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SILENT\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses messages. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.sp .6 +.RS 4n +Suppresses warning messages. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB$HOME/.nsmbrc\fR\fR +.ad +.RS 28n +.rt +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 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.sp .6 +.RS 4n +User is unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTHTOK_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Password is bad. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Domain is bad. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.sp .6 +.RS 4n +System error. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attribute: +.sp + +.sp +.TS +tab() box; +cw(2.76i) |cw(2.74i) +lw(2.76i) |lw(2.74i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsmbutil\fR(1), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), +\fBpam_setcred\fR(3PAM), \fBpam_sm\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), +\fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBpam.conf\fR(4), +\fBattributes\fR(5), \fBsmbfs\fR(7FS) +.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/man5/pam_tsol_account.5 b/usr/src/man/man5/pam_tsol_account.5 new file mode 100644 index 0000000000..60955c2bd6 --- /dev/null +++ b/usr/src/man/man5/pam_tsol_account.5 @@ -0,0 +1,149 @@ +'\" 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 5 "20 Jul 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) file. These defaults can be overridden by entries in +the \fBuser_attr\fR(4) 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(4), +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 +.mk +.na +\fB\fBallow_unlabeled\fR\fR +.ad +.RS 19n +.rt +Allows remote connections from hosts with unlabeled template types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 19n +.rt +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 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 19n +.rt +The account is valid for use at this time and label. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 19n +.rt +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 +.mk +.na +\fBOther values\fR +.ad +.RS 19n +.rt +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(5) for description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT LevelMT-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 +\fBkeylogin\fR(1), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), +\fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_start\fR(3PAM), \fBsyslog\fR(3C), +\fBlabel_encodings\fR(4), \fBpam.conf\fR(4), \fBuser_attr\fR(4), +\fBattributes\fR(5) +.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/man5/pam_unix_account.5 b/usr/src/man/man5/pam_unix_account.5 new file mode 100644 index 0000000000..56bdda2ba6 --- /dev/null +++ b/usr/src/man/man5/pam_unix_account.5 @@ -0,0 +1,198 @@ +'\" 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 5 "14 Feb 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4). +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 17n +.rt +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.RS 17n +.rt +Turn off warning messages +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBserver_policy\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBPAM_UNIX_ACCOUNT\fR\fR +.ad +.RS 24n +.rt +User account has expired +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_AUTHTOK_EXPIRED\fR\fR +.ad +.RS 24n +.rt +Password expired and no longer usable +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 24n +.rt +Memory buffer error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 24n +.rt +Ignore module, not participating in result +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR +.ad +.RS 24n +.rt +Obtain new authentication token from the user +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.RS 24n +.rt +The account is locked or has been inactive for too long +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SERVICE_ERR\fR\fR +.ad +.RS 24n +.rt +Error in underlying service module +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.RS 24n +.rt +The account is valid for use at this time +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 24n +.rt +No account is present for the user +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C), +\fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBnsswitch.conf\fR(4), +\fBattributes\fR(5) +.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/man5/pam_unix_auth.5 b/usr/src/man/man5/pam_unix_auth.5 new file mode 100644 index 0000000000..363d96abdd --- /dev/null +++ b/usr/src/man/man5/pam_unix_auth.5 @@ -0,0 +1,239 @@ +'\" 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 5 "23 Apr 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4) +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(4) +and \fBpolicy.conf\fR(4)) 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(4) and +\fBshadow\fR(4)) 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(5) to ensure a successful return from +\fBpam_setcred\fR(3PAM). +.sp +.LP +The following options can be passed to the module: +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.sp .6 +.RS 4n +Turn off warning messages. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPAM_AUTH_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Authentication failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.sp .6 +.RS 4n +Memory buffer error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.sp .6 +.RS 4n +Ignores module, not participating in result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_MAXTRIES\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of retries exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_PERM_DENIED\fR\fR +.ad +.sp .6 +.RS 4n +Permission denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +Successfully obtains authentication token. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.sp .6 +.RS 4n +System error. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBlogin\fR(1), \fBpasswd\fR(1), \fBuseradd\fR(1M), \fBusermod\fR(1M), +\fBroleadd\fR(1M), \fBrolemod\fR(1M), \fBcrypt\fR(3C), \fBlibpam\fR(3LIB), +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_setcred\fR(3PAM), +\fBsyslog\fR(3C), \fBpam.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), +\fBnsswitch.conf\fR(4), \fBshadow\fR(4), \fBuser_attr\fR(4), +\fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_session\fR(5) +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), +\fBpam_passwd_auth\fR(5),\fBpam_setcred\fR(3PAM), \fBpam_unix_account\fR(5), +\fBpam_unix_cred\fR(5), \fBpam_unix_session\fR(5). +.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/man5/pam_unix_cred.5 b/usr/src/man/man5/pam_unix_cred.5 new file mode 100644 index 0000000000..8ec53b32ff --- /dev/null +++ b/usr/src/man/man5/pam_unix_cred.5 @@ -0,0 +1,232 @@ +'\" 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 5 "9 Mar 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) 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 +.mk +.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(1M). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fBdebug\fR\fR +.ad +.RS 10n +.rt +Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnowarn\fR\fR +.ad +.RS 10n +.rt +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 +.mk +.na +\fB\fBPAM_CRED_UNAVAIL\fR\fR +.ad +.RS 20n +.rt +Underlying authentication service cannot retrieve user credentials +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_CRED_EXPIRED\fR\fR +.ad +.RS 20n +.rt +User credentials have expired +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +User is unknown to the authentication service +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_CRED_ERR\fR\fR +.ad +.RS 20n +.rt +Failure in setting user credentials +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_BUF_ERR\fR\fR +.ad +.RS 20n +.rt +Memory buffer error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SYSTEM_ERR\fR\fR +.ad +.RS 20n +.rt +System error +.RE + +.sp +.LP +The following values are returned from \fBpam_sm_authenticate()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_IGNORE\fR\fR +.ad +.RS 14n +.rt +Ignores this module regardless of the control flag +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBssh\fR(1), \fBsu\fR(1M), \fBsettaskid\fR(2), \fBlibpam\fR(3LIB), +\fBgetprojent\fR(3PROJECT), \fBpam\fR(3PAM), \fBpam_set_item\fR(3PAM), +\fBpam_sm_authenticate\fR(3PAM), \fBsyslog\fR(3C), +\fBsetproject\fR(3PROJECT),\fBpam.conf\fR(4), \fBnsswitch.conf\fR(4), +\fBproject\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), +\fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), +\fBpam_passwd_auth\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_account\fR(5), +\fBpam_unix_session\fR(5), \fBprivileges\fR(5) +.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/man5/pam_unix_session.5 b/usr/src/man/man5/pam_unix_session.5 new file mode 100644 index 0000000000..7b28e52c59 --- /dev/null +++ b/usr/src/man/man5/pam_unix_session.5 @@ -0,0 +1,110 @@ +'\" 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_unix_session 5 "9 Sept 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) 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 +.mk +.na +\fBdebug\fR +.ad +.RS 9n +.rt +\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level +.RE + +.SH ERRORS +.sp +.LP +Upon successful completion, \fBPAM_SUCCESS\fR is returned. The following error +codes are returned upon error: +.sp +.ne 2 +.mk +.na +\fB\fBPAM_SESSION_ERR\fR\fR +.ad +.RS 20n +.rt +Cannot make or remove the entry for the specified session (PAM_TTY is not +present). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAM_USER_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +No account is present for \fIuser\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C), +\fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBnsswitch.conf\fR(4), +\fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5),\fBpam_unix_auth\fR(5), +.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(5) module is no longer supported. Similar functionality is +provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), +\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), +\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and +\fBpam_unix_session\fR(5). diff --git a/usr/src/man/man5/pkcs11_kernel.5 b/usr/src/man/man5/pkcs11_kernel.5 new file mode 100644 index 0000000000..733864ccdd --- /dev/null +++ b/usr/src/man/man5/pkcs11_kernel.5 @@ -0,0 +1,112 @@ +'\" 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 5 "27 Oct 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard: PKCS#11 v2.20 +_ +MT-LevelT{ +MT-Safe with exceptions. See section 6.5.2 of RSA PKCS#11 v2.20 +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBcryptoadm\fR(1M), \fBrctladm\fR(1M), \fBlibpkcs11\fR(3LIB), +\fBattributes\fR(5), \fBpkcs11_softtoken\fR(5) +.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/man5/pkcs11_softtoken.5 b/usr/src/man/man5/pkcs11_softtoken.5 new file mode 100644 index 0000000000..57d27f39e2 --- /dev/null +++ b/usr/src/man/man5/pkcs11_softtoken.5 @@ -0,0 +1,293 @@ +'\" 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 5 "25 Mar 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.mk +.na +\fBPublic key object\fR +.ad +.RS 22n +.rt +\fBCKA_ENCRYPT\fR, \fBCKA_VERIFY\fR, \fBCKA_VERIFY_RECOVER\fR +.RE + +.sp +.ne 2 +.mk +.na +\fBPrivate key object\fR +.ad +.RS 22n +.rt +\fBCKA_DECRYPT\fR, \fBCKA_SIGN\fR, \fBCKA_SIGN_RECOVER\fR, +\fBCKA_EXTRACTABLE\fR +.RE + +.sp +.ne 2 +.mk +.na +\fBSecret key object\fR +.ad +.RS 22n +.rt +\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 +.mk +.na +\fB\fBCKC_X_509\fR\fR +.ad +.RS 23n +.rt +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 +.mk +.na +\fB\fBCKC_X_509_ATTR_CERT\fR\fR +.ad +.RS 23n +.rt +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 +.mk +.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 +.mk +.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(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelT{ +MT-Safe with exceptions. See section 6.5.2 of RSA PKCS#11 v2.20. +T} +_ +StandardPKCS#11 v2.20 +.TE + +.SH SEE ALSO +.sp +.LP +\fBpktool\fR(1), \fBcryptoadm\fR(1M), \fBlibpkcs11\fR(3LIB), +\fBattributes\fR(5), \fBpkcs11_kernel\fR(5) +.sp +.LP +RSA PKCS#11 v2.20 http://www.rsasecurity.com diff --git a/usr/src/man/man5/pkcs11_tpm.5 b/usr/src/man/man5/pkcs11_tpm.5 new file mode 100644 index 0000000000..eaad9f4a45 --- /dev/null +++ b/usr/src/man/man5/pkcs11_tpm.5 @@ -0,0 +1,285 @@ +'\" 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 5 "20 Mar 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.sp +.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 \fBSUNWtrousers\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" +.sp +.LP +The \fBpkcs11_tpm\fR provider can only be used on a system which has a TPM +device and which also has the \fBSUNWtrousers\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" +.sp +.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" +.sp +.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 +.sp +.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 +.sp +.ne 2 +.mk +.na +\fB\fB/var/tpm/pkcs11/USERNAME\fR\fR +.ad +.sp .6 +.RS 4n +User's default token object store. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB${PKCS11_TPM_DIR}\fR\fR +.ad +.sp .6 +.RS 4n +Alternate token object store. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-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 +.sp +.LP +\fBpktool\fR(1), \fBcryptoadm\fR(1M), \fBlibpkcs11\fR(3LIB), +\fBattributes\fR(5) +.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/man5/privileges.5 b/usr/src/man/man5/privileges.5 new file mode 100644 index 0000000000..606958ab42 --- /dev/null +++ b/usr/src/man/man5/privileges.5 @@ -0,0 +1,1347 @@ +'\" 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 privileges 5 "29 May 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +privileges \- process privilege model +.SH DESCRIPTION +.sp +.LP +Solaris 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 Solaris +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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPRIV_DTRACE_KERNEL\fR\fR +.ad +.sp .6 +.RS 4n +Allow DTrace kernel-level tracing. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPRIV_PROC_CHROOT\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to change its root directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRIV_PROC_CLOCK_HIGHRES\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to use high resolution timers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRIV_PROC_EXEC\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to call \fBexec\fR(2). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPRIV_PROC_PRIOCNTL\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to elevate its priority above its current level. Allow a +process to change its scheduling class to any scheduling class, including the +RT class. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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(5). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 specifying \fBcoreadm\fR(1M) and \fBnscd\fR(1M) settings +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPRIV_SYS_LINKDIR\fR\fR +.ad +.sp .6 +.RS 4n +Allow a process to unlink and link directories. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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(1M) +\fBpppd\fR(1M) and control PPPoE plumbing with \fBsppptun\fR(1M)sppptun(1M). +This privilege is granted by default to exclusive IP stack instance zones. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRIV_SYS_RES_CONFIG\fR\fR +.ad +.sp .6 +.RS 4n +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 +.mk +.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 +.mk +.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 +.mk +.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 +Solaris proper. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPRIV_VIRT_MANAGE\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process to manage virtualized environments such as \fBxVM\fR(5). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBPRIV_XVM_CONTROL\fR\fR +.ad +.sp .6 +.RS 4n +Allows a process access to the \fBxVM\fR(5) 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 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 Solaris extends the process credential with +four privilege sets: +.sp +.ne 2 +.mk +.na +\fBI, the inheritable set\fR +.ad +.RS 26n +.rt +The privileges inherited on \fBexec\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBP, the permitted set\fR +.ad +.RS 26n +.rt +The maximum set of privileges for the process. +.RE + +.sp +.ne 2 +.mk +.na +\fBE, the effective set\fR +.ad +.RS 26n +.rt +The privileges currently in effect. +.RE + +.sp +.ne 2 +.mk +.na +\fBL, the limit set\fR +.ad +.RS 26n +.rt +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 absense 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" +.sp +.LP +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 Solaris 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" +.sp +.LP +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" +.sp +.LP +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(4) 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" +.sp +.LP +The Solaris Management Console (see \fBsmc\fR(1M)) is the preferred method of +modifying privileges for a command. Use \fBusermod\fR(1M) or \fBsmrole\fR(1M) +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 +.sp +.LP +\fBmdb\fR(1), \fBppriv\fR(1), \fBadd_drv\fR(1M), \fBifconfig\fR(1M), +\fBlockd\fR(1M), \fBnfsd\fR(1M), \fBpppd\fR(1M), \fBrem_drv\fR(1M), +\fBsmbd\fR(1M), \fBsppptun\fR(1M), \fBupdate_drv\fR(1M), \fBIntro\fR(2), +\fBaccess\fR(2), \fBacct\fR(2), \fBacl\fR(2), \fBadjtime\fR(2), \fBaudit\fR(2), +\fBauditon\fR(2), \fBchmod\fR(2), \fBchown\fR(2), \fBchroot\fR(2), +\fBcreat\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), +\fBfpathconf\fR(2), \fBgetacct\fR(2), \fBgetpflags\fR(2), \fBgetppriv\fR(2), +\fBgetsid\fR(2), \fBkill\fR(2), \fBlink\fR(2), \fBmemcntl\fR(2), +\fBmknod\fR(2), \fBmount\fR(2), \fBmsgctl\fR(2), \fBnice\fR(2), +\fBntp_adjtime\fR(2), \fBopen\fR(2), \fBp_online\fR(2), \fBpriocntl\fR(2), +\fBpriocntlset\fR(2), \fBprocessor_bind\fR(2), \fBpset_bind\fR(2), +\fBpset_create\fR(2), \fBreadlink\fR(2), \fBresolvepath\fR(2), \fBrmdir\fR(2), +\fBsemctl\fR(2), \fBsetauid\fR(2), \fBsetegid\fR(2), \fBseteuid\fR(2), +\fBsetgid\fR(2), \fBsetgroups\fR(2), \fBsetpflags\fR(2), \fBsetppriv\fR(2), +\fBsetrctl\fR(2), \fBsetregid\fR(2), \fBsetreuid\fR(2), \fBsetrlimit\fR(2), +\fBsettaskid\fR(2), \fBsetuid\fR(2), \fBshmctl\fR(2), \fBshmget\fR(2), +\fBshmop\fR(2), \fBsigsend\fR(2), \fBstat\fR(2), \fBstatvfs\fR(2), +\fBstime\fR(2), \fBswapctl\fR(2), \fBsysinfo\fR(2), \fBuadmin\fR(2), +\fBulimit\fR(2), \fBumount\fR(2), \fBunlink\fR(2), \fButime\fR(2), +\fButimes\fR(2), \fBbind\fR(3SOCKET), \fBdoor_ucred\fR(3C), +\fBpriv_addset\fR(3C), \fBpriv_set\fR(3C), \fBpriv_getbyname\fR(3C), +\fBpriv_getbynum\fR(3C), \fBpriv_set_to_str\fR(3C), \fBpriv_str_to_set\fR(3C), +\fBsocket\fR(3SOCKET), \fBt_bind\fR(3NSL), \fBtimer_create\fR(3C), +\fBucred_get\fR(3C), \fBexec_attr\fR(4), \fBproc\fR(4), \fBsystem\fR(4), +\fBuser_attr\fR(4), \fBxVM\fR(5), \fBddi_cred\fR(9F), \fBdrv_priv\fR(9F), +\fBpriv_getbyname\fR(9F), \fBpriv_policy\fR(9F), \fBpriv_policy_choice\fR(9F), +\fBpriv_policy_only\fR(9F) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man5/prof.5 b/usr/src/man/man5/prof.5 new file mode 100644 index 0000000000..9a2ca83ce8 --- /dev/null +++ b/usr/src/man/man5/prof.5 @@ -0,0 +1,72 @@ +'\" 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 5 "3 Jul 1990" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +\fBprofil\fR(2), \fBmonitor\fR(3C) diff --git a/usr/src/man/man5/rbac.5 b/usr/src/man/man5/rbac.5 new file mode 100644 index 0000000000..bae6658637 --- /dev/null +++ b/usr/src/man/man5/rbac.5 @@ -0,0 +1,238 @@ +'\" 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 5 "15 Jul 2003" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4). 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(4), +\fBuser_attr\fR(4), and \fBprof_attr\fR(4) 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 +\fBld.so.1\fR(1), \fBchkauthattr\fR(3SECDB), \fBauth_attr\fR(4), +\fBpolicy.conf\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4) +.sp +.LP +\fISystem Administration Guide: Security Services\fR diff --git a/usr/src/man/man5/regex.5 b/usr/src/man/man5/regex.5 new file mode 100644 index 0000000000..70cfb7c24b --- /dev/null +++ b/usr/src/man/man5/regex.5 @@ -0,0 +1,813 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Portions Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical 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] +.TH regex 5 "21 Apr 2005" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +regex \- internationalized basic and extended regular expression matching +.SH DESCRIPTION +.sp +.LP +Regular Expressions (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 +\fBregexp\fR(5) manual page in the following ways: +.RS +4 +.TP +.ie t \(bu +.el o +both Basic and Extended 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 supported. +.RE +.sp +.LP +The Basic Regular Expression (BRE) notation and construction rules described in +the \fBBASIC\fR \fBREGULAR\fR \fBEXPRESSIONS\fR section apply to most utilities +supporting regular expressions. Some utilities, instead, support the Extended +Regular Expressions (ERE) described in the \fBEXTENDED\fR \fBREGULAR\fR +\fBEXPRESSIONS\fR 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 +\fBregcomp\fR(3C) and \fBregexec\fR(3C). +.SH BASIC REGULAR EXPRESSIONS +.SS "BREs Matching a Single Character" +.sp +.LP +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 \fBRE Bracket Expression\fR, +below. +.SS "BRE Ordinary Characters" +.sp +.LP +An ordinary character is a BRE that matches itself: any character in the +supported character set, except for the BRE special characters listed in \fBBRE +Special Characters\fR, below. +.sp +.LP +The interpretation of an ordinary character preceded by a backslash (\e) is +undefined, except for: +.RS +4 +.TP +1. +the characters ), (, {, and } +.RE +.RS +4 +.TP +2. +the digits 1 to 9 inclusive (see \fBBREs Matching Multiple Characters\fR, +below) +.RE +.RS +4 +.TP +3. +a character inside a bracket expression. +.RE +.SS "BRE Special Characters" +.sp +.LP +A BRE \fIspecial\fR \fIcharacter\fR 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: +.sp +.ne 2 +.mk +.na +\fB\&. [ \e\fR +.ad +.RS 12n +.rt +The period, left-bracket, and backslash are special except when used in a +bracket expression (see \fBRE Bracket Expression\fR, below). An expression +containing a [ that is not preceded by a backslash and is not part of a bracket +expression produces undefined results. +.RE + +.sp +.ne 2 +.mk +.na +\fB*\fR +.ad +.RS 12n +.rt +The asterisk is special except when used: +.RS +4 +.TP +.ie t \(bu +.el o +in a bracket expression +.RE +.RS +4 +.TP +.ie t \(bu +.el o +as the first character of an entire BRE (after an initial ^, if any) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +as the first character of a subexpression (after an initial ^, if any); see +\fBBREs Matching Multiple Characters\fR, below. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI^\fR\fR +.ad +.RS 12n +.rt +The circumflex is special when used: +.RS +4 +.TP +.ie t \(bu +.el o +as an anchor (see \fBBRE Expression Anchoring\fR, below). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +as the first character of a bracket expression (see \fBRE Bracket +Expression\fR, below). +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB$\fR +.ad +.RS 12n +.rt +The dollar sign is special when used as an anchor. +.RE + +.SS "Periods in BREs" +.sp +.LP +A period (\fB\&.\fR), when used outside a bracket expression, is a BRE that +matches any character in the supported character set except NUL. +.SS "RE Bracket Expression" +.sp +.LP +A bracket expression (an expression enclosed in square brackets, [\|]) is an RE +that matches a single collating element contained in the non-empty set of +collating elements represented by the bracket expression. +.sp +.LP +The following rules and definitions apply to bracket expressions: +.RS +4 +.TP +1. +A \fIbracket expression\fR 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 (see rule 7 below). Portable applications must not use range +expressions, even though all implementations support them. The right-bracket +(]) loses its special meaning and represents itself in a bracket expression if +it occurs first in the list (after an initial circumflex (^), if any). +Otherwise, it terminates the bracket expression, unless it appears in a +collating symbol (such as [.].]) or is the ending right-bracket for a collating +symbol, equivalence class, or character class. The special characters: +.sp +.in +2 +.nf + . * [ \e +.fi +.in -2 +.sp + +(period, asterisk, left-bracket and backslash, respectively) lose their special +meaning within a bracket expression. +.sp +The character sequences: +.sp +.in +2 +.nf + [. [= [: +.fi +.in -2 +.sp + +(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 .], =] or :], as +described in the following items. +.RE +.RS +4 +.TP +2. +A \fImatching list\fR 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, \fB[abc]\fR is an RE that matches any of +the characters \fBa\fR, \fBb\fR or \fBc\fR. +.RE +.RS +4 +.TP +3. +A \fInon-matching list\fR expression begins with a circumflex (^), 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, +[^abc] is an RE that matches any character or collating element except the +characters \fBa,\fR \fBb\fR, or \fBc\fR. The circumflex will have this special +meaning only when it occurs first in the list, immediately following the +left-bracket. +.RE +.RS +4 +.TP +4. +A \fIcollating symbol\fR is a collating element enclosed within +bracket-period ([..]) 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 \fBch\fR is a collating element in the +current collation sequence with the associated collating symbol <ch>, the +expression [[.ch.]] will be treated as an RE matching the character sequence +\fBch\fR, while [ch] will be treated as an RE matching \fBc\fR or \fBh\fR. +Collating symbols will be recognized only inside bracket expressions. This +implies that the RE \fB[[.ch.]]*c\fR matches the first to fifth character in +the string 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. +.RE +.RS +4 +.TP +5. +An \fIequivalence class expression\fR 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 ([==]) +delimiters. For example, if a and b belong to the same equivalence class, then +[[=a=]b], [[==]b] and [[==]b] will each be equivalent to [ab]. If the collating +element does not belong to an equivalence class, the equivalence class +expression will be treated as a \fIcollating symbol\fR. +.RE +.RS +4 +.TP +6. +A \fIcharacter class expression\fR represents the set of characters +belonging to a character class, as defined in the \fBLC_CTYPE\fR 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 ([::]) delimiters. +.sp +The following character class expressions are supported in all locales: +.sp + +.sp +.TS +tab(); +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +. +\fB[:alnum:]\fR\fB[:cntrl:]\fR\fB[:lower:]\fR\fB[:space:]\fR +\fB[:alpha:]\fR\fB[:digit:]\fR\fB[:print:]\fR\fB[:upper:]\fR +\fB[:blank:]\fR\fB[:graph:]\fR\fB[:punct:]\fR\fB[:xdigit:]\fR +.TE + +In addition, character class expressions of the form: +.sp +.in +2 +.nf + \fB[:name:]\fR +.fi +.in -2 +.sp + +are recognized in those locales where the \fIname\fR keyword has been given a +\fBcharclass\fR definition in the \fBLC_CTYPE\fR category. +.RE +.RS +4 +.TP +7. +A \fIrange expression\fR 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 +(\fB-\fR). +.sp +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 \fBa\fR, while another defines it as a letter following \fBz\fR, +then the expression [-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. +.sp +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 [[=e=]\(mif] should be given as +[[=e=]e\(mif]. 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 (see \fBlocale\fR(5)) will +not be performed. For example, assuming that the character eszet is placed in +the collation sequence after \fBr\fR and \fBs\fR, but before \fBt\fR, and that +it maps to the sequence \fBss\fR for collation purposes, then the expression +[r\(mis] matches only \fBr\fR and \fBs\fR, but the expression [s\(mit] matches +\fBs\fR, \fBbeta\fR, or \fBt\fR. +.sp +The interpretation of range expressions where the ending range point is also +the starting range point of a subsequent range expression (for instance +[a\(mim\(mio]) is undefined. +.sp +The hyphen character will be treated as itself if it occurs first (after an +initial ^, if any) or last in the list, or as an ending range point in a range +expression. As examples, the expressions [\(miac] and [ac\(mi] are equivalent +and match any of the characters \fBa\fR, \fBc\fR, or \fB\(mi;\fR [^\(miac] and +[^ac\(mi] are equivalent and match any characters except \fBa\fR, \fBc\fR, or +\(mi; the expression [%\(mi\|\(mi] matches any of the characters between % and +\(mi inclusive; the expression [\(mi\|\(mi@] matches any of the characters +between \(mi and @ inclusive; and the expression [a\(mi\|\(mi@] is invalid, +because the letter \fBa\fR follows the symbol \(mi 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: +[][.\(mi.]\(mi0], which matches either a right bracket or any character or +collating element that collates between hyphen and 0, inclusive. +.sp +If a bracket expression must specify both \(mi and ], the ] must be placed +first (after the ^, if any) and the \(mi last within the bracket expression. +.RE +.sp +.LP +Note: Latin-1 characters such as \(ga or ^ are not printable in some locales, +for example, the \fBja\fR locale. +.SS "BREs Matching Multiple Characters" +.sp +.LP +The following rules can be used to construct BREs matching multiple characters +from BREs matching a single character: +.RS +4 +.TP +1. +The concatenation of BREs matches the concatenation of the strings matched +by each component of the BRE. +.RE +.RS +4 +.TP +2. +A \fIsubexpression\fR can be defined within a BRE by enclosing it between +the character pairs \e( and \e) . Such a subexpression matches whatever it +would have matched without the \e( and \e), except that anchoring within +subexpressions is optional behavior; see \fBBRE Expression Anchoring\fR, below. +Subexpressions can be arbitrarily nested. +.RE +.RS +4 +.TP +3. +The \fIback-reference\fR expression \e\fIn\fR matches the same (possibly +empty) string of characters as was matched by a subexpression enclosed between +\e( and \e) preceding the \e\fIn\fR. The character \fIn\fR must be a digit from +1 to 9 inclusive, \fIn\fRth subexpression (the one that begins with the +\fIn\fRth \e( and ends with the corresponding paired \e)\|). The expression is +invalid if less than \fIn\fR subexpressions precede the \e\fIn\fR. For example, +the expression \|^\e(.*\e)\e1$ matches a line consisting of two adjacent +appearances of the same string, and the expression \e(a\e)*\e1 fails to match +\fBa\fR. 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. The following is a valid BRE with ten +subexpressions: +.sp +.in +2 +.nf +\fB\e(\e(\e(ab\e)*c\e)*d\e)\e(ef\e)*\e(gh\e)\e{2\e}\e(ij\e)*\e(kl\e)*\e(mn\e)*\e(op\e)*\e(qr\e)*\fR +.fi +.in -2 +.sp + +.RE +.RS +4 +.TP +4. +When a BRE matching a single character, a subexpression or a back-reference +is followed by the special character asterisk (*), together with that asterisk +it matches what zero or more consecutive occurrences of the BRE would match. +For example, \fB[ab]*\fR \fBand\fR \fB[ab][ab]\fR are equivalent when matching +the string \fBab\fR. +.RE +.RS +4 +.TP +5. +When a BRE matching a single character, a subexpression, or a back-reference +is followed by an \fIinterval expression\fR of the format \e{\fIm\fR\e}, +\e{\fIm\fR,\e} or \e{\fIm\fR,\fIn\fR\e}, together with that interval expression +it matches what repeated consecutive occurrences of the BRE would match. The +values of \fIm\fR and \fIn\fR will be decimal integers in the range 0 \(<= +\fIm\fR \(<= \fIn\fR \(<= {\fBRE_DUP_MAX\fR}, where \fIm\fR specifies the exact +or minimum number of occurrences and \fIn\fR specifies the maximum number of +occurrences. The expression \e{\fIm\fR\e} matches exactly \fIm\fR occurrences +of the preceding BRE, \e{\fIm\fR,\e} matches at least \fIm\fR occurrences and +\e{\fIm,n\fR\e} matches any number of occurrences between \fIm\fR and \fIn\fR, +inclusive. +.sp +For example, in the string \fBabababccccccd\fR, the BRE c\e{3\e} is matched by +characters seven to nine, the BRE \e(ab\e)\e{4,\e} is not matched at all and +the BRE c\e{1,3\e}d is matched by characters ten to thirteen. +.RE +.sp +.LP +The behavior of multiple adjacent duplication symbols \fB(\fR \fB*\fR \fB\fR +and intervals) produces undefined results. +.SS "BRE Precedence" +.sp +.LP +The order of precedence is as shown in the following table: +.sp +.in +2 +.nf + +.fi +.in -2 +.sp + +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBBRE Precedence (from high to low)\fR +collation-related bracket symbols[= =] [: :] [. .] +escaped characters\e<\fIspecial character\fR> +bracket expression[ ] +subexpressions/back-references\e( \e) \e\fIn\fR +single-character-BRE duplication* \e{\fIm\fR,\fIn\fR\e} +concatenation +anchoring^ $ +.TE + +.SS "BRE Expression Anchoring" +.sp +.LP +A BRE can be limited to matching strings that begin or end a line; this is +called \fIanchoring\fR. The circumflex and dollar sign special characters will +be considered BRE anchors in the following contexts: +.RS +4 +.TP +1. +A circumflex \fB(\fR \fB^\fR \fB)\fR 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 ^ab matches \fBab\fR in the string \fBabcdef,\fR but fails to match in the +string \fBcdefab\fR. A portable BRE must escape a leading circumflex in a +subexpression to match a literal circumflex. +.RE +.RS +4 +.TP +2. +A dollar sign \fB(\fR \fB$\fR \fB)\fR 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. +.RE +.RS +4 +.TP +3. +A BRE anchored by both \fB^\fR and \fB$\fR matches only an entire string. +For example, the BRE \fB^abcdef$\fR matches strings consisting only of +\fBabcdef\fR. +.RE +.RS +4 +.TP +4. +\fB^\fR and \fB$\fR are not special in subexpressions. +.RE +.sp +.LP +Note: The Solaris implementation does not support anchoring in BRE +subexpressions. +.SH EXTENDED REGULAR EXPRESSIONS +.sp +.LP +The rules specififed for BREs apply to Extended Regular Expressions (EREs) with +the following exceptions: +.RS +4 +.TP +.ie t \(bu +.el o +The characters \fB|\fR, \fB+\fR, and \fB?\fR have special meaning, as defined +below. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fB{\fR and \fB}\fR characters, when used as the duplication operator, are +not preceded by backslashes. The constructs \fB\e{\fR and \fB\e}\fR simply +match the characters \fB{\fR and \fB}\fR, respectively. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The back reference operator is not supported. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Anchoring (\fB^$\fR) is supported in subexpressions. +.RE +.SS "EREs Matching a Single Character" +.sp +.LP +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 \fIERE\fR \fImatching\fR \fIa\fR +\fIsingle\fR \fIcharacter\fR enclosed in parentheses matches the same as the +ERE without parentheses would have matched. +.SS "ERE Ordinary Characters" +.sp +.LP +An \fIordinary character\fR 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 \fBERE\fR \fBSpecial\fR \fBCharacters\fR below. +The interpretation of an ordinary character preceded by a backslash (\fB\e\fR) +is undefined. +.SS "ERE Special Characters" +.sp +.LP +An \fIERE\fR \fIspecial\fR \fIcharacter\fR 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: +.sp +.ne 2 +.mk +.na +\fB\&. [ \e (\fR +.ad +.RS 14n +.rt +The period, left-bracket, backslash, and left-parenthesis are special except +when used in a bracket expression (see \fBRE Bracket Expression\fR, above). +Outside a bracket expression, a left-parenthesis immediately followed by a +right-parenthesis produces undefined results. +.RE + +.sp +.ne 2 +.mk +.na +\fB)\fR +.ad +.RS 14n +.rt +The right-parenthesis is special when matched with a preceding +left-parenthesis, both outside a bracket expression. +.RE + +.sp +.ne 2 +.mk +.na +\fB* + ? {\fR +.ad +.RS 14n +.rt +The asterisk, plus-sign, question-mark, and left-brace are special except when +used in a bracket expression (see \fBRE Bracket Expression\fR, above). Any of +the following uses produce undefined results: +.RS +4 +.TP +.ie t \(bu +.el o +if these characters appear first in an ERE, or immediately following a +vertical-line, circumflex or left-parenthesis +.RE +.RS +4 +.TP +.ie t \(bu +.el o +if a left-brace is not part of a valid interval expression. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB|\fR +.ad +.RS 14n +.rt +The vertical-line is special except when used in a bracket expression (see +\fBRE Bracket Expression\fR, above). 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. +.RE + +.sp +.ne 2 +.mk +.na +\fB^\fR +.ad +.RS 14n +.rt +The circumflex is special when used: +.RS +4 +.TP +.ie t \(bu +.el o +as an anchor (see \fBERE Expression Anchoring\fR, below). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +as the first character of a bracket expression (see \fBRE Bracket +Expression\fR, above). +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB$\fR +.ad +.RS 14n +.rt +The dollar sign is special when used as an anchor. +.RE + +.SS "Periods in EREs" +.sp +.LP +A period (\fB\&.\fR), when used outside a bracket expression, is an ERE that +matches any character in the supported character set except NUL. +.SS "ERE Bracket Expression" +.sp +.LP +The rules for ERE Bracket Expressions are the same as for Basic Regular +Expressions; see \fBRE Bracket Expression\fR, above). +.SS "EREs Matching Multiple Characters" +.sp +.LP +The following rules will be used to construct EREs matching multiple characters +from EREs matching a single character: +.RS +4 +.TP +1. +A \fIconcatenation\fR \fIof\fR \fIEREs\fR 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 \fBcd\fR and the ERE \fB(cd)\fR +are matched by the third and fourth character of the string \fBabcdefabcdef\fR. +.RE +.RS +4 +.TP +2. +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by the special character plus-sign (+), together with that plus-sign +it matches what one or more consecutive occurrences of the ERE would match. For +example, the ERE \fBb+(bc)\fR matches the fourth to seventh characters in the +string \fBacabbbcde;\fR \fB[ab]\fR + and \fB[ab][ab]*\fR are equivalent. +.RE +.RS +4 +.TP +3. +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by the special character asterisk (\fB*\fR), together with that +asterisk it matches what zero or more consecutive occurrences of the ERE would +match. For example, the ERE \fBb*c\fR matches the first character in the string +\fBcabbbcde,\fR and the ERE \fBb*cd\fR matches the third to seventh characters +in the string \fBcabbbcdebbbbbbcdbc\fR. And, \fB[ab]*\fR and \fB[ab][ab]\fR are +equivalent when matching the string \fBab\fR. +.RE +.RS +4 +.TP +4. +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by the special character question-mark (\fB?\fR), together with that +question-mark it matches what zero or one consecutive occurrences of the ERE +would match. For example, the ERE \fBb?c\fR matches the second character in the +string \fBacabbbcde\fR. +.RE +.RS +4 +.TP +5. +When an ERE matching a single character or an ERE enclosed in parentheses is +followed by an \fIinterval\fR \fIexpression\fR of the format {\fIm\fR}, +{\fIm\fR,} or {\fIm\fR,\fIn\fR}, together with that interval expression it +matches what repeated consecutive occurrences of the ERE would match. The +values of \fIm\fR and \fIn\fR will be decimal integers in the range 0 \(<= +\fIm\fR \(<= \fIn\fR \(<= \fB{RE_DUP_MAX}\fR, where \fIm\fR specifies the exact +or minimum number of occurrences and \fIn\fR specifies the maximum number of +occurrences. The expression {\fIm\fR} matches exactly \fIm\fR occurrences of +the preceding ERE, {\fIm\fR,} matches at least \fIm\fR occurrences and +{\fIm\fR,\fIn\fR} matches any number of occurrences between \fIm\fR and +\fIn\fR, inclusive. +.RE +.sp +.LP +For example, in the string \fBabababccccccd\fR the ERE c{3} is matched by +characters seven to nine and the ERE (ab){2,} is matched by characters one to +six. +.sp +.LP +The behavior of multiple adjacent duplication symbols \fB(\fR+\fB,\fR \fB*\fR, +\fB?\fR and intervals) produces undefined results. +.SS "ERE Alternation" +.sp +.LP +Two EREs separated by the special character vertical-line (|) match a string +that is matched by either. For example, the ERE a((bc)|d) matches the string +abc and the string 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" +.sp +.LP +The order of precedence will be as shown in the following table: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBERE Precedence (from high to low)\fR +collation-related bracket symbols[= =] [: :] [. .] +escaped characters\e<\fIspecial character\fR> +bracket expression[ ] +grouping( ) +single-character-ERE duplication* + ? {\fIm\fR,\fIn\fR} +concatenation +anchoring^ $ +alternation| +.TE + +.sp +.LP +For example, the ERE \fBabba\||\|cde\fR matches either the string \fBabba\fR or +the string \fBcde\fR (rather than the string \fBabbade\fR or \fBabbcde\fR, +because concatenation has a higher order of precedence than alternation). +.SS "ERE Expression Anchoring" +.sp +.LP +An ERE can be limited to matching strings that begin or end a line; this is +called \fIanchoring\fR. The circumflex and dollar sign special characters are +considered ERE anchors when used anywhere outside a bracket expression. This +has the following effects: +.RS +4 +.TP +1. +A circumflex (^) 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 ^ab and (^ab) match ab in the string abcdef, but +fail to match in the string cdefab, and the ERE a^b is valid, but can never +match because the \fBa\fR prevents the expression ^b from matching starting at +the first character. +.RE +.RS +4 +.TP +2. +A dollar sign \fB(\fR \fB$\fR \fB)\fR 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 ef$ and (ef$) match ef in the +string abcdef, but fail to match in the string cdefab, and the ERE e$f is +valid, but can never match because the \fBf\fR prevents the expression e$ from +matching ending at the last character. +.RE +.SH SEE ALSO +.sp +.LP +\fBlocaledef\fR(1), \fBregcomp\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBlocale\fR(5), \fBregexp\fR(5) diff --git a/usr/src/man/man5/regexp.5 b/usr/src/man/man5/regexp.5 new file mode 100644 index 0000000000..b72342f820 --- /dev/null +++ b/usr/src/man/man5/regexp.5 @@ -0,0 +1,786 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text +.\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" 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] +.TH regexp 5 "20 May 2002" "SunOS 5.11" "Standards, Environments, and Macros" +.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(5) 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 +.mk +.na +\fB1.1\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB1.2\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fBa.\fR +.ad +.RS 6n +.rt +\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 +.mk +.na +\fBb.\fR +.ad +.RS 6n +.rt +^ (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 +.mk +.na +\fBc.\fR +.ad +.RS 6n +.rt +\fB$\fR (dollar sign), which is special at the \fBend\fR of an \fIentire\fR RE +(see 4.2 below). +.RE + +.sp +.ne 2 +.mk +.na +\fBd.\fR +.ad +.RS 6n +.rt +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 +.mk +.na +\fB1.3\fR +.ad +.RS 7n +.rt +A period (\fB\&.\fR) is a one-character RE that matches any character except +new-line. +.RE + +.sp +.ne 2 +.mk +.na +\fB1.4\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB2.1\fR +.ad +.RS 7n +.rt +A one-character RE is a RE that matches whatever the one-character RE matches. +.RE + +.sp +.ne 2 +.mk +.na +\fB2.2\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB2.3\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB2.4\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB2.5\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB2.6\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB3.1\fR +.ad +.RS 7n +.rt +\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 +.mk +.na +\fB3.2\fR +.ad +.RS 7n +.rt +\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 +.mk +.na +\fB4.1\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB4.2\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB4.3\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB\fBGETC\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBPEEKC\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBUNGETC\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBRETURN(\fR\fIptr\fR\fB)\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBERROR(\fR\fIval\fR\fB)\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB11\fR +.ad +.RS 6n +.rt +range endpoint too large. +.RE + +.sp +.ne 2 +.mk +.na +\fB16\fR +.ad +.RS 6n +.rt +bad number. +.RE + +.sp +.ne 2 +.mk +.na +\fB25\fR +.ad +.RS 6n +.rt +\fB\e\fR \fIdigit\fR out of range. +.RE + +.sp +.ne 2 +.mk +.na +\fB36\fR +.ad +.RS 6n +.rt +illegal or missing delimiter. +.RE + +.sp +.ne 2 +.mk +.na +\fB41\fR +.ad +.RS 6n +.rt +no remembered search string. +.RE + +.sp +.ne 2 +.mk +.na +\fB42\fR +.ad +.RS 6n +.rt +\fB\e( \e)\fR imbalance. +.RE + +.sp +.ne 2 +.mk +.na +\fB43\fR +.ad +.RS 6n +.rt +too many \fB\e(\fR\&. +.RE + +.sp +.ne 2 +.mk +.na +\fB44\fR +.ad +.RS 6n +.rt +more than 2 numbers given in \fB\e{ \e}\fR\&. +.RE + +.sp +.ne 2 +.mk +.na +\fB45\fR +.ad +.RS 6n +.rt +\fB}\fR expected after \fB\e\fR\&. +.RE + +.sp +.ne 2 +.mk +.na +\fB46\fR +.ad +.RS 6n +.rt +first number exceeds second in \fB\e{ \e}\fR\&. +.RE + +.sp +.ne 2 +.mk +.na +\fB49\fR +.ad +.RS 6n +.rt +\fB[ ]\fR imbalance. +.RE + +.sp +.ne 2 +.mk +.na +\fB50\fR +.ad +.RS 6n +.rt +regular expression overflow. +.RE + +.SH SEE ALSO +.sp +.LP +\fBregex\fR(5) diff --git a/usr/src/man/man5/resource_controls.5 b/usr/src/man/man5/resource_controls.5 new file mode 100644 index 0000000000..db47946ede --- /dev/null +++ b/usr/src/man/man5/resource_controls.5 @@ -0,0 +1,1046 @@ +'\" 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 resource_controls 5 "2 Jul 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +resource_controls \- resource controls available through project database +.SH DESCRIPTION +.sp +.LP +The resource controls facility is configured through the project database. See +\fBproject\fR(4). You can set and modify resource controls through the +following utilities: +.RS +4 +.TP +.ie t \(bu +.el o +\fBprctl\fR(1) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBprojadd\fR(1M) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBprojmod\fR(1M) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBrctladm\fR(1M) +.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(1M) and \fBpoolcfg\fR(1M) 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 +.mk +.na +\fB\fBprocess.max-address-space\fR\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 +.mk +.na +\fB\fBprocess.max-core-size\fR\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 +.mk +.na +\fB\fBprocess.max-cpu-time\fR\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 +.mk +.na +\fB\fBprocess.max-data-size\fR\fR +.ad +.sp .6 +.RS 4n +Maximum heap memory available to this process, expressed as a number of bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprocess.max-file-descriptor\fR\fR +.ad +.sp .6 +.RS 4n +Maximum file descriptor index available to this process, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprocess.max-file-size\fR\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 +.mk +.na +\fB\fBprocess.max-msg-messages\fR\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 +.mk +.na +\fB\fBprocess.max-msg-qbytes\fR\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 +.mk +.na +\fB\fBprocess.max-port-events\fR\fR +.ad +.sp .6 +.RS 4n +Maximum allowable number of events per event port, expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprocess.max-sem-nsems\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphores allowed per semaphore set, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprocess.max-sem-ops\fR\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 +.mk +.na +\fB\fBprocess.max-stack-size\fR\fR +.ad +.sp .6 +.RS 4n +Maximum stack memory segment available to this process, expressed as a number +of bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.cpu-caps\fR\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 +.mk +.na +\fB\fBproject.cpu-shares\fR\fR +.ad +.sp .6 +.RS 4n +Number of CPU shares granted to a project for use with the fair share scheduler +(see \fBFSS\fR(7)). The unit used is the number of shares (an integer). This +resource control does not support the \fBsyslog\fR action. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-contracts\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of contracts allowed in a project, expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-crypto-memory\fR\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 +.mk +.na +\fB\fBproject.max-locked-memory\fR\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 +.mk +.na +\fB\fBproject.max-lwps\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of LWPs simultaneously available to a project, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-msg-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of message queue IDs allowed for a project, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-port-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum allowable number of event ports, expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-sem-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphore IDs allowed for a project, expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-shm-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of shared memory IDs allowed for a project, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.max-shm-memory\fR\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 +.mk +.na +\fB\fBproject.max-tasks\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of tasks allowable in a project, expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBproject.pool\fR\fR +.ad +.sp .6 +.RS 4n +Binds a specified resource pool with a project. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrcap.max-rss\fR\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 +.mk +.na +\fB\fBtask.max-cpu-time\fR\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 +.mk +.na +\fB\fBtask.max-lwps\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of LWPs simultaneously available to this task's processes, +expressed as an integer. +.RE + +.sp +.LP +The following zone-wide resource controls are available: +.sp +.ne 2 +.mk +.na +\fB\fBzone.cpu-cap\fR\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 +.mk +.na +\fB\fBzone.cpu-shares\fR\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 +.mk +.na +\fB\fBzone.max-locked-memory\fR\fR +.ad +.sp .6 +.RS 4n +Total amount of physical locked memory available to a zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBzone.max-lwps\fR\fR +.ad +.sp .6 +.RS 4n +Enhances resource isolation by preventing too many LWPs in one zone from +affecting other zones. A zone's total LWPs can be further subdivided among +projects within the zone within the zone by using \fBproject.max-lwps\fR +entries. Expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBzone.max-msg-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of message queue IDs allowed for a zone, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBzone.max-sem-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of semaphore IDs allowed for a zone, expressed as an integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBzone.max-shm-ids\fR\fR +.ad +.sp .6 +.RS 4n +Maximum number of shared memory IDs allowed for a zone, expressed as an +integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBzone.max-shm-memory\fR\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 +.mk +.na +\fB\fBzone.max-swap\fR\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(5). +.SS "Units Used in Resource Controls" +.sp +.LP +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(1M), and \fBprojmod\fR(1M) commands. You cannot +use unit modifiers in the project database itself. +.SS "Resource Control Values and Privilege Levels" +.sp +.LP +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 +.mk +.na +\fB\fBbasic\fR\fR +.ad +.sp .6 +.RS 4n +Can be modified by the owner of the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprivileged\fR\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 +.mk +.na +\fB\fBsystem\fR\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" +.sp +.LP +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(1M) 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 +.mk +.na +\fB\fBnone\fR\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 threshhold is not affected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdeny\fR\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 +.mk +.na +\fB\fBsignal=\fR\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(1M).) 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 +.mk +.na +\fB\fBSIGABRT\fR\fR +.ad +.sp .6 +.RS 4n +Terminate the process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGHUP\fR\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 +.mk +.na +\fB\fBSIGTERM\fR\fR +.ad +.sp .6 +.RS 4n +Terminate the process. Termination signal sent by software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGKILL\fR\fR +.ad +.sp .6 +.RS 4n +Terminate the process and kill the program. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGSTOP\fR\fR +.ad +.sp .6 +.RS 4n +Stop the process. Job control signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGXRES\fR\fR +.ad +.sp .6 +.RS 4n +Resource control limit exceeded. Generated by resource control facility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGXFSZ\fR\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 +.mk +.na +\fB\fBSIGXCPU\fR\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" +.sp +.LP +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(1M) 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 +.mk +.na +\fB\fBlowerable\fR\fR +.ad +.sp .6 +.RS 4n +Superuser privileges are not required to lower the privileged values for this +control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBno-deny\fR\fR +.ad +.sp .6 +.RS 4n +Even when threshold values are exceeded, access to the resource is never +denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcpu-time\fR\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 +.mk +.na +\fB\fBseconds\fR\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" +.sp +.LP +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 +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBprctl\fR(1), \fBpooladm\fR(1M), \fBpoolcfg\fR(1M), \fBprojadd\fR(1M), +\fBprojmod\fR(1M), \fBrctladm\fR(1M), \fBsetrctl\fR(2), +\fBrctlblk_set_value\fR(3C), \fBlibpool\fR(3LIB), \fBproject\fR(4), +\fBattributes\fR(5), \fBFSS\fR(7) +.sp +.LP +\fISystem Administration Guide: Virtualization Using the Solaris Operating +System\fR diff --git a/usr/src/man/man5/smf.5 b/usr/src/man/man5/smf.5 new file mode 100644 index 0000000000..18b9b6f6bf --- /dev/null +++ b/usr/src/man/man5/smf.5 @@ -0,0 +1,545 @@ +'\" 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 5 "6 Jul 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.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(1M) 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(1M) 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 +.mk +.na +\fB\fBrequire_all\fR\fR +.ad +.RS 16n +.rt +Satisfied when all cited services are running (online or degraded), or when all +indicated files are present. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrequire_any\fR\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fBoptional_all\fR\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fB\fBexclude_all\fR\fR +.ad +.RS 16n +.rt +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(1M), and modified with \fBsvccfg\fR(1M). +.SS "Restarters" +.sp +.LP +Each service is managed by a restarter. The master restarter, +\fBsvc.startd\fR(1M) 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(1M) 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(1M) 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(1M) 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(5). +.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(5) for a more +complete description of the method conventions for \fBsvc.startd\fR(1M) 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(1M) manual +page. +.sp +.LP +The methods for a service can be listed and modified using the \fBsvccfg\fR(1M) +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 +.mk +.na +\fB\fBUNINITIALIZED\fR\fR +.ad +.RS 17n +.rt +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(1M) or the appropriate restarter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBOFFLINE\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBONLINE\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBDEGRADED\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBMAINTENANCE\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBDISABLED\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBLEGACY-RUN\fR\fR +.ad +.RS 17n +.rt +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(4) 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(5). +.SS "General Property Group" +.sp +.LP +The \fBgeneral\fR property group applies to all service instances. It includes +the following properties: +.sp +.ne 2 +.mk +.na +\fBenabled (boolean)\fR +.ad +.RS 21n +.rt +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 +.mk +.na +\fBrestarter (fmri)\fR +.ad +.RS 21n +.rt +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 +.mk +.na +\fB\fBinitial\fR\fR +.ad +.RS 15n +.rt +Initial configuration of the instance created by the administrator or produced +during package installation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBlast_import\fR\fR +.ad +.RS 15n +.rt +Configuration as prescribed by the manifest of the service that is taken during +\fBsvccfg\fR(1M) import operation. This snapshot provides a baseline for +determining property customization. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprevious\fR\fR +.ad +.RS 15n +.rt +Current configuration captured when an administrative undo operation is +performed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrunning\fR\fR +.ad +.RS 15n +.rt +The running configuration of the instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBstart\fR\fR +.ad +.RS 15n +.rt +Configuration captured during a successful transition to the online state. +.RE + +.sp +.LP +The \fBsvccfg\fR(1M) 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(1M). 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(1M). +.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 +.mk +.na +\fB\fBmanifests\fR\fR +.ad +.RS 13n +.rt +Files that contain the complete set of properties associated with a specific +set of services or service instances. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBprofiles\fR\fR +.ad +.RS 13n +.rt +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(1M) command. See \fBservice_bundle\fR(4) 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 +.mk +.na +\fB\fB/etc/rcS.d\fR\fR +.ad +.RS 14n +.rt +milestone/single-user:default +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rc2.d\fR\fR +.ad +.RS 14n +.rt +milestone/multi-user:default +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/rc3.d\fR\fR +.ad +.RS 14n +.rt +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(1M) command. No error diagnosis or restart is done for these +programs. +.SH SEE ALSO +.sp +.LP +\fBsvcs\fR(1), \fBinetd\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), +\fBsvc.configd\fR(1M), \fBsvc.startd\fR(1M), \fBexec\fR(2), \fBfork\fR(2), +\fBlibscf\fR(3LIB), \fBstrftime\fR(3C), \fBcontract\fR(4), +\fBservice_bundle\fR(4), \fBsmf_bootstrap\fR(5), \fBsmf_method\fR(5), +\fBsmf_restarter\fR(5), \fBsmf_security\fR(5) diff --git a/usr/src/man/man5/smf_bootstrap.5 b/usr/src/man/man5/smf_bootstrap.5 new file mode 100644 index 0000000000..77f82852d0 --- /dev/null +++ b/usr/src/man/man5/smf_bootstrap.5 @@ -0,0 +1,124 @@ +'\" 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 5 "25 Sep 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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(1M) 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(1M) 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(1M) is invoked, the +service manifest is imported. +.sp +.LP +When \fBpkgrm\fR(1M) 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(1M) or \fBpkgrm\fR(1M), 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(5) 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(5) 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(4) 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(1M) 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(4) 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(1M) 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(1M) 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(1M). +.SH SEE ALSO +.sp +.LP +\fBpkgadd\fR(1M), \fBpkgrm\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), +\fBsvc.startd\fR(1M), \fBlibscf\fR(3LIB), \fBservice_bundle\fR(4), +\fBattributes\fR(5), \fBsmf\fR(5), \fBsmf_security\fR(5) +.SH NOTES +.sp +.LP +The present version of \fBsmf\fR(5) does not support multiple repositories. diff --git a/usr/src/man/man5/smf_method.5 b/usr/src/man/man5/smf_method.5 new file mode 100644 index 0000000000..983f1aa8ac --- /dev/null +++ b/usr/src/man/man5/smf_method.5 @@ -0,0 +1,611 @@ +'\" 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_method 5 "20 May 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +smf_method \- service management framework conventions for methods +.SH DESCRIPTION +.sp +.LP +The class of services managed by \fBsvc.startd\fR(1M) in the service management +framework, \fBsmf\fR(5), consists of applications that fit a simple +\fBfork\fR(2)-\fBexec\fR(2) model. The \fBsvc.startd\fR(1M) master daemon and +other restarters support the \fBfork\fR(2)-\fBexec\fR(2) model, potentially +with additional capabilities. The \fBsvc.startd\fR(1M) 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" +.sp +.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(1M) 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" +.sp +.LP +The restarter provides four environment variables to the method that determine +the context in which the method is invoked. +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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" +.sp +.LP +A method is defined minimally by three properties in a propertygroup of type +\fBmethod\fR. +.sp +.LP +These properties are: +.sp +.ne 2 +.mk +.na +\fBexec (\fIastring\fR)\fR +.ad +.RS 27n +.rt +Method executable string. +.RE + +.sp +.ne 2 +.mk +.na +\fBtimeout_seconds (\fIcount\fR)\fR +.ad +.RS 27n +.rt +Number of seconds before method times out. See the \fBTimeouts\fR section for +more detail. +.RE + +.sp +.ne 2 +.mk +.na +\fBtype (\fIastring\fR)\fR +.ad +.RS 27n +.rt +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" +.sp +.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(1M), does not support the following +method expansions. +.sp +.ne 2 +.mk +.na +\fB\fB%%\fR\fR +.ad +.sp .6 +.RS 4n +% +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%r\fR\fR +.ad +.sp .6 +.RS 4n +Name of the restarter, such as \fBsvc.startd\fR +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB%s\fR\fR +.ad +.sp .6 +.RS 4n +Name of the service +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%i\fR\fR +.ad +.sp .6 +.RS 4n +Name of the instance +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\fR\fB%f\fR\fR +.ad +.sp .6 +.RS 4n +FMRI of the instance +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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" +.sp +.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 +tab(); +lw(1.74i) lw(.9i) lw(2.86i) +lw(1.74i) lw(.9i) lw(2.86i) +. +\fBSMF_EXIT_OK\fR\fB0\fRT{ +Method exited, performing its operation successfully. +T} +\fBSMF_EXIT_ERR_FATAL\fR\fB95\fRT{ +Method failed fatally and is unrecoverable without administrative intervention. +T} +\fBSMF_EXIT_ERR_CONFIG\fR\fB96\fRT{ +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\fRT{ +Method has been mistakenly invoked outside the \fBsmf\fR(5) facility. Services that depend on \fBsmf\fR(5) capabilities should exit with this status value. +T} +\fBSMF_EXIT_ERR_PERM\fR\fB100\fRT{ +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\fRT{ +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" +.sp +.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" +.sp +.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(5) 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" +.sp +.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 +.mk +.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 +.mk +.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 +.mk +.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(4). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuser\fR\fR +.ad +.sp .6 +.RS 4n +The user ID in numeric or text form. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgroup\fR\fR +.ad +.sp .6 +.RS 4n +The group ID in numeric or text form. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fBprivileges\fR\fR +.ad +.sp .6 +.RS 4n +An optional string specifying the privilege set as defined in +\fBprivileges\fR(5). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBlimit_privileges\fR\fR +.ad +.sp .6 +.RS 4n +An optional string specifying the limit privilege set as defined in +\fBprivileges\fR(5). +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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(1M). Most restarters supply a default. Setting this +property overrides local customizations to the global core pattern. +.RE + +.sp +.ne 2 +.mk +.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 +.mk +.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(4) 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 +.mk +.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 +.mk +.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 +.sp +.ne 2 +.mk +.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 +.mk +.na +\fB\fB/usr/include/libscf.h\fR\fR +.ad +.sp .6 +.RS 4n +Definitions of exit status codes. +.RE + +.SH SEE ALSO +.sp +.LP +\fBzonename\fR(1), \fBcoreadm\fR(1M), \fBinetd\fR(1M), \fBsvccfg\fR(1M), +\fBsvc.startd\fR(1M), \fBexec\fR(2), \fBfork\fR(2), +\fBgetdefaultproj\fR(3PROJECT), \fBexec_attr\fR(4), \fBproject\fR(4), +\fBservice_bundle\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5), +\fBrbac\fR(5), \fBsmf\fR(5), \fBsmf_bootstrap\fR(5), \fBzones\fR(5) +.SH NOTES +.sp +.LP +The present version of \fBsmf\fR(5) 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/man5/smf_restarter.5 b/usr/src/man/man5/smf_restarter.5 new file mode 100644 index 0000000000..ff041fe8d2 --- /dev/null +++ b/usr/src/man/man5/smf_restarter.5 @@ -0,0 +1,126 @@ +'\" 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_restarter 5 "23 May 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +smf_restarter \- service management facility conventions for restarters +.SH DESCRIPTION +.sp +.LP +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" +.sp +.LP +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 +.mk +.na +\fB\fBenabled\fR\fR +.ad +.RS 19n +.rt +This is a required property. If set, the restarter of an instance attempts to +maintain availability of the service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrestarter\fR\fR +.ad +.RS 19n +.rt +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(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsingle_instance\fR\fR +.ad +.RS 19n +.rt +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. +.RE + +.SS "Service Reporting" +.sp +.LP +All restarters report status using the \fBrestarter\fR property group, which +includes the following properties: +.sp +.ne 2 +.mk +.na +\fB\fBnext_state\fR\fR +.ad +.RS 19n +.rt +The current state and next state, if currently in transition, for instances +stored in these properties. See \fBsmf\fR(5) for a description of the potential +states. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauxiliary_state\fR\fR +.ad +.RS 19n +.rt +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 +.mk +.na +\fB\fBstate_timestamp\fR\fR +.ad +.RS 19n +.rt +The time when the current state was reached. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcontract\fR\fR +.ad +.RS 19n +.rt +The primary process contract ID, if any, under which the service instance is +executing. +.RE + +.SH SEE ALSO +.sp +.LP +\fBsvcs\fR(1), \fBsvc.startd\fR(1M), \fBservice_bundle\fR(4), \fBsmf\fR(5), +\fBsmf_method\fR(5) diff --git a/usr/src/man/man5/smf_security.5 b/usr/src/man/man5/smf_security.5 new file mode 100644 index 0000000000..e9469ddca4 --- /dev/null +++ b/usr/src/man/man5/smf_security.5 @@ -0,0 +1,261 @@ +'\" 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 5 "20 May 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +smf_security \- service management facility security behavior +.SH DESCRIPTION +.sp +.LP +The configuration subsystem for the service management facility, \fBsmf\fR(5), +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(4) and \fBprof_attr\fR(4). See \fBrbac\fR(5). +.sp +.LP +The following authorization is used to manipulate services and service +instances. +.sp +.ne 2 +.mk +.na +\fB\fBsolaris.smf.modify\fR\fR +.ad +.RS 22n +.rt +Authorized to add, delete, or modify services, service instances, or their +properties, and to read protected property values. +.RE + +.SS "Property Group Authorizations" +.sp +.LP +The \fBsmf\fR(5) 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(5) 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(5). The following +basic authorizations, however, apply only to the core property group types: +.sp +.ne 2 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.na +\fB\fBmodify_authorization\fR\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fB\fBvalue_authorization\fR\fR +.ad +.RS 24n +.rt +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 +.mk +.na +\fB\fBread_authorization\fR\fR +.ad +.RS 24n +.rt +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" +.sp +.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(1M) archive command to create an archive of the +repository without protected property values. +.SS "Service Action Authorization" +.sp +.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 +.mk +.na +\fB\fBsolaris.smf.manage\fR\fR +.ad +.RS 22n +.rt +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" +.sp +.LP +Two rights profiles are included that offer grouped authorizations for +manipulating typical \fBsmf\fR(5) operations. +.sp +.ne 2 +.mk +.na +\fBService Management\fR +.ad +.RS 22n +.rt +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. +.sp +The service management profile is the minimum required to use the +\fBpkgadd\fR(1M) or \fBpkgrm\fR(1M) commands to add or remove software packages +that contain an inventory of services in its service manifest. +.RE + +.sp +.ne 2 +.mk +.na +\fBService Operator\fR +.ad +.RS 22n +.rt +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" +.sp +.LP +Remote repository servers can deny modification attempts due to additional +privilege checks. See NOTES. +.SH SEE ALSO +.sp +.LP +\fBauths\fR(1), \fBprofiles\fR(1), \fBpkgadd\fR(1M), \fBpkgrm\fR(1M), +\fBsvccfg\fR(1M), \fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBrbac\fR(5), +\fBsmf\fR(5) +.SH NOTES +.sp +.LP +The present version of \fBsmf\fR(5) 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/man5/smf_template.5 b/usr/src/man/man5/smf_template.5 new file mode 100644 index 0000000000..3a2f7c390c --- /dev/null +++ b/usr/src/man/man5/smf_template.5 @@ -0,0 +1,803 @@ +'\" 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 5 "10 Nov 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.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(1M)'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='1M' 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='1M' + 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 +\fBsvcs\fR(1), \fBsvccfg\fR(1M), \fBlibscf\fR(3LIB), \fBservice_bundle\fR(4), +\fBsmf\fR(5) diff --git a/usr/src/man/man5/standards.5 b/usr/src/man/man5/standards.5 new file mode 100644 index 0000000000..caba3a202d --- /dev/null +++ b/usr/src/man/man5/standards.5 @@ -0,0 +1,541 @@ +'\" 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 5 "14 Jan 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +.sp +.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 +tab(); +cw(1.25i) cw(3.3i) cw(.95i) +lw(1.25i) lw(3.3i) lw(.95i) +. +POSIX StandardDescriptionRelease +_ +POSIX.1-1988system interfaces and headersSunOS 4.1 +_ +POSIX.1-1990POSIX.1-1988 updateSolaris 2.0 +_ +POSIX.1b-1993realtime extensionsSolaris 2.4 +_ +POSIX.1c-1996threads extensionsSolaris 2.6 +_ +POSIX.2-1992shell and utilitiesSolaris 2.5 +_ +POSIX.2a-1992interactive shell and utilitiesSolaris 2.5 +_ +POSIX.1-2001T{ +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 +tab(); +cw(1.29i) cw(3.27i) cw(.93i) +cw(1.29i) cw(3.27i) cw(.93i) +. +X/Open CAE +_ + SpecificationDescriptionRelease +_ +XPG3T{ +superset of POSIX.1-1988 containing utilities from SVID3 +T}SunOS 4.1 +_ +XPG4T{ +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 +_ +XNS4sockets and XTI interfacesSolaris 2.6 +_ +SUSv2T{ +superset of SUS extended to support POSIX.1b-1993, POSIX.1c-1996, and ISO/IEC 9899 (C Standard) Amendment 1 +T}Solaris 7 +_ +XNS5T{ +superset and LP64-clean derivative of XNS4. +T}Solaris 7 +_ +SUSv3same as POSIX.1-2001Solaris 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" +.sp +.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 utilitues 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 +.mk +.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 +.mk +.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 +.mk +.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 + +.sp +.LP +When an application uses \fBexeclp()\fR or \fBexecvp()\fR (see \fBexec\fR(2)) +to execute a shell file, or uses \fBsystem\fR(3C), the shell used to interpret +the shell file depends on the standard to which the caller conforms: +.sp + +.sp +.TS +tab(); +cw(4.33i) cw(1.17i) +lw(4.33i) lw(1.17i) +. +StandardShell Used +_ +T{ +1989 ANSI C, 1990 ISO C, 1999 ISO C, POSIX.1 (1990-2001), SUS, SUSv2, SUSv3, XPG4 +T}\fB/usr/xpg4/bin/sh\fR +T{ +POSIX.1 (1988), SVID3, XPG3, no standard specified +T}\fB/usr/bin/sh\fR +.TE + +.SS "Feature Test Macros" +.sp +.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" +.sp +.LP +No feature test macros need to be defined to indicate that an application is a +conforming C application. +.SS "ANSI/ISO C++" +.sp +.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" +.sp +.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 +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +\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" +.sp +.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" +.sp +.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 +.mk +.na +\fBXPG3\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fBXPG4\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fBSUS (XPG4v2)\fR +.ad +.RS 16n +.rt +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 +.mk +.na +\fBSUSv2\fR +.ad +.RS 16n +.rt +The application must define \fB_XOPEN_SOURCE=500\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBSUSv3\fR +.ad +.RS 16n +.rt +The application must define \fB_XOPEN_SOURCE=600\fR. +.RE + +.SS "Compilation" +.sp +.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 suppports 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(5) 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 +_________________________________________________________________________ +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 +_________________________________________________________________________ +POSIX.1c-1996 c89 _POSIX_C_SOURCE=199506L +_________________________________________________________________________ +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" +.sp +.ne 2 +.mk +.na +\fB\fBc99\fR\fR +.ad +.RS 28n +.rt +\fB_XOPEN_SOURCE=600\fR +.RE + +.SH SEE ALSO +.sp +.LP +\fBcsh\fR(1), \fBksh\fR(1), \fBsh\fR(1), \fBexec\fR(2), \fBsysconf\fR(3C), +\fBsystem\fR(3C), \fBenviron\fR(5), \fBlf64\fR(5) diff --git a/usr/src/man/man5/sticky.5 b/usr/src/man/man5/sticky.5 new file mode 100644 index 0000000000..2846618079 --- /dev/null +++ b/usr/src/man/man5/sticky.5 @@ -0,0 +1,40 @@ +'\" 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 5 "1 Aug 2002" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +\fBchmod\fR(1), \fBchmod\fR(2), \fBchown\fR(2), \fBmkdir\fR(2), +\fBrename\fR(2), \fBunlink\fR(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/man5/tecla.5 b/usr/src/man/man5/tecla.5 new file mode 100644 index 0000000000..dd54aeba60 --- /dev/null +++ b/usr/src/man/man5/tecla.5 @@ -0,0 +1,4353 @@ +'\" 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 5 "20 May 2004" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +tecla, teclarc \- User interface provided by the tecla library. +.SH DESCRIPTION +.sp +.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 shell\fR 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" +.sp +.LP +In the rest of this man page, and also in all tecla configuration files, key +sequences are expressed as follows. +.sp +.ne 2 +.mk +.na +\fB\fB^A\fR or \fBC-a\fR\fR +.ad +.RS 13n +.rt +This is a 'CONTROL-A', entered by pressing the CONTROL key at the same time as +the 'A' key. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\E\fR or \fBM-\fR\fR +.ad +.RS 13n +.rt +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 +.mk +.na +\fBup\fR +.ad +.RS 13n +.rt +This refers to the up-arrow key. +.RE + +.sp +.ne 2 +.mk +.na +\fBdown\fR +.ad +.RS 13n +.rt +This refers to the down-arrow key. +.RE + +.sp +.ne 2 +.mk +.na +\fBleft\fR +.ad +.RS 13n +.rt +This refers to the left-arrow key. +.RE + +.sp +.ne 2 +.mk +.na +\fBright\fR +.ad +.RS 13n +.rt +This refers to the right-arrow key. +.RE + +.sp +.ne 2 +.mk +.na +\fBa\fR +.ad +.RS 13n +.rt +This is just a normal 'A' key. +.RE + +.SS "The Tecla Configuration File" +.sp +.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 +.mk +.na +\fBvi\fR +.ad +.RS 9n +.rt +Install key bindings like those of the \fBvi\fR editor. +.RE + +.sp +.ne 2 +.mk +.na +\fBemacs\fR +.ad +.RS 9n +.rt +Install key bindings like those of the \fBemacs\fR editor. This is the default. +.RE + +.sp +.ne 2 +.mk +.na +\fBnone\fR +.ad +.RS 9n +.rt +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" +.sp +.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" +.sp +.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" +.sp +.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 interpretted as a pattern to be matched. +Thus, cotinuing 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" +.sp +.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" +.sp +.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" +.sp +.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" +.sp +.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" +.sp +.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 +.mk +.na +\fBuser-interrupt\fR +.ad +.RS 30n +.rt +Send a SIGINT signal to the parent process. +.RE + +.sp +.ne 2 +.mk +.na +\fBsuspend\fR +.ad +.RS 30n +.rt +Suspend the parent process. +.RE + +.sp +.ne 2 +.mk +.na +\fBstop-output\fR +.ad +.RS 30n +.rt +Pause terminal output. +.RE + +.sp +.ne 2 +.mk +.na +\fBstart-output\fR +.ad +.RS 30n +.rt +Resume paused terminal output. +.RE + +.sp +.ne 2 +.mk +.na +\fBliteral-next\fR +.ad +.RS 30n +.rt +Arrange for the next character to be treated as a normal character. This allows +control characters to be entered. +.RE + +.sp +.ne 2 +.mk +.na +\fBcursor-right\fR +.ad +.RS 30n +.rt +Move the cursor one character right. +.RE + +.sp +.ne 2 +.mk +.na +\fBcursor-left\fR +.ad +.RS 30n +.rt +Move the cursor one character left. +.RE + +.sp +.ne 2 +.mk +.na +\fBinsert-mode\fR +.ad +.RS 30n +.rt +Toggle between insert mode and overwrite mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBbeginning-of-line\fR +.ad +.RS 30n +.rt +Move the cursor to the beginning of the line. +.RE + +.sp +.ne 2 +.mk +.na +\fBend-of-line\fR +.ad +.RS 30n +.rt +Move the cursor to the end of the line. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete-line\fR +.ad +.RS 30n +.rt +Delete the contents of the current line. +.RE + +.sp +.ne 2 +.mk +.na +\fBkill-line\fR +.ad +.RS 30n +.rt +Delete everything that follows the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-kill-line\fR +.ad +.RS 30n +.rt +Delete all characters between the cursor and the start of the line. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-word\fR +.ad +.RS 30n +.rt +Move to the end of the word which follows the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-to-word\fR +.ad +.RS 30n +.rt +Move the cursor to the start of the word that follows the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-word\fR +.ad +.RS 30n +.rt +Move to the start of the word which precedes the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBgoto-column\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBfind-parenthesis\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBforward-delete-char\fR +.ad +.RS 30n +.rt +Delete the character under the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-delete-char\fR +.ad +.RS 30n +.rt +Delete the character which precedes the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBlist-or-eof\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBdel-char-or-list-or-eof\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBforward-delete-word\fR +.ad +.RS 30n +.rt +Delete the word which follows the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-delete-word\fR +.ad +.RS 30n +.rt +Delete the word which precedes the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBupcase-word\fR +.ad +.RS 30n +.rt +Convert all of the characters of the word which follows the cursor, to upper +case. +.RE + +.sp +.ne 2 +.mk +.na +\fBdowncase-word\fR +.ad +.RS 30n +.rt +Convert all of the characters of the word which follows the cursor, to lower +case. +.RE + +.sp +.ne 2 +.mk +.na +\fBcapitalize-word\fR +.ad +.RS 30n +.rt +Capitalize the word which follows the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBchange-case\fR +.ad +.RS 30n +.rt +If the next character is upper case, toggle it to lower case and vice versa. +.RE + +.sp +.ne 2 +.mk +.na +\fBredisplay\fR +.ad +.RS 30n +.rt +Redisplay the line. +.RE + +.sp +.ne 2 +.mk +.na +\fBclear-screen\fR +.ad +.RS 30n +.rt +Clear the terminal, then redisplay the current line. +.RE + +.sp +.ne 2 +.mk +.na +\fBtranspose-chars\fR +.ad +.RS 30n +.rt +Swap the character under the cursor with the character just before the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBset-mark\fR +.ad +.RS 30n +.rt +Set a mark at the position of the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBexchange-point-and-mark\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBkill-region\fR +.ad +.RS 30n +.rt +Delete the characters that lie between the last mark that was set, and the +cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBcopy-region-as-kill\fR +.ad +.RS 30n +.rt +Copy the text between the mark and the cursor to the cut buffer, without +deleting the original text. +.RE + +.sp +.ne 2 +.mk +.na +\fByank\fR +.ad +.RS 30n +.rt +Insert the text that was last deleted, just before the current position of the +cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBappend-yank\fR +.ad +.RS 30n +.rt +Paste the current contents of the cut buffer, after the cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBup-history\fR +.ad +.RS 30n +.rt +Recall the next oldest line that was entered. Note that in \fBvi\fR mode you +are left in command mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBdown-history\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBhistory-search-backward\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBhistory-search-forward\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBhistory-re-search-backward\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBhistory-re-search-forward\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBcomplete-word\fR +.ad +.RS 30n +.rt +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 commmand 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 +.mk +.na +\fBexpand-filename\fR +.ad +.RS 30n +.rt +Within the command line, expand wild cards, tilde expressions and dollar +expressions in the file name which immediately precedes the cursor. In \fBvi\fR +commmand 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 +.mk +.na +\fBlist-glob\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBlist-history\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBread-from-file\fR +.ad +.RS 30n +.rt +Temporarily switch to reading input from the file who's name precedes the +cursor. +.RE + +.sp +.ne 2 +.mk +.na +\fBread-init-files\fR +.ad +.RS 30n +.rt +Re-read \fBteclarc\fR configuration files. +.RE + +.sp +.ne 2 +.mk +.na +\fBbeginning-of-history\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBend-of-history\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBdigit-argument\fR +.ad +.RS 30n +.rt +Enter a repeat count for the next key binding function. For details, see the +Entering Repeat Counts section. +.RE + +.sp +.ne 2 +.mk +.na +\fBnewline\fR +.ad +.RS 30n +.rt +Terminate and return the current contents of the line, after appending a +newline character. The newline character is normally '\n', 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 '\n' +newline character or the '\r' carriage return character, the line is appended +to the history buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBrepeat-history\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBring-bell\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBforward-copy-char\fR +.ad +.RS 30n +.rt +Copy the next character into the cut buffer (NB. use repeat counts to copy more +than one). +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-copy-char\fR +.ad +.RS 30n +.rt +Copy the previous character into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-copy-word\fR +.ad +.RS 30n +.rt +Copy the next word into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-copy-word\fR +.ad +.RS 30n +.rt +Copy the previous word into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-find-char\fR +.ad +.RS 30n +.rt +Move the cursor to the next occurrence of the next character that you type. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-find-char\fR +.ad +.RS 30n +.rt +Move the cursor to the last occurrence of the next character that you type. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-to-char\fR +.ad +.RS 30n +.rt +Move the cursor to the character just before the next occurrence of the next +character that the user types. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-to-char\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBrepeat-find-char\fR +.ad +.RS 30n +.rt +Repeat the last backward-find-char, forward-find-char, backward-to-char or +forward-to-char. +.RE + +.sp +.ne 2 +.mk +.na +\fBinvert-refind-char\fR +.ad +.RS 30n +.rt +Repeat the last backward-find-char, forward-find-char, backward-to-char, or +forward-to-char in the opposite direction. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete-to-column\fR +.ad +.RS 30n +.rt +Delete the characters from the cursor up to the column that is specified by the +repeat count. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete-to-parenthesis\fR +.ad +.RS 30n +.rt +Delete the characters from the cursor up to and including the matching +parenthesis, or next close parenthesis. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-delete-find\fR +.ad +.RS 30n +.rt +Delete the characters from the cursor up to and including the following +occurence of the next character typed. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-delete-find\fR +.ad +.RS 30n +.rt +Delete the characters from the cursor up to and including the preceding +occurence of the next character typed. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-delete-to\fR +.ad +.RS 30n +.rt +Delete the characters from the cursor up to, but not including, the following +occurence of the next character typed. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-delete-to\fR +.ad +.RS 30n +.rt +Delete the characters from the cursor up to, but not including, the preceding +occurence of the next character typed. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete-refind\fR +.ad +.RS 30n +.rt +Repeat the last *-delete-find or *-delete-to action. +.RE + +.sp +.ne 2 +.mk +.na +\fBdelete-invert-refind\fR +.ad +.RS 30n +.rt +Repeat the last *-delete-find or *-delete-to action, in the opposite direction. +.RE + +.sp +.ne 2 +.mk +.na +\fBcopy-to-column\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBcopy-to-parenthesis\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBforward-copy-find\fR +.ad +.RS 30n +.rt +Copy the characters from the cursor up to and including the following occurence +of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-copy-find\fR +.ad +.RS 30n +.rt +Copy the characters from the cursor up to and including the preceding occurence +of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBforward-copy-to\fR +.ad +.RS 30n +.rt +Copy the characters from the cursor up to, but not including, the following +occurence of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBbackward-copy-to\fR +.ad +.RS 30n +.rt +Copy the characters from the cursor up to, but not including, the preceding +occurence of the next character typed, into the cut buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBcopy-refind\fR +.ad +.RS 30n +.rt +Repeat the last *-copy-find or *-copy-to action. +.RE + +.sp +.ne 2 +.mk +.na +\fBcopy-invert-refind\fR +.ad +.RS 30n +.rt +Repeat the last *-copy-find or *-copy-to action, in the opposite direction. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-mode\fR +.ad +.RS 30n +.rt +Switch to \fBvi\fR mode from emacs mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBemacs-mode\fR +.ad +.RS 30n +.rt +Switch to \fBemacs\fR mode from \fBvi\fR mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-insert\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, switch to insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-overwrite\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, switch to overwrite mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-insert-at-bol\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, move the cursor to the start of the line and switch +to insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-append-at-eol\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, move the cursor to the end of the line and switch +to append mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-append\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, move the cursor one position right, and switch to +insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-replace-char\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, replace the character under the cursor with the +next character entered. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-forward-change-char\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete the next character then enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-backward-change-char\fR +.ad +.RS 30n +.rt +From vi command mode, delete the preceding character then enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-forward-change-word\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete the next word then enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-backward-change-word\fR +.ad +.RS 30n +.rt +From vi command mode, delete the preceding word then enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-change-rest-of-line\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete from the cursor to the end of the line, then +enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-change-line\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete the current line, then enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-change-to-bol\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBvi-change-to-column\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBvi-change-to-parenthesis\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBvi-forward-change-find\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete the characters from the cursor up to and +including the following occurence of the next character typed, then enter +insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-backward-change-find\fR +.ad +.RS 30n +.rt +From vi command mode, delete the characters from the cursor up to and including +the preceding occurence of the next character typed, then enter insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-forward-change-to\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete the characters from the cursor up to, but +not including, the following occurence of the next character typed, then enter +insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-backward-change-to\fR +.ad +.RS 30n +.rt +From \fBvi\fR command mode, delete the characters from the cursor up to, but +not including, the preceding occurence of the next character typed, then enter +insert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-change-refind\fR +.ad +.RS 30n +.rt +Repeat the last vi-*-change-find or vi-*-change-to action. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-change-invert-refind\fR +.ad +.RS 30n +.rt +Repeat the last vi-*-change-find or vi-*-change-to action, in the opposite +direction. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-undo\fR +.ad +.RS 30n +.rt +In \fBvi\fR mode, undo the last editing operation. +.RE + +.sp +.ne 2 +.mk +.na +\fBvi-repeat-change\fR +.ad +.RS 30n +.rt +In \fBvi\fR command mode, repeat the last command that modified the line. +.RE + +.SS "Default Key Bindings In \fBemacs\fR Mode" +.sp +.LP +The following default key bindings, which can be overriden by the tecla +configuration file, are designed to mimic most of the bindings of the unix +\fBtcsh shell\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 +.mk +.na +\fB\fB^C\fR\fR +.ad +.RS 6n +.rt +user-interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^\\fR\fR +.ad +.RS 6n +.rt +abort +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Z\fR\fR +.ad +.RS 6n +.rt +suspend +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Q\fR\fR +.ad +.RS 6n +.rt +start-output +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^S\fR\fR +.ad +.RS 6n +.rt +stop-output +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^V\fR\fR +.ad +.RS 6n +.rt +literal-next +.RE + +.sp +.LP +The cursor keys are refered 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 +.mk +.na +\fBright\fR +.ad +.RS 9n +.rt +cursor-right +.RE + +.sp +.ne 2 +.mk +.na +\fBleft\fR +.ad +.RS 9n +.rt +cursor-left +.RE + +.sp +.ne 2 +.mk +.na +\fBup\fR +.ad +.RS 9n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fBdown\fR +.ad +.RS 9n +.rt +down-history +.RE + +.sp +.LP +The remaining bindings don't depend on the terminal setttings. +.sp +.ne 2 +.mk +.na +\fB\fB^F\fR\fR +.ad +.RS 21n +.rt +cursor-right +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^B\fR\fR +.ad +.RS 21n +.rt +cursor-left +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-i\fR\fR +.ad +.RS 21n +.rt +insert-mode +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^A\fR\fR +.ad +.RS 21n +.rt +beginning-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^E\fR\fR +.ad +.RS 21n +.rt +end-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^U\fR\fR +.ad +.RS 21n +.rt +delete-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^K\fR\fR +.ad +.RS 21n +.rt +kill-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-f\fR\fR +.ad +.RS 21n +.rt +forward-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-b\fR\fR +.ad +.RS 21n +.rt +backward-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^D\fR\fR +.ad +.RS 21n +.rt +del-char-or-list-or-eof +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^H\fR\fR +.ad +.RS 21n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^?\fR\fR +.ad +.RS 21n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d\fR\fR +.ad +.RS 21n +.rt +forward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^H\fR\fR +.ad +.RS 21n +.rt +backward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^?\fR\fR +.ad +.RS 21n +.rt +backward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-u\fR\fR +.ad +.RS 21n +.rt +upcase-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-l\fR\fR +.ad +.RS 21n +.rt +downcase-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c\fR\fR +.ad +.RS 21n +.rt +capitalize-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^R\fR\fR +.ad +.RS 21n +.rt +redisplay +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^L\fR\fR +.ad +.RS 21n +.rt +clear-screen +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^T\fR\fR +.ad +.RS 21n +.rt +transpose-chars +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^@\fR\fR +.ad +.RS 21n +.rt +set-mark +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X^X\fR\fR +.ad +.RS 21n +.rt +exchange-point-and-mark +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^W\fR\fR +.ad +.RS 21n +.rt +kill-region +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-w\fR\fR +.ad +.RS 21n +.rt +copy-region-as-kill +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Y\fR\fR +.ad +.RS 21n +.rt +yank +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^P\fR\fR +.ad +.RS 21n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^N\fR\fR +.ad +.RS 21n +.rt +down-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-p\fR\fR +.ad +.RS 21n +.rt +history-search-backward +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-n\fR\fR +.ad +.RS 21n +.rt +history-search-forward +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^I\fR\fR +.ad +.RS 21n +.rt +complete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X*\fR\fR +.ad +.RS 21n +.rt +expand-filename +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X^F\fR\fR +.ad +.RS 21n +.rt +read-from-file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X^R\fR\fR +.ad +.RS 21n +.rt +read-init-files +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Xg\fR\fR +.ad +.RS 21n +.rt +list-glob +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Xh\fR\fR +.ad +.RS 21n +.rt +list-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-<\fR\fR +.ad +.RS 21n +.rt +beginning-of-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM->\fR\fR +.ad +.RS 21n +.rt +end-of-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\n\fR\fR +.ad +.RS 21n +.rt +newline +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\r\fR\fR +.ad +.RS 21n +.rt +newline +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-o\fR\fR +.ad +.RS 21n +.rt +repeat-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^V\fR\fR +.ad +.RS 21n +.rt +\fBvi\fR-mode +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-0, M-1, ... M-9\fR\fR +.ad +.RS 21n +.rt +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" +.sp +.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 +.mk +.na +\fB\fB^C\fR\fR +.ad +.RS 8n +.rt +user-interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^\\fR\fR +.ad +.RS 8n +.rt +abort +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Z\fR\fR +.ad +.RS 8n +.rt +suspend +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^Q\fR\fR +.ad +.RS 8n +.rt +start-output +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^S\fR\fR +.ad +.RS 8n +.rt +stop-output +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^V\fR\fR +.ad +.RS 8n +.rt +literal-next +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^C\fR\fR +.ad +.RS 8n +.rt +user-interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^\\fR\fR +.ad +.RS 8n +.rt +abort +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^Z\fR\fR +.ad +.RS 8n +.rt +suspend +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^Q\fR\fR +.ad +.RS 8n +.rt +start-output +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^S\fR\fR +.ad +.RS 8n +.rt +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 refered 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 +.mk +.na +\fB\fBright\fR\fR +.ad +.RS 9n +.rt +cursor-right +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBleft\fR\fR +.ad +.RS 9n +.rt +cursor-left +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBup\fR\fR +.ad +.RS 9n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdown\fR\fR +.ad +.RS 9n +.rt +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 +.mk +.na +\fB\fB^D\fR\fR +.ad +.RS 8n +.rt +list-or-eof +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^G\fR\fR +.ad +.RS 8n +.rt +list-glob +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^H\fR\fR +.ad +.RS 8n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^I\fR\fR +.ad +.RS 8n +.rt +complete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\r\fR\fR +.ad +.RS 8n +.rt +newline +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\n\fR\fR +.ad +.RS 8n +.rt +newline +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^L\fR\fR +.ad +.RS 8n +.rt +clear-screen +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^N\fR\fR +.ad +.RS 8n +.rt +down-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^P\fR\fR +.ad +.RS 8n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^R\fR\fR +.ad +.RS 8n +.rt +redisplay +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^U\fR\fR +.ad +.RS 8n +.rt +backward-kill-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^W\fR\fR +.ad +.RS 8n +.rt +backward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X*\fR\fR +.ad +.RS 8n +.rt +expand-filename +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X^F\fR\fR +.ad +.RS 8n +.rt +read-from-file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^X^R\fR\fR +.ad +.RS 8n +.rt +read-init-files +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^?\fR\fR +.ad +.RS 8n +.rt +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 +.mk +.na +\fB\fBM-\\fR\fR +.ad +.RS 21n +.rt +cursor-right (META-space) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-$\fR\fR +.ad +.RS 21n +.rt +end-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-*\fR\fR +.ad +.RS 21n +.rt +expand-filename +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-+\fR\fR +.ad +.RS 21n +.rt +down-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM--\fR\fR +.ad +.RS 21n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-<\fR\fR +.ad +.RS 21n +.rt +beginning-of-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM->\fR\fR +.ad +.RS 21n +.rt +end-of-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^\fR\fR +.ad +.RS 21n +.rt +beginning-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-\fR\fR +.ad +.RS 21n +.rt +repeat-find-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-,\fR\fR +.ad +.RS 21n +.rt +invert-refind-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-|\fR\fR +.ad +.RS 21n +.rt +goto-column +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-~\fR\fR +.ad +.RS 21n +.rt +change-case +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-.\fR\fR +.ad +.RS 21n +.rt +vi-repeat-change +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-%\fR\fR +.ad +.RS 21n +.rt +find-parenthesis +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-a\fR\fR +.ad +.RS 21n +.rt +vi-append +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-A\fR\fR +.ad +.RS 21n +.rt +vi-append-at-eol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-b\fR\fR +.ad +.RS 21n +.rt +backward-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-B\fR\fR +.ad +.RS 21n +.rt +backward-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-C\fR\fR +.ad +.RS 21n +.rt +vi-change-rest-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cb\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cB\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cc\fR\fR +.ad +.RS 21n +.rt +vi-change-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-ce\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cE\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cw\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cW\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cF\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-find +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cf\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-find +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cT\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-to +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-ct\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-to +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c;\fR\fR +.ad +.RS 21n +.rt +vi-change-refind +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c,\fR\fR +.ad +.RS 21n +.rt +vi-change-invert-refind +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-ch\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c^H\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c^?\fR\fR +.ad +.RS 21n +.rt +vi-backward-change-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-cl\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c\\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-char (META-c-space) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c^\fR\fR +.ad +.RS 21n +.rt +vi-change-to-bol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c0\fR\fR +.ad +.RS 21n +.rt +vi-change-to-bol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c$\fR\fR +.ad +.RS 21n +.rt +vi-change-rest-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c|\fR\fR +.ad +.RS 21n +.rt +vi-change-to-column +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-c%\fR\fR +.ad +.RS 21n +.rt +vi-change-to-parenthesis +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dh\fR\fR +.ad +.RS 21n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d^H\fR\fR +.ad +.RS 21n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d^?\fR\fR +.ad +.RS 21n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dl\fR\fR +.ad +.RS 21n +.rt +forward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d\fR\fR +.ad +.RS 21n +.rt +forward-delete-char (META-d-space) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dd\fR\fR +.ad +.RS 21n +.rt +delete-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-db\fR\fR +.ad +.RS 21n +.rt +backward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dB\fR\fR +.ad +.RS 21n +.rt +backward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-de\fR\fR +.ad +.RS 21n +.rt +forward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dE\fR\fR +.ad +.RS 21n +.rt +forward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dw\fR\fR +.ad +.RS 21n +.rt +forward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dW\fR\fR +.ad +.RS 21n +.rt +forward-delete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dF\fR\fR +.ad +.RS 21n +.rt +backward-delete-find +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-df\fR\fR +.ad +.RS 21n +.rt +forward-delete-find +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dT\fR\fR +.ad +.RS 21n +.rt +backward-delete-to +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-dt\fR\fR +.ad +.RS 21n +.rt +forward-delete-to +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d;\fR\fR +.ad +.RS 21n +.rt +delete-refind +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d,\fR\fR +.ad +.RS 21n +.rt +delete-invert-refind +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d^\fR\fR +.ad +.RS 21n +.rt +backward-kill-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d0\fR\fR +.ad +.RS 21n +.rt +backward-kill-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d$\fR\fR +.ad +.RS 21n +.rt +kill-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-D\fR\fR +.ad +.RS 21n +.rt +kill-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d|\fR\fR +.ad +.RS 21n +.rt +delete-to-column +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-d%\fR\fR +.ad +.RS 21n +.rt +delete-to-parenthesis +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-e\fR\fR +.ad +.RS 21n +.rt +forward-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-E\fR\fR +.ad +.RS 21n +.rt +forward-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-f\fR\fR +.ad +.RS 21n +.rt +forward-find-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-F\fR\fR +.ad +.RS 21n +.rt +backward-find-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM--\fR\fR +.ad +.RS 21n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-h\fR\fR +.ad +.RS 21n +.rt +cursor-left +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-H\fR\fR +.ad +.RS 21n +.rt +beginning-of-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-i\fR\fR +.ad +.RS 21n +.rt +vi-insert +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-I\fR\fR +.ad +.RS 21n +.rt +vi-insert-at-bol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-j\fR\fR +.ad +.RS 21n +.rt +down-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-J\fR\fR +.ad +.RS 21n +.rt +history-search-forward +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-k\fR\fR +.ad +.RS 21n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-K\fR\fR +.ad +.RS 21n +.rt +history-search-backward +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-l\fR\fR +.ad +.RS 21n +.rt +cursor-right +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-L\fR\fR +.ad +.RS 21n +.rt +end-of-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-n\fR\fR +.ad +.RS 21n +.rt +history-re-search-forward +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-N\fR\fR +.ad +.RS 21n +.rt +history-re-search-backward +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-p\fR\fR +.ad +.RS 21n +.rt +append-yank +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-P\fR\fR +.ad +.RS 21n +.rt +yank +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-r\fR\fR +.ad +.RS 21n +.rt +vi-replace-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-R\fR\fR +.ad +.RS 21n +.rt +vi-overwrite +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-s\fR\fR +.ad +.RS 21n +.rt +vi-forward-change-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-S\fR\fR +.ad +.RS 21n +.rt +vi-change-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-t\fR\fR +.ad +.RS 21n +.rt +forward-to-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-T\fR\fR +.ad +.RS 21n +.rt +backward-to-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-u\fR\fR +.ad +.RS 21n +.rt +vi-undo +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-w\fR\fR +.ad +.RS 21n +.rt +forward-to-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-W\fR\fR +.ad +.RS 21n +.rt +forward-to-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-x\fR\fR +.ad +.RS 21n +.rt +forward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-X\fR\fR +.ad +.RS 21n +.rt +backward-delete-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yh\fR\fR +.ad +.RS 21n +.rt +backward-copy-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y^H\fR\fR +.ad +.RS 21n +.rt +backward-copy-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y^?\fR\fR +.ad +.RS 21n +.rt +backward-copy-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yl\fR\fR +.ad +.RS 21n +.rt +forward-copy-char +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y\\fR\fR +.ad +.RS 21n +.rt +forward-copy-char (META-y-space) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-ye\fR\fR +.ad +.RS 21n +.rt +forward-copy-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yE\fR\fR +.ad +.RS 21n +.rt +forward-copy-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yw\fR\fR +.ad +.RS 21n +.rt +forward-copy-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yW\fR\fR +.ad +.RS 21n +.rt +forward-copy-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yb\fR\fR +.ad +.RS 21n +.rt +backward-copy-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yB\fR\fR +.ad +.RS 21n +.rt +backward-copy-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yf\fR\fR +.ad +.RS 21n +.rt +forward-copy-find +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yF\fR\fR +.ad +.RS 21n +.rt +backward-copy-find +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yt\fR\fR +.ad +.RS 21n +.rt +forward-copy-to +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yT\fR\fR +.ad +.RS 21n +.rt +backward-copy-to +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y;\fR\fR +.ad +.RS 21n +.rt +copy-refind +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y,\fR\fR +.ad +.RS 21n +.rt +copy-invert-refind +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y^\fR\fR +.ad +.RS 21n +.rt +copy-to-bol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y0\fR\fR +.ad +.RS 21n +.rt +copy-to-bol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y$\fR\fR +.ad +.RS 21n +.rt +copy-rest-of-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-yy\fR\fR +.ad +.RS 21n +.rt +copy-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-Y\fR\fR +.ad +.RS 21n +.rt +copy-line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y|\fR\fR +.ad +.RS 21n +.rt +copy-to-column +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-y%\fR\fR +.ad +.RS 21n +.rt +copy-to-parenthesis +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^E\fR\fR +.ad +.RS 21n +.rt +emacs-mode +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^H\fR\fR +.ad +.RS 21n +.rt +cursor-left +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^?\fR\fR +.ad +.RS 21n +.rt +cursor-left +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^L\fR\fR +.ad +.RS 21n +.rt +clear-screen +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^N\fR\fR +.ad +.RS 21n +.rt +down-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^P\fR\fR +.ad +.RS 21n +.rt +up-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^R\fR\fR +.ad +.RS 21n +.rt +redisplay +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^D\fR\fR +.ad +.RS 21n +.rt +list-or-eof +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^I\fR\fR +.ad +.RS 21n +.rt +complete-word +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-\r\fR\fR +.ad +.RS 21n +.rt +newline +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-\n\fR\fR +.ad +.RS 21n +.rt +newline +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^X^R\fR\fR +.ad +.RS 21n +.rt +read-init-files +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-^Xh\fR\fR +.ad +.RS 21n +.rt +list-history +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM-0, M-1, ... M-9\fR\fR +.ad +.RS 21n +.rt +digit-argument (see below) +.RE + +.sp +.LP +Note that \fB^I\fR is what the TAB key generates. +.SS "Entering Repeat Counts" +.sp +.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 +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/libtecla.so\fR\fR +.ad +.RS 27n +.rt +The tecla library +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/include/libtecla.h\fR\fR +.ad +.RS 27n +.rt +The tecla header file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB~/.teclarc\fR\fR +.ad +.RS 27n +.rt +The personal tecla customization file +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBvi\fR(1), \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA), +\fBgl_get_line\fR(3TECLA), \fBgl_io_mode\fR(3TECLA), \fBlibtecla\fR(3LIB), +\fBpca_lookup_file\fR(3TECLA), \fBattributes\fR(5) diff --git a/usr/src/man/man5/term.5 b/usr/src/man/man5/term.5 new file mode 100644 index 0000000000..00b33c09fc --- /dev/null +++ b/usr/src/man/man5/term.5 @@ -0,0 +1,213 @@ +'\" 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 5 "3 Jul 1990" "SunOS 5.11" "Standards, Environments, and Macros" +.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(4), and \fBenviron\fR(5). 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(4). 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(1M). +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(4)), 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 +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +SuffixMeaningExample +\(miwWide mode (more than 80 columns)att4425\(miw +\(miamWith auto. margins (usually default)vt100\(miam +\(minamWithout automatic marginsvt100\(minam +\(mi\fIn\fRNumber of lines on the screen aaa\(mi60 +\(minaNo arrow keys (leave them in local)c100\(mina +\(minpNumber of pages of memoryc100\(mi4p +\(mirvReverse videoatt4415\(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(4) 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 +tab(); +lw(2.06i) lw(3.44i) +lw(2.06i) lw(3.44i) +. +2621,hp2621Hewlett-Packard 2621 series +2631Hewlett-Packard 2631 line printer +2631\(micT{ +Hewlett-Packard 2631 line printer, compressed mode +T} +2631\(mieT{ +Hewlett-Packard 2631 line printer, expanded mode +T} +2640,hp2640Hewlett-Packard 2640 series +2645,hp2645Hewlett-Packard 2645 series +3270IBM Model 3270 +33,tty33AT&T Teletype Model 33 KSR +35,tty35AT&T Teletype Model 35 KSR +37,tty37AT&T Teletype Model 37 KSR +4000aTrendata 4000a +4014,tek4014TEKTRONIX 4014 +40,tty40AT&T Teletype Dataspeed 40/2 +43,tty43AT&T Teletype Model 43 KSR +4410,5410T{ +AT&T 4410/5410 in 80-column mode, version 2 +T} +4410\(minfk,5410\(minfkT{ +AT&T 4410/5410 without function keys, version 1 +T} +4410\(minsl,5410\(minslAT&T 4410/5410 without pln defined +4410\(miw,5410\(miwAT&T 4410/5410 in 132-column mode +4410v1,5410v1T{ +AT&T 4410/5410 in 80-column mode, version 1 +T} +4410v1\(miw,5410v1\(miwT{ +AT&T 4410/5410 in 132-column mode, version 1 +T} +4415,5420AT&T 4415/5420 in 80-column mode +4415\(minl,5420\(minlAT&T 4415/5420 without changing labels +4415\(mirv,5420\(mirvT{ +AT&T 4415/5420 80 columns in reverse video +T} +4415\(mirv\(minl,5420\(mirv\(minlT{ +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\(minlT{ +AT&T 4415/5420 in 132-column mode without changing labels +T} +4415\(miw\(mirv,5420\(miw\(mirvT{ +AT&T 4415/5420 132 columns in reverse video +T} +4418,5418AT&T 5418 in 80-column mode +4418\(miw,5418\(miwAT&T 5418 in 132-column mode +4420AT&T Teletype Model 4420 +4424AT&T Teletype Model 4424 +4424-2T{ +AT&T Teletype Model 4424 in display function group ii +T} +4425,5425 AT&T 4425/5425 +4425\(mifk,5425\(mifkAT&T 4425/5425 without function keys +4425\(minl,5425\(minlT{ +AT&T 4425/5425 without changing labels in 80-column mode +T} +4425\(miw,5425\(miwAT&T 4425/5425 in 132-column mode +4425\(miw\(mifk,5425\(miw\(mifkT{ +AT&T 4425/5425 without function keys in 132-column mode +T} +4425\(minl\(miw,5425\(minl\(miwT{ +AT&T 4425/5425 without changing labels in 132-column mode +T} +4426AT&T Teletype Model 4426S +450DASI 450 (same as Diablo 1620) +450\(mi12DASI 450 in 12-pitch mode +500,att500AT&T-IS 500 terminal +510,510aAT&T 510/510a in 80-column mode +513bct,att513AT&T 513 bct terminal +5320AT&T 5320 hardcopy terminal +5420_2AT&T 5420 model 2 in 80-column mode +5420_2\(miwAT&T 5420 model 2 in 132-column mode +5620,dmdAT&T 5620 terminal 88 columns +5620\(mi24,dmd\(mi24T{ +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,610bctAT&T 610 bct terminal in 80-column mode +610\(miw,610bct\(miwAT&T 610 bct terminal in 132-column mode +630,630MTGAT&T 630 Multi-Tasking Graphics terminal +7300,pc7300,unix_pcAT&T UNIX PC Model 7300 +735,tiTexas Instruments TI735 and TI725 +745Texas Instruments TI745 +dumbT{ +generic name for terminals that lack reverse line-feed and other special escape sequences +T} +hpHewlett-Packard (same as 2645) +lpgeneric name for a line printer +pt505AT&T Personal Terminal 505 (22 lines) +pt505\(mi24T{ +AT&T Personal Terminal 505 (24-line mode) +T} +syncT{ +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 +.mk +.na +\fB\fB/usr/share/lib/terminfo/?/*\fR\fR +.ad +.sp .6 +.RS 4n +compiled terminal description database +.RE + +.SH SEE ALSO +.sp +.LP +\fBsh\fR(1), \fBstty\fR(1), \fBtabs\fR(1), \fBtput\fR(1), \fBvi\fR(1), +\fBinfocmp\fR(1M), \fBcurses\fR(3CURSES), \fBprofile\fR(4), \fBterminfo\fR(4), +\fBenviron\fR(5) diff --git a/usr/src/man/man5/threads.5 b/usr/src/man/man5/threads.5 new file mode 100644 index 0000000000..9770404d2e --- /dev/null +++ b/usr/src/man/man5/threads.5 @@ -0,0 +1,526 @@ +'\" 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 threads 5 "11 Nov 2008" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +threads, pthreads \- POSIX pthreads and Solaris threads concepts +.SH SYNOPSIS +.SS "POSIX" +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ -lrt \fIlibrary\fR... ] +.fi + +.LP +.nf +#include <pthread.h> +.fi + +.SS "Solaris" +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +.fi + +.LP +.nf +#include <sched.h> +.fi + +.LP +.nf +#include <thread.h> +.fi + +.SH DESCRIPTION +.sp +.LP +POSIX and Solaris threads each have their own implementation within +\fBlibc\fR(3LIB). Both 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. POSIX +and Solaris threads require different source, include files and linking +libraries. See \fBSYNOPSIS\fR. +.SS "Similarities" +.sp +.LP +Most of the POSIX and Solaris 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 Solaris functions +have similar endings. Typically, similar POSIX and Solaris functions have the +same number and use of arguments. +.SS "Differences" +.sp +.LP +POSIX pthreads and Solaris 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 +Solaris threads can be suspended and continued. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Solaris threads implement daemon threads, for whose demise the process does not +wait. +.RE +.SH FUNCTION COMPARISON +.sp +.LP +The following table compares the POSIX pthreads and Solaris threads functions. +When a comparable interface is not available either in POSIX pthreads or +Solaris threads, a hyphen (\fB-\fR) appears in the column. +.SS "Functions Related to Creation" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_create()\fR\fBthr_create()\fR +\fBpthread_attr_init()\fR\fB-\fR +\fBpthread_attr_setdetachstate()\fR\fB-\fR +\fBpthread_attr_getdetachstate()\fR\fB-\fR +\fBpthread_attr_setinheritsched()\fR\fB-\fR +\fBpthread_attr_getinheritsched()\fR\fB-\fR +\fBpthread_attr_setschedparam()\fR\fB-\fR +\fBpthread_attr_getschedparam()\fR\fB-\fR +\fBpthread_attr_setschedpolicy()\fR\fB-\fR +\fBpthread_attr_getschedpolicy()\fR\fB-\fR +\fBpthread_attr_setscope()\fR\fB-\fR +\fBpthread_attr_getscope()\fR\fB-\fR +\fBpthread_attr_setstackaddr()\fR\fB-\fR +\fBpthread_attr_getstackaddr()\fR\fB-\fR +\fBpthread_attr_setstacksize()\fR\fB-\fR +\fBpthread_attr_getstacksize()\fR\fB-\fR +\fBpthread_attr_getguardsize()\fR\fB-\fR +\fBpthread_attr_setguardsize()\fR\fB-\fR +\fBpthread_attr_destroy()\fR\fB-\fR +\fB-\fR\fBthr_min_stack()\fR +.TE + +.SS "Functions Related to Exit" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_exit()\fR\fBthr_exit()\fR +\fBpthread_join()\fR\fBthr_join()\fR +\fBpthread_detach()\fR\fB-\fR +.TE + +.SS "Functions Related to Thread Specific Data" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_key_create()\fR\fBthr_keycreate()\fR +\fBpthread_setspecific()\fR\fBthr_setspecific()\fR +\fBpthread_getspecific()\fR\fBthr_getspecific()\fR +\fBpthread_key_delete()\fR\fB-\fR +.TE + +.SS "Functions Related to Signals" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_sigmask()\fR\fBthr_sigsetmask()\fR +\fBpthread_kill()\fR\fBthr_kill()\fR +.TE + +.SS "Functions Related to IDs" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_self()\fR\fBthr_self()\fR +\fBpthread_equal()\fR\fB-\fR +\fB-\fR\fBthr_main()\fR +.TE + +.SS "Functions Related to Scheduling" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fB-\fR\fBthr_yield()\fR +\fB-\fR\fBthr_suspend()\fR +\fB-\fR\fBthr_continue()\fR +\fBpthread_setconcurrency()\fR\fBthr_setconcurrency()\fR +\fBpthread_getconcurrency()\fR\fBthr_getconcurrency()\fR +\fBpthread_setschedparam()\fR\fBthr_setprio()\fR +\fBpthread_setschedprio()\fR\fBthr_setprio()\fR +\fBpthread_getschedparam()\fR\fBthr_getprio()\fR +.TE + +.SS "Functions Related to Cancellation" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_cancel()\fR\fB-\fR +\fBpthread_setcancelstate()\fR\fB-\fR +\fBpthread_setcanceltype()\fR\fB-\fR +\fBpthread_testcancel()\fR\fB-\fR +\fBpthread_cleanup_pop()\fR\fB-\fR +\fBpthread_cleanup_push()\fR\fB-\fR +.TE + +.SS "Functions Related to Mutexes" +.sp + +.sp +.TS +tab(); +lw(3.85i) lw(1.65i) +lw(3.85i) lw(1.65i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_mutex_init()\fR\fBmutex_init()\fR +\fBpthread_mutexattr_init()\fR\fB-\fR +\fBpthread_mutexattr_setpshared()\fR\fB-\fR +\fBpthread_mutexattr_getpshared()\fR\fB-\fR +\fBpthread_mutexattr_setprotocol()\fR\fB-\fR +\fBpthread_mutexattr_getprotocol()\fR\fB-\fR +\fBpthread_mutexattr_setprioceiling()\fR\fB-\fR +\fBpthread_mutexattr_getprioceiling()\fR\fB-\fR +\fBpthread_mutexattr_settype()\fR\fB-\fR +\fBpthread_mutexattr_gettype()\fR\fB-\fR +\fBpthread_mutexattr_setrobust()\fR\fB-\fR +\fBpthread_mutexattr_getrobust()\fR\fB-\fR +\fBpthread_mutexattr_destroy()\fR\fB-\fR +\fBpthread_mutex_setprioceiling()\fR\fB-\fR +\fBpthread_mutex_getprioceiling()\fR\fB-\fR +\fBpthread_mutex_lock()\fR\fBmutex_lock()\fR +\fBpthread_mutex_trylock()\fR\fBmutex_trylock()\fR +\fBpthread_mutex_unlock()\fR\fBmutex_unlock()\fR +\fBpthread_mutex_destroy()\fR\fBmutex_destroy()\fR +.TE + +.SS "Functions Related to Condition Variables" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_cond_init()\fR\fBcond_init()\fR +\fBpthread_condattr_init()\fR\fB-\fR +\fBpthread_condattr_setpshared()\fR\fB-\fR +\fBpthread_condattr_getpshared()\fR\fB-\fR +\fBpthread_condattr_destroy()\fR\fB-\fR +\fBpthread_cond_wait()\fR\fBcond_wait()\fR +\fBpthread_cond_timedwait()\fR\fBcond_timedwait()\fR +\fBpthread_cond_signal()\fR\fBcond_signal()\fR +\fBpthread_cond_broadcast()\fR\fBcond_broadcast()\fR +\fBpthread_cond_destroy()\fR\fBcond_destroy()\fR +.TE + +.SS "Functions Related to Reader/Writer Locking" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_rwlock_init()\fR\fBrwlock_init()\fR +\fBpthread_rwlock_rdlock()\fR\fBrw_rdlock()\fR +\fBpthread_rwlock_tryrdlock()\fR\fBrw_tryrdlock()\fR +\fBpthread_rwlock_wrlock()\fR\fBrw_wrlock()\fR +\fBpthread_rwlock_trywrlock()\fR\fBrw_trywrlock()\fR +\fBpthread_rwlock_unlock()\fR\fBrw_unlock()\fR +\fBpthread_rwlock_destroy()\fR\fBrwlock_destroy()\fR +\fBpthread_rwlockattr_init()\fR\fB-\fR +\fBpthread_rwlockattr_destroy()\fR\fB-\fR +\fBpthread_rwlockattr_getpshared()\fR\fB-\fR +\fBpthread_rwlockattr_setpshared()\fR\fB-\fR +.TE + +.SS "Functions Related to Semaphores" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBsem_init()\fR\fBsema_init()\fR +\fBsem_open()\fR\fB-\fR +\fBsem_close()\fR\fB-\fR +\fBsem_wait()\fR\fBsema_wait()\fR +\fBsem_trywait()\fR\fBsema_trywait()\fR +\fBsem_post()\fR\fBsema_post()\fR +\fBsem_getvalue()\fR\fB-\fR +\fBsem_unlink()\fR\fB-\fR +\fBsem_destroy()\fR\fBsema_destroy()\fR +.TE + +.SS "Functions Related to fork(\|) Clean Up" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_atfork()\fR\fB-\fR +.TE + +.SS "Functions Related to Limits" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fBpthread_once()\fR\fB-\fR +.TE + +.SS "Functions Related to Debugging" +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPOSIX\fR\fBSolaris\fR +\fB-\fR\fBthr_stksegment()\fR +.TE + +.SH LOCKING +.SS "Synchronization" +.sp +.LP +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 Solaris implement four +synchronization mechanisms: mutexes, condition variables, reader/writer locking +(\fIoptimized frequent-read occasional-write mutex\fR), and semaphores. +.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" +.sp +.LP +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" +.sp +.LP +Solaris supports the following three POSIX scheduling policies: +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_OTHER\fR\fR +.ad +.RS 15n +.rt +Traditional Timesharing scheduling policy. It is based on the timesharing (TS) +scheduling class. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_FIFO\fR\fR +.ad +.RS 15n +.rt +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 +.mk +.na +\fB\fBSCHED_RR\fR\fR +.ad +.RS 15n +.rt +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, Solaris also +supports these scheduling policies: +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_IA\fR\fR +.ad +.RS 13n +.rt +Threads are scheduled according to the Inter-Active Class (IA) policy as +described in \fBpriocntl\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_FSS\fR\fR +.ad +.RS 13n +.rt +Threads are scheduled according to the Fair-Share Class (FSS) policy as +described in \fBpriocntl\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_FX\fR\fR +.ad +.RS 13n +.rt +Threads are scheduled according to the Fixed-Priority Class (FX) policy as +described in \fBpriocntl\fR(2). +.RE + +.SS "Solaris Threads" +.sp +.LP +Only scheduling policy supported is \fBSCHED_OTHER\fR, which is timesharing, +based on the \fBTS\fR scheduling class. +.SH ERRORS +.sp +.LP +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" +.sp +.LP +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. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe, Fork 1-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcrle\fR(1), \fBfork\fR(2), \fBpriocntl\fR(2), \fBlibpthread\fR(3LIB), +\fBlibrt\fR(3LIB), \fBlibthread\fR(3LIB), \fBpthread_atfork\fR(3C), +\fBpthread_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man5/trusted_extensions.5 b/usr/src/man/man5/trusted_extensions.5 new file mode 100644 index 0000000000..4ab69f72c7 --- /dev/null +++ b/usr/src/man/man5/trusted_extensions.5 @@ -0,0 +1,48 @@ +'\" 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 trusted_extensions 5 "12 Nov 2007" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +trusted_extensions \- Solaris Trusted Extensions +.SH DESCRIPTION +.sp +.LP +Solaris\u\s-2TM\s+2\d Trusted Extensions software is a specific configuration +of the Solaris Operating System (Solaris OS). Solaris Trusted Extensions +(Trusted Extensions) provides labels for local objects and processes, for the +desktop and windowing system, 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(1M) service, identified by the FMRI: +.sp +.in +2 +.nf +svc:/system/labeld:default +.fi +.in -2 +.sp + +.sp +.LP +Refer to the Administrator's Guide listed below for the required configuration +of Trusted Extensions software necessary before use. The system must be +rebooted after enabling or disabling \fBlabeld\fR to activate or deactivate +Trusted Extensions software. +.SH SEE ALSO +.sp +.LP +\fBlabeld\fR(1M), \fBlabel_encodings\fR(4), \fBlabels\fR(5) +.sp +.LP +\fISolaris Trusted Extensions Administrator\&'s Procedures\fR +.sp +.LP +\fISolaris Trusted Extensions User\&'s Guide\fR diff --git a/usr/src/man/man5/vgrindefs.5 b/usr/src/man/man5/vgrindefs.5 new file mode 100644 index 0000000000..7444fea121 --- /dev/null +++ b/usr/src/man/man5/vgrindefs.5 @@ -0,0 +1,273 @@ +'\" 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 5 "10 Aug 1994" "SunOS 5.11" "Standards, Environments, and Macros" +.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 +tab() box; +cw(.6i) |cw(.64i) |cw(4.26i) +lw(.6i) |lw(.64i) |lw(4.26i) +. +NameTypeDescription +_ +\fBab\fR\fBstr\fRT{ +Regular expression for the start of an alternate form comment +T} +_ +\fBae\fR\fBstr\fRT{ +Regular expression for the end of an alternate form comment +T} +_ +\fBbb\fR\fBstr\fRT{ +Regular expression for the start of a block +T} +_ +\fBbe\fR\fBstr\fRT{ +Regular expression for the end of a lexical block +T} +_ +\fBcb\fR\fBstr\fRT{ +Regular expression for the start of a comment +T} +_ +\fBce\fR\fBstr\fRT{ +Regular expression for the end of a comment +T} +_ +\fBid\fR\fBstr\fRT{ +String giving characters other than letters and digits that may legally occur in identifiers (default `_') +T} +_ +\fBkw\fR\fBstr\fRA list of keywords separated by spaces +_ +\fBlb\fR\fBstr\fRT{ +Regular expression for the start of a character constant +T} +_ +\fBle\fR\fBstr\fRT{ +Regular expression for the end of a character constant +T} +_ +\fBoc\fR\fBbool\fRT{ +Present means upper and lower case are equivalent +T} +_ +\fBpb\fR\fBstr\fRT{ +Regular expression for start of a procedure +T} +_ +\fBpl\fR\fBbool\fRT{ +Procedure definitions are constrained to the lexical level matched by the `px' capability +T} +_ +\fBpx\fR\fBstr\fRT{ +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\fRT{ +Regular expression for the start of a string +T} +_ +\fBse\fR\fBstr\fRT{ +Regular expression for the end of a string +T} +_ +\fBtc\fR\fBstr\fRT{ +Use the named entry as a continuation of this one +T} +_ +\fBtl\fR\fBbool\fRT{ +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 +.mk +.na +\fB\fB$\fR\fR +.ad +.RS 7n +.rt +The end of a line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^\fR\fR +.ad +.RS 7n +.rt +The beginning of a line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\ed\fR\fR +.ad +.RS 7n +.rt +A delimiter (space, tab, newline, start of line) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\ea\fR\fR +.ad +.RS 7n +.rt +Matches any string of symbols (like `.*' in lex) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\ep\fR\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB\fB()\fR\fR +.ad +.RS 7n +.rt +Grouping +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB|\fR\fR +.ad +.RS 7n +.rt +Alternation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB?\fR\fR +.ad +.RS 7n +.rt +Last item is optional +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\ee\fR\fR +.ad +.RS 7n +.rt +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 +.mk +.na +\fB\fB/usr/lib/vgrindefs\fR\fR +.ad +.RS 22n +.rt +file containing vgrind descriptions +.RE + +.SH SEE ALSO +.sp +.LP +\fBex\fR(1), \fBlex\fR(1), \fBtroff\fR(1), \fBvgrind\fR(1) diff --git a/usr/src/man/man5/zones.5 b/usr/src/man/man5/zones.5 new file mode 100644 index 0000000000..acf711706d --- /dev/null +++ b/usr/src/man/man5/zones.5 @@ -0,0 +1,261 @@ +'\" 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 zones 5 "29 Jan 2009" "SunOS 5.11" "Standards, Environments, and Macros" +.SH NAME +zones \- Solaris application containers +.SH DESCRIPTION +.sp +.LP +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(5). +.sp +.LP +You can configure and administer zones with the \fBzoneadm\fR(1M) and +\fBzonecfg\fR(1M) 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 \fBin.rlogind\fR(1M) or \fBsshd\fR(1M). +.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(1M). 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(1M). +.sp +.LP +An alphanumeric name and numeric ID identify each active zone. Alphanumeric +names are configured using the \fBzonecfg\fR(1M) 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(1M) 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 +.mk +.na +\fB\fBCONFIGURED\fR\fR +.ad +.RS 17n +.rt +Indicates that the configuration for the zone has been completely specified and +committed to stable storage. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBINCOMPLETE\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBINSTALLED\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBREADY\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBRUNNING\fR\fR +.ad +.RS 17n +.rt +Indicates that user processes associated with the zone application environment +are running. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSHUTTING_DOWN\fR\fR +.ad +.br +.na +\fB\fBDOWN\fR\fR +.ad +.RS 17n +.rt +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" +.sp +.LP +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(4) 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" +.sp +.LP +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(5). +.SS "Device Restrictions" +.sp +.LP +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(1M) 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(1M), +\fBprtdiag\fR(1M), and \fBprtconf\fR(1M) utilities do not work in a zone since +they rely on devices that are not normally available. +.SS "Brands" +.sp +.LP +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(5)). Once installed, a zone's brand may not +be changed unless the zone is first uninstalled. +.SS "File Systems" +.sp +.LP +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(1M) +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(7FS) 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. +.SS "Networking" +.sp +.LP +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(1M). 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(1M). 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" +.sp +.LP +A zone is capable of emulating a 32-bit host identifier, which can be +configured via \fBzonecfg\fR(1M), for the purpose of system consolidation. If a +zone emulates a host identifier, then commands such as \fBhostid\fR(1) and +\fBsysdef\fR(1M) 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 +.sp +.LP +\fBhostid\fR(1), \fBzlogin\fR(1), \fBzonename\fR(1), \fBin.rlogind\fR(1M), +\fBsshd\fR(1M), \fBsysdef\fR(1M), \fBzoneadm\fR(1M), \fBzonecfg\fR(1M), +\fBkill\fR(2), \fBpriocntl\fR(2), \fBsysinfo\fR(2), \fBgethostid\fR(3C), +\fBgetzoneid\fR(3C), \fBucred_get\fR(3C), \fBproc\fR(4), \fBattributes\fR(5), +\fBbrands\fR(5), \fBprivileges\fR(5), \fBcrgetzoneid\fR(9F) |