diff options
| author | Jerry Jelinek <jerry.jelinek@joyent.com> | 2017-06-08 10:10:29 +0000 |
|---|---|---|
| committer | Jerry Jelinek <jerry.jelinek@joyent.com> | 2017-06-08 10:10:29 +0000 |
| commit | 8cb9f5acecaded019a9a55454a31dcf4328d0d1b (patch) | |
| tree | 7c69e28b9b9b5ac2d9f928324a663becf2efa2d7 | |
| parent | 3a5445f1b9d90e4f1538503bd60913c8f302c17f (diff) | |
| parent | 79809f9cf402f130667349b2d4007ecd65d63c6f (diff) | |
| download | illumos-joyent-release-20170608.tar.gz | |
[illumos-gate merge]release-20170608
commit 79809f9cf402f130667349b2d4007ecd65d63c6f
8269 dtrace stddev aggregation is normalized incorrectly
commit 22c8b9583d07895c16549075a53668d7bc988cf3
8108 zdb -l fails to read labels 2 and 3
commit 0255edcc85fc0cd1dda0e49bcd52eb66c06a1b16
8056 zfs send size estimate is inaccurate for some zvols
commit dbfd9f930004c390a2ce2cf850c71b4f880eef9c
8156 dbuf_evict_notify() does not need dbuf_evict_lock
commit 690031d326342fa4ea28b5e80f1ad6a16281519d
8168 NULL pointer dereference in zfs_create()
commit 7c4ab494ff60bbbcc0889e71388ae63e903bbf57
8276 rpcbind leaks memory due to libumem per thread caching.
commit f176a0a4cd61cbd708a7f25dc30d221f4d5902ba
8270 dnlc_reverse_lookup() is unsafe at any speed
commit 72d3dbb9ab4481606cb93caca98ba3b3a8eb6ce2
8300 fix man page issues found by mandoc 1.14.1
commit cb4d790db8fe85bce9f9647fe4e1bdc274c7af1c
8337 gss: misleading-indentation
commit f53522305c07915a44e86f2455cc62e7aac27037
8324 more: misleading-indentation
Conflicts:
usr/src/uts/common/fs/lookup.c
usr/src/man/man3c/thrd_equal.3c
298 files changed, 6931 insertions, 5145 deletions
diff --git a/usr/src/cmd/dtrace/test/tst/common/aggs/tst.stddev.normalize.d b/usr/src/cmd/dtrace/test/tst/common/aggs/tst.stddev.normalize.d new file mode 100644 index 0000000000..50c14d3ced --- /dev/null +++ b/usr/src/cmd/dtrace/test/tst/common/aggs/tst.stddev.normalize.d @@ -0,0 +1,46 @@ +/* + * This file and its contents are supplied under the terms of the + * Common Development and Distribution License ("CDDL"), version 1.0. + * You may only use this file in accordance with the terms of version + * 1.0 of the CDDL. + * + * A full copy of the text of the CDDL should have accompanied this + * source. A copy of the CDDL is also available via the Internet at + * http://www.illumos.org/license/CDDL. + */ + +/* + * Copyright 2017 Panzura. All rights reserved. + */ + +/* + * ASSERTION: + * Positive test for normalization() of stddev() + * + * SECTION: Aggregations/Normalization + * + */ + +#pragma D option quiet +#pragma D option aggrate=1ms +#pragma D option switchrate=50ms + +BEGIN +{ + i = 0; +} + +tick-100ms +/i < 11/ +{ + @ = stddev(i * 100); + i++; +} + +tick-100ms +/i == 11/ +{ + printf("normalized data:\n"); + normalize(@, 10); + exit(0); +} diff --git a/usr/src/cmd/dtrace/test/tst/common/aggs/tst.stddev.normalize.d.out b/usr/src/cmd/dtrace/test/tst/common/aggs/tst.stddev.normalize.d.out new file mode 100644 index 0000000000..a629b1fdb5 --- /dev/null +++ b/usr/src/cmd/dtrace/test/tst/common/aggs/tst.stddev.normalize.d.out @@ -0,0 +1,3 @@ +normalized data: + + 31 diff --git a/usr/src/cmd/gss/gssd/gssd_clnt_stubs.c b/usr/src/cmd/gss/gssd/gssd_clnt_stubs.c index 8be41c666d..9eba27a66c 100644 --- a/usr/src/cmd/gss/gssd/gssd_clnt_stubs.c +++ b/usr/src/cmd/gss/gssd/gssd_clnt_stubs.c @@ -1064,12 +1064,11 @@ kgss_accept_sec_context( } else gssd_ver_cred_handle = GSSD_NO_CREDENTIAL; - err = kgss_accept_sec_context_wrapped(minor_status, - &kctx->gssd_ctx, - &kctx->gssd_ctx_verifier, gssd_ver_cred_handle, - gssd_cred_verifier, input_token, input_chan_bindings, - src_name, mech_type, output_token, ret_flags, - time_rec, delegated_cred_handle, uid); + err = kgss_accept_sec_context_wrapped(minor_status, &kctx->gssd_ctx, + &kctx->gssd_ctx_verifier, gssd_ver_cred_handle, + gssd_cred_verifier, input_token, input_chan_bindings, + src_name, mech_type, output_token, ret_flags, + time_rec, delegated_cred_handle, uid); if (GSS_ERROR(err)) { KGSS_FREE(kctx); diff --git a/usr/src/cmd/more/more.c b/usr/src/cmd/more/more.c index 523d87e7cd..9bbe46daad 100644 --- a/usr/src/cmd/more/more.c +++ b/usr/src/cmd/more/more.c @@ -1089,8 +1089,8 @@ command(char *filename, register FILE *f) done++; goto endsw; } - Currline++; - nlines--; + Currline++; + nlines--; } ret (dlines); case '\n': @@ -1470,8 +1470,8 @@ skiplns(register off_t n, register FILE *f) while ((c = Getc (f)) != '\n') if (c == EOF) return; - n--; - Currline++; + n--; + Currline++; } } diff --git a/usr/src/cmd/zdb/zdb.c b/usr/src/cmd/zdb/zdb.c index 0137e6f448..75f1d6a815 100644 --- a/usr/src/cmd/zdb/zdb.c +++ b/usr/src/cmd/zdb/zdb.c @@ -2301,24 +2301,29 @@ dump_label(const char *dev) (void) snprintf(path, sizeof (path), "%s%s", ZFS_RDISK_ROOTD, dev); - if ((s = strrchr(dev, 's')) == NULL || !isdigit(*(s + 1))) + if (((s = strrchr(dev, 's')) == NULL && + (s = strchr(dev, 'p')) == NULL) || + !isdigit(*(s + 1))) (void) strlcat(path, "s0", sizeof (path)); } - if (stat64(path, &statbuf) != 0) { - (void) printf("failed to stat '%s': %s\n", path, + if ((fd = open64(path, O_RDONLY)) < 0) { + (void) fprintf(stderr, "cannot open '%s': %s\n", path, strerror(errno)); exit(1); } - if (S_ISBLK(statbuf.st_mode)) { - (void) printf("cannot use '%s': character device required\n", - path); + if (fstat64(fd, &statbuf) != 0) { + (void) fprintf(stderr, "failed to stat '%s': %s\n", path, + strerror(errno)); + (void) close(fd); exit(1); } - if ((fd = open64(path, O_RDONLY)) < 0) { - (void) printf("cannot open '%s': %s\n", path, strerror(errno)); + if (S_ISBLK(statbuf.st_mode)) { + (void) fprintf(stderr, + "cannot use '%s': character device required\n", path); + (void) close(fd); exit(1); } diff --git a/usr/src/lib/libc/port/threads/thr.c b/usr/src/lib/libc/port/threads/thr.c index 134c078a57..747e789442 100644 --- a/usr/src/lib/libc/port/threads/thr.c +++ b/usr/src/lib/libc/port/threads/thr.c @@ -22,6 +22,7 @@ /* * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2016 by Delphix. All rights reserved. + * Copyright (c) 2017 by The MathWorks, Inc. All rights reserved. */ /* * Copyright 2016 Joyent, Inc. @@ -779,9 +780,14 @@ _thrp_exit() } lmutex_unlock(&udp->link_lock); - tmem_exit(); /* deallocate tmem allocations */ + /* + * tsd_exit() may call its destructor free(), thus depending on + * tmem, therefore tmem_exit() needs to be called after tsd_exit() + * and tls_exit(). + */ tsd_exit(); /* deallocate thread-specific data */ tls_exit(); /* deallocate thread-local storage */ + tmem_exit(); /* deallocate tmem allocations */ heldlock_exit(); /* deal with left-over held locks */ /* block all signals to finish exiting */ diff --git a/usr/src/lib/libdtrace/common/dt_consume.c b/usr/src/lib/libdtrace/common/dt_consume.c index b292b6abc5..7f8c673dbe 100644 --- a/usr/src/lib/libdtrace/common/dt_consume.c +++ b/usr/src/lib/libdtrace/common/dt_consume.c @@ -381,8 +381,10 @@ dt_stddev(uint64_t *data, uint64_t normal) * The standard approximation for standard deviation is * sqrt(average(x**2) - average(x)**2), i.e. the square root * of the average of the squares minus the square of the average. + * When normalizing, we should divide the sum of x**2 by normal**2. */ dt_divide_128(data + 2, normal, avg_of_squares); + dt_divide_128(avg_of_squares, normal, avg_of_squares); dt_divide_128(avg_of_squares, data[0], avg_of_squares); norm_avg = (int64_t)data[1] / (int64_t)normal / (int64_t)data[0]; diff --git a/usr/src/lib/libzfs/common/libzfs_dataset.c b/usr/src/lib/libzfs/common/libzfs_dataset.c index 8f56c4042b..339be4e0af 100644 --- a/usr/src/lib/libzfs/common/libzfs_dataset.c +++ b/usr/src/lib/libzfs/common/libzfs_dataset.c @@ -3291,6 +3291,7 @@ zfs_create(libzfs_handle_t *hdl, const char *path, zfs_type_t type, char errbuf[1024]; uint64_t zoned; enum lzc_dataset_type ost; + zpool_handle_t *zpool_handle; (void) snprintf(errbuf, sizeof (errbuf), dgettext(TEXT_DOMAIN, "cannot create '%s'"), path); @@ -3330,7 +3331,8 @@ zfs_create(libzfs_handle_t *hdl, const char *path, zfs_type_t type, if (p != NULL) *p = '\0'; - zpool_handle_t *zpool_handle = zpool_open(hdl, pool_path); + if ((zpool_handle = zpool_open(hdl, pool_path)) == NULL) + return (-1); if (props && (props = zfs_valid_proplist(hdl, type, props, zoned, NULL, zpool_handle, errbuf)) == 0) { diff --git a/usr/src/man/man1/apropos.1 b/usr/src/man/man1/apropos.1 index 2ef316cbe5..56b160626e 100644 --- a/usr/src/man/man1/apropos.1 +++ b/usr/src/man/man1/apropos.1 @@ -39,8 +39,9 @@ and fail. .Lp Each word is considered -separately and the case of letters is ignored. Words which are part of other -words are considered; for example, when looking for +separately and the case of letters is ignored. +Words which are part of other words are considered; for example, when looking +for .Sq compile , .Nm apropos finds all instances of @@ -49,8 +50,8 @@ also. .Lp The .Nm whatis -command performs the same search, but only matches whole words. In the above -example, +command performs the same search, but only matches whole words. +In the above example, .Nm whatis would not match the instances of .Sq compiler @@ -70,7 +71,8 @@ command. .Bl -tag -width "-s section" .It Fl M Ar path Force a specific colon separated manual path instead of the -default search path. Overrides the MANPATH environment variable. +default search path. +Overrides the MANPATH environment variable. .It Fl s Ar section Restrict search to specified section. .El diff --git a/usr/src/man/man1/hostname.1 b/usr/src/man/man1/hostname.1 index 75a24a0437..2dc4c542bb 100644 --- a/usr/src/man/man1/hostname.1 +++ b/usr/src/man/man1/hostname.1 @@ -18,7 +18,8 @@ The .Nm command prints the name of the current host, as given before the .Xr login 1 -prompt. The super-user can set the hostname by giving +prompt. +The super-user can set the hostname by giving .Ar name-of-host . .Pp While setting the hostname changes the hostname for the running system, diff --git a/usr/src/man/man1/kvmstat.1 b/usr/src/man/man1/kvmstat.1 index b0a6afdc17..fa1bd7a12a 100644 --- a/usr/src/man/man1/kvmstat.1 +++ b/usr/src/man/man1/kvmstat.1 @@ -31,15 +31,15 @@ injected interrupts, emulations, and more, on a per virtual CPU basis. .Nm should be used when trying to get a rough sense of guest activity from the hypervisor's perspective, and allows one to understand from a low-level -perspective, what kind of activity is going on inside of the virtual machine. In -addition, +perspective, what kind of activity is going on inside of the virtual machine. +In addition, .Nm is useful for diagnosing reports of pathological or faulty behavior inside of -guests. While there is no expected range of values for the fields displayed as -that varies with the use of virtual machines, if all of the virtual CPUs for a -given virtual machine are consistently zero, then that may indicate that a -problem has occurred, for example, a panic inside of the guest or a bug in the -hypervisor. +guests. +While there is no expected range of values for the fields displayed as that +varies with the use of virtual machines, if all of the virtual CPUs for a given +virtual machine are consistently zero, then that may indicate that a problem has +occurred, for example, a panic inside of the guest or a bug in the hypervisor. .Lp If no operands are specified, then .Nm @@ -96,15 +96,15 @@ The following operands are supported: .Bl -hang -width Ds .It Ar count .Bd -filled -compact -Specifies the number of times that the statistics are repeated. If not -specified, +Specifies the number of times that the statistics are repeated. +If not specified, .Nm will continue until it is terminated. .Ed .It Ar interval .Bd -filled -compact -Specifies the number of seconds between reports of statistics. If not specified, -reports are generated every second. +Specifies the number of seconds between reports of statistics. +If not specified, reports are generated every second. .Ed .El .Sh STABILITY diff --git a/usr/src/man/man1/man.1 b/usr/src/man/man1/man.1 index 8cc4606db0..c4a16b60bb 100644 --- a/usr/src/man/man1/man.1 +++ b/usr/src/man/man1/man.1 @@ -39,8 +39,8 @@ .Sh DESCRIPTION The .Nm -command displays information from the reference manuals. It -displays complete manual pages that you select by +command displays information from the reference manuals. +It displays complete manual pages that you select by .Ar name , or one-line summaries selected either by .Ar keyword @@ -55,7 +55,8 @@ Reference Manual pages are marked up with either .Xr man 5 , or .Xr mdoc 5 -language tags. The +language tags. +The .Nm command recognizes the type of markup and processes the file accordingly. @@ -65,8 +66,10 @@ processes the file accordingly. The online Reference Manual page directories are conventionally located in .Pa /usr/share/man . Each directory corresponds to a -section of the manual. Since these directories are optionally installed, they -might not reside on your host. You might have to mount +section of the manual. +Since these directories are optionally installed, they might not reside on your +host. +You might have to mount .Pa /usr/share/man from a host on which they do reside. The @@ -92,15 +95,18 @@ Shows all manual pages matching .Ar name within the .Ev MANPATH -search path. Manual pages are displayed in the order found. +search path. +Manual pages are displayed in the order found. .It Fl d -Debugs. Displays what a section-specifier evaluates to, method used for -searching, and paths searched by +Debugs. +Displays what a section-specifier evaluates to, method used for searching, and +paths searched by .Nm . .It Fl f Ar file ... Attempts to locate manual pages related to any of the given .Ar file -names. It strips the leading path name components from each +names. +It strips the leading path name components from each .Ar file , and then prints one-line summaries containing the resulting basename or names. This option also uses the @@ -108,7 +114,8 @@ This option also uses the database. .It Fl F This option is present for backwards compatibility and is documented -here for reference only. It performs no function. +here for reference only. +It performs no function. .It Fl k Ar keyword ... Prints out one-line summaries from the .Pa whatis @@ -124,10 +131,12 @@ Lists all manual pages found matching .Ar name within the search path. .It Fl M Ar path -Specifies an alternate search path for manual pages. The +Specifies an alternate search path for manual pages. +The .Ar path is a colon-separated list of directories that contain manual page directory -subtrees. For example, if +subtrees. +For example, if .Ar path is .Pa /usr/share/man:/usr/local/man , @@ -143,11 +152,13 @@ or .Fl w options, the .Fl M -option must appear first. Each directory in the +option must appear first. +Each directory in the .Ar path is assumed to contain subdirectories of the form .Pa man* , -one for each section. This option overrides the +one for each section. +This option overrides the .Ev MANPATH environment variable. .It Fl r @@ -156,7 +167,8 @@ display it. .It Fl s Ar section Specifies sections of the manual for .Nm -to search. The directories searched for +to search. +The directories searched for .Ar name are limited to those specified by .Ar section . @@ -172,12 +184,14 @@ can be a word, for example, .Li old , .Li public . .Ar section -can also be a letter. To specify multiple sections, -separate each section with a comma. This option overrides the +can also be a letter. +To specify multiple sections, separate each section with a comma. +This option overrides the .Ev MANPATH environment variable and the .Pa man.cf -file. See +file. +See .Sx Search Path below for an explanation of how .Nm @@ -187,7 +201,8 @@ Arranges for the specified manual pages to be sent to the default printer as PostScript. .It Fl T Ar macro-package This option is present for backwards compatibility and is documented -here for reference only. It performs no function. +here for reference only. +It performs no function. .It Fl w Updates the .Nm whatis @@ -210,8 +225,8 @@ Entries in the reference manuals are organized into .Em sections . A section name consists of a major section name, typically a single digit, optionally -followed by a subsection name, typically one or more letters. An unadorned -major section name, for example, +followed by a subsection name, typically one or more letters. +An unadorned major section name, for example, .Qq 9 , does not act as an abbreviation for the subsections of that name, such as @@ -223,7 +238,8 @@ That is, each subsection must be searched separately by .Nm .Fl s . Each section contains descriptions apropos to a particular reference category, -with subsections refining these distinctions. See the +with subsections refining these distinctions. +See the .Em intro manual pages for an explanation of the classification used in this release. . @@ -248,13 +264,14 @@ environment variable, primarily by substituting .Li man for the last component of the .Ev PATH -element. Special provisions are added -to account for unique characteristics of directories such as +element. +Special provisions are added to account for unique characteristics of +directories such as .Pa /sbin , .Pa /usr/ucb , .Pa /usr/xpg4/bin , -and others. If the file argument contains -a +and others. +If the file argument contains a .Qq / character, the .Em dirname @@ -299,7 +316,8 @@ file has the following format: Lines beginning with .Sq Li # and blank lines are considered comments, and are -ignored. Each directory specified in +ignored. +Each directory specified in .Ev MANPATH can contain a manual page configuration file, specifying the default search order for that directory. @@ -310,9 +328,9 @@ page entry fitting the pattern: .Dl \&.so man*/ Ns Em sourcefile .Lp .Nm -processes the indicated file in place of the current one. The -reference must be expressed as a path name relative to the root of the manual -page directory subtree. +processes the indicated file in place of the current one. +The reference must be expressed as a path name relative to the root of the +manual page directory subtree. .Lp When the second or any subsequent line starts with .Sy \&.so , @@ -337,17 +355,20 @@ and .Bl -tag -width MANWIDTH .It Ev MANPATH A colon-separated list of directories; each directory can be followed by a -comma-separated list of sections. If set, its value overrides +comma-separated list of sections. +If set, its value overrides .Pa /usr/share/man as the default directory search path, and the .Pa man.cf -file as the default section search path. The +file as the default section search path. +The .Fl M and .Fl s flags, in turn, override these values. .It Ev MANWIDTH -Width of the output. If set to the special value +Width of the output. +If set to the special value .Qq Sy TTY .Po or .Qq Sy tty @@ -355,9 +376,11 @@ Width of the output. If set to the special value and output is to terminal, auto-detect terminal width. .It Ev PAGER A program to use for interactively delivering -output to the screen. If not set, +output to the screen. +If not set, .Sq Nm more Fl s -is used. See +is used. +See .Xr more 1 . .El .Sh FILES @@ -419,5 +442,6 @@ created with the option. .Sh BUGS The manual is supposed to be reproducible either on a phototypesetter or on an -ASCII terminal. However, on a terminal some information (indicated by -font changes, for instance) is lost. +ASCII terminal. +However, on a terminal some information (indicated by font changes, for +instance) is lost. diff --git a/usr/src/man/man1m/acpidump.1m b/usr/src/man/man1m/acpidump.1m index 5d93abbcbe..577a1deaef 100644 --- a/usr/src/man/man1m/acpidump.1m +++ b/usr/src/man/man1m/acpidump.1m @@ -29,8 +29,8 @@ The .Nm utility is used to dump the system's Advanced Configuration and Power Interface -(ACPI) tables that are provided by system firmware. The dumped tables can be -used by other utilities, such as +(ACPI) tables that are provided by system firmware. +The dumped tables can be used by other utilities, such as .Xr acpixtract 1M or .Sy iasl . @@ -42,7 +42,8 @@ Get the table at the given physical address. .It Fl b Dump all tables to binary files. .It Fl c Ar on|off -Enable dumping customized tables. The default is off. +Enable dumping customized tables. +The default is off. .It Fl f Ar file Read the table from the given binary file. .It Fl h diff --git a/usr/src/man/man1m/acpixtract.1m b/usr/src/man/man1m/acpixtract.1m index cc844c78d0..309056c459 100644 --- a/usr/src/man/man1m/acpixtract.1m +++ b/usr/src/man/man1m/acpixtract.1m @@ -25,19 +25,22 @@ The .Nm utility extracts the binary data from a dump of the system's Advanced -Configuration and Power Interface (ACPI) tables. The dump is usually obtained -via the +Configuration and Power Interface (ACPI) tables. +The dump is usually obtained via the .Xr acpidump 1M -command. The resulting binary file(s) are represented in the ACPI +command. +The resulting binary file(s) are represented in the ACPI .Sy ASL -assembly language. For each table extracted, a corresponding +assembly language. +For each table extracted, a corresponding .Em table.dat file will be created. .Sh OPTIONS The following options are supported: .Bl -tag -width Ds .It Fl a -Extract all of the tables found. By default only the +Extract all of the tables found. +By default only the .Sy DSDT and .Sy SSDT diff --git a/usr/src/man/man1m/automount.1m b/usr/src/man/man1m/automount.1m index 3ce74a5b1d..717d4fafe1 100644 --- a/usr/src/man/man1m/automount.1m +++ b/usr/src/man/man1m/automount.1m @@ -34,18 +34,21 @@ The .Nm utility installs .Nm autofs -mount points and associates an automount map with each mount point. It starts -the +mount points and associates an automount map with each mount point. +It starts the .Xr automountd 1M daemon if it finds any non-trivial entries in either local or distributed -automount maps and if the daemon is not already running. The +automount maps and if the daemon is not already running. +The .Nm autofs file system monitors attempts to access directories within it and notifies the .Xr automountd 1M -daemon. The daemon uses the map to locate a file system, which it then mounts at -the point of reference within the +daemon. +The daemon uses the map to locate a file system, which it then mounts at the +point of reference within the .Nm autofs -file system. A map can be assigned to an +file system. +A map can be assigned to an .Nm autofs mount using an entry in the .Pa /etc/auto_master @@ -61,7 +64,8 @@ The file .Pa /etc/auto_master determines the locations of all .Nm autofs -mount points. By default, this file contains three entries: +mount points. +By default, this file contains three entries: .Bd -literal -offset indent # Master map for automounter # @@ -72,17 +76,21 @@ mount points. By default, this file contains three entries: .Pp The .Sy +auto_master -entry is a reference to an external NIS master map. If one exists, then -its entries are read as if they occurred in place of the +entry is a reference to an external NIS master map. +If one exists, then its entries are read as if they occurred in place of the .Sy +auto_master -entry. The remaining entries in the master file specify a directory on which an +entry. +The remaining entries in the master file specify a directory on which an .Nm autofs mount will be made followed by the automounter map to be associated with it. Optional mount options may be supplied as an optional third field in the each -entry. These options are used for any entries in the map that do not specify -mount options explicitly. The +entry. +These options are used for any entries in the map that do not specify mount +options explicitly. +The .Nm -command is usually run without arguments. It compares the entries +command is usually run without arguments. +It compares the entries .Pa /etc/auto_master with the current list of .Nm autofs @@ -96,33 +104,37 @@ up to date with the .Pa /etc/auto_master . At boot time it installs all .Nm autofs -mounts from the master map. Subsequently, it may be run to install +mounts from the master map. +Subsequently, it may be run to install .Nm autofs mounts for new entries in the master map or the direct map, or to perform unmounts for entries that have been removed from these maps. .Ss Automount with Solaris Trusted Extensions If a system is configured with Solaris Trusted Extensions, additional -processing is performed to facilitate multilevel home directory access. A list -of zones whose labels are dominated by the current zone is generated and +processing is performed to facilitate multilevel home directory access. +A list of zones whose labels are dominated by the current zone is generated and default .Sy auto_home -automount maps are generated if they do not currently exist. These automount -maps are named +automount maps are generated if they do not currently exist. +These automount maps are named .Sy auto_home_ Ns Ar zonename , where .Ar zonename -is the name of each zone's lower-level zone. An +is the name of each zone's lower-level zone. +An .Nm autofs mount of each such .Sy auto_home map is then performed, regardless of whether it is explicitly or implicitly -listed in the master map. Instead of +listed in the master map. +Instead of .Nm autofs mounting the standard .Sy auto_home map, the zone uses an .Pa auto_home -file appended with its own zone name. Each zone's +file appended with its own zone name. +Each zone's .Sy auto_home map is uniquely named so that it can be maintained and shared by all zones using a common name server. @@ -130,7 +142,8 @@ a common name server. By default, the home directories of lower-level zones are mounted read-only under .Pa /zone/ Ns Ar zonename Ns Pa /export/home -when each zone is booted. The default +when each zone is booted. +The default .Sy auto_home_ Ns Ar zonename automount map specifies that path as the source directory for an .Nm lofs @@ -147,22 +160,23 @@ as generated from a higher level zone would contain: When a home directory is referenced and the name does not match any other keys in the .Sy auto_home_public -map, it will match this loopback mount specification. If this loopback match -occurs and the name corresponds to a valid user whose home directory does not -exist in the public zone, the directory is automatically created on behalf of -the user. +map, it will match this loopback mount specification. +If this loopback match occurs and the name corresponds to a valid user whose +home directory does not exist in the public zone, the directory is automatically +created on behalf of the user. .Sh OPTIONS The following options are supported: .Bl -tag -width Ds .It Fl v -Verbose mode. Notifies of +Verbose mode. +Notifies of .Nm autofs mounts, unmounts, or other non-essential information. .It Fl t Ar duration Specifies a .Ar duration , -in seconds, that a file system is to remain mounted when not in use. The default -is +in seconds, that a file system is to remain mounted when not in use. +The default is .Sy 10 minutes. .El @@ -184,8 +198,8 @@ is a comma-separated list of .Nm mount options, and .Ar location -specifies a file system from which the directory may be mounted. In the case of -a simple NFS mount, the options that can be used are specified in +specifies a file system from which the directory may be mounted. +In the case of a simple NFS mount, the options that can be used are specified in .Xr mount_nfs 1M , and .Ar location @@ -211,17 +225,19 @@ If the read-only flag is set in the map entry, .Nm automountd mounts a list of locations that the kernel may use, sorted by several criteria. Only locations available at mount time will be mounted, and thus be available to -the kernel. When a server does not respond, the kernel will switch to an -alternate server. The sort ordering of +the kernel. +When a server does not respond, the kernel will switch to an alternate server. +The sort ordering of .Nm -is used to determine how the next server is chosen. If the read-only flag is not -set, +is used to determine how the next server is chosen. +If the read-only flag is not set, .Nm will mount the best single location, chosen by the same sort ordering, and new servers will only be chosen when an unmount has been possible, and a remount is -done. Servers on the same local subnet are given the strongest preference, and -servers on the local net are given the second strongest preference. Among -servers equally far away, response times will determine the order if no +done. +Servers on the same local subnet are given the strongest preference, and servers +on the local net are given the second strongest preference. +Among servers equally far away, response times will determine the order if no weighting factors .Pq see below are used. @@ -230,9 +246,10 @@ If the list includes server locations using both the NFS Version 2 Protocol and the NFS Version 3 Protocol, .Nm will choose only a subset of the server locations on the list, so that all -entries will be the same protocol. It will choose servers with the NFS Version 3 -Protocol so long as an NFS Version 2 Protocol server on a local subnet will not -be ignored. See the FIXME for additional details. +entries will be the same protocol. +It will choose servers with the NFS Version 3 Protocol so long as an NFS Version +2 Protocol server on a local subnet will not be ignored. +See the FIXME for additional details. .Pp If each .Ar location @@ -246,11 +263,11 @@ may be used with a comma-separated list of hostnames: .Ed .Pp Requests for a server may be weighted, with the weighting factor appended to -the server name as an integer in parentheses. Servers without a weighting are -assumed to have a value of zero +the server name as an integer in parentheses. +Servers without a weighting are assumed to have a value of zero .Pq most likely to be selected . -Progressively higher values decrease the chance of being selected. In the -example, +Progressively higher values decrease the chance of being selected. +In the example, .Bd -literal -offset indent man -ro alpha,bravo,charlie(1),delta(4):/usr/man .Ed @@ -263,19 +280,21 @@ have the highest priority; host .Sy delta has the lowest. .Pp -Server proximity takes priority in the selection process. In the example above, -if the server +Server proximity takes priority in the selection process. +In the example above, if the server .Sy delta is on the same network segment as the client, but the others are on different network segments, then .Sy delta -will be selected; the weighting value is ignored. The weighting has effect only -when selecting between servers with the same network proximity. The automounter -always selects the localhost over other servers on the same network segment, -regardless of weighting. +will be selected; the weighting value is ignored. +The weighting has effect only when selecting between servers with the same +network proximity. +The automounter always selects the localhost over other servers on the same +network segment, regardless of weighting. .Pp In cases where each server has a different export point, the weighting can -still be applied. For example: +still be applied. +For example: .Bd -literal -offset indent man -ro alpha:/usr/man bravo,charlie(1):/usr/share/man \e delta(3):/export/man @@ -292,7 +311,8 @@ The ampersand .Pq Qq Sy \*(Am character is expanded to the value of the .Ar key -field for the entry in which it occurs. In this case: +field for the entry in which it occurs. +In this case: .Bd -literal -offset indent jane sparcserver:/home/& .Ed @@ -306,9 +326,9 @@ The asterisk .Pq Qq Sy * character, when supplied as the .Ar key -field, is recognized as the catch-all entry. Such an entry will match any key -not previously matched. For instance, if the following entry appeared in the -indirect map for +field, is recognized as the catch-all entry. +Such an entry will match any key not previously matched. +For instance, if the following entry appeared in the indirect map for .Pa /config : .Bd -literal -offset indent * &:/export/config/& @@ -327,12 +347,13 @@ option. .Ss Variable Substitution Client specific variables can be used within an .Nm -map. For instance, if +map. +For instance, if .Sy $HOST appeared within a map, .Nm -would expand it to its current value for the client's host name. Supported -variables are: +would expand it to its current value for the client's host name. +Supported variables are: .Bl -column "PLATFORM" "arch -k or uname -m" .It Sy NAME Ta Sy OUTPUT OF Ta Sy DESCRIPTION (EXAMPLE) .It Ev ARCH @@ -385,8 +406,8 @@ A multiple mount entry takes the form: .Pp The initial .Ar mountpoint -is optional for the first mount and mandatory for all subsequent mounts. The -optional +is optional for the first mount and mandatory for all subsequent mounts. +The optional .Ar mountpoint is taken as a pathname relative to the directory named by .Ar key . @@ -422,15 +443,16 @@ or .Sy svr2 , whichever host is nearest and responds first. .Ss Other File System Types -The automounter assumes NFS mounts as a default file system type. Other file -system types can be described using the +The automounter assumes NFS mounts as a default file system type. +Other file system types can be described using the .Sy fstype -mount option. Other mount options specific to this file system type can be -combined with the +mount option. +Other mount options specific to this file system type can be combined with the .Sy fstype -option. The location field must contain information specific to the file system -type. If the location field begins with a slash, a colon character must be -prepended, for instance, to mount a CD file system: +option. +The location field must contain information specific to the file system type. +If the location field begins with a slash, a colon character must be prepended, +for instance, to mount a CD file system: .Bd -literal -offset indent cdrom -fstype=hsfs,ro :/dev/sr0 .Ed @@ -451,23 +473,26 @@ section for information on option inheritance. An indirect map allows you to specify mappings for the subdirectories you wish to mount under the .Ar directory -indicated on the command line. In an indirect map, each +indicated on the command line. +In an indirect map, each .Ar key consists of a simple name that refers to one or more file systems that are to be mounted as needed. .Ss Direct Maps Entries in a direct map are associated directly with .Nm autofs -mount points. Each +mount points. +Each .Ar key is the full pathname of an .Nm autofs -mount point. The direct map as a whole is not associated with any single -directory. +mount point. +The direct map as a whole is not associated with any single directory. .Pp Direct maps are distinguished from indirect maps by the .Sy \- -key. For example: +key. +For example: .Bd -literal -offset indent # Master map for automounter # @@ -509,10 +534,12 @@ The .Sy -hosts map is used with the .Pa /net -directory and assumes that the map key is the hostname of an NFS server. The +directory and assumes that the map key is the hostname of an NFS server. +The .Nm automountd daemon dynamically constructs a map entry from the server's list of exported -file systems. References to a directory under +file systems. +References to a directory under .Pa /net/hermes will refer to the corresponding directory relative to .Sy hermes @@ -520,26 +547,29 @@ root. .Pp The .Sy -null -map cancels a previous map for the directory indicated. This is most useful in -the +map cancels a previous map for the directory indicated. +This is most useful in the .Pa /etc/auto_master for cancelling entries that would otherwise be inherited from the .Sy +auto_master -include entry. To be effective, the +include entry. +To be effective, the .Sy -null entries must be inserted before the included map entry. .Ss Executable Maps Local maps that have the execute bit set in their file permissions will be executed by the automounter and provided with a key to be looked up as an -argument. The executable map is expected to return the content of an -automounter map entry on its stdout or no output if the entry cannot be -determined. A direct map cannot be made executable. +argument. +The executable map is expected to return the content of an automounter map entry +on its stdout or no output if the entry cannot be determined. +A direct map cannot be made executable. .Ss Configuration and the auto_master Map When initiated without arguments, .Nm consults the master map for a list of .Nm autofs -mount points and their maps. It mounts any +mount points and their maps. +It mounts any .Nm autofs mounts that are not already mounted, and unmounts .Nm autofs @@ -547,18 +577,21 @@ mounts that have been removed from the master map or direct map. .Pp The master map is assumed to be called .Sy auto_master -and its location is determined by the name service switch policy. Normally the -master map is located initially as a local file +and its location is determined by the name service switch policy. +Normally the master map is located initially as a local file .Pa /etc/auto_master . .Ss Browsing The .Nm automountd -daemon supports browsability of indirect maps. This allows all of the potential -mount points to be visible, whether or not they are mounted. The +daemon supports browsability of indirect maps. +This allows all of the potential mount points to be visible, whether or not they +are mounted. +The .Sy -nobrowse option can be added to any indirect .Nm autofs -map to disable browsing. For example: +map to disable browsing. +For example: .Bd -literal -offset indent /net -hosts -nosuid,nobrowse /home auto_home @@ -574,21 +607,23 @@ The .Sy -browse option enables browsability of .Nm autofs -file systems. This is the default for all indirect maps. +file systems. +This is the default for all indirect maps. .Pp The .Sy -browse option does not work in conjunction with the wildcard key. .Ss Restricting Mount Maps Options specified for a map are used as the default options for all the entries -in that map. They are ignored when map entries specify their own mount options. +in that map. +They are ignored when map entries specify their own mount options. .Pp In some cases, however, it is desirable to force .Sy nosuid , nodevices , nosetuid , or .Sy noexec -for a complete mount map and its submounts. This can be done by specifying the -additional mount option, +for a complete mount map and its submounts. +This can be done by specifying the additional mount option, .Sy -restrict . .Bd -literal -offset indent /home auto_home -restrict,nosuid,hard @@ -600,13 +635,15 @@ option forces the inheritance of all the restrictive options .Sy nosuid , nodevices , nosetuid , and .Sy noexec -as well as the restrict option itself. In this particular example, the +as well as the restrict option itself. +In this particular example, the .Sy nosuid and .Sy restrict option are inherited but the .Sy hard -option is not. The +option is not. +The .Sy restrict option also prevents the execution of .Qq executable maps @@ -619,7 +656,8 @@ Master automount map. .It Pa /etc/auto_home Map to support automounted home directories. .It Pa /etc/nsswitch.conf -Name service switch configuration file. See +Name service switch configuration file. +See .Xr nsswitch.conf 4 . .El .Sh EXIT STATUS @@ -651,15 +689,16 @@ Since each direct map entry results in a new .Nm autofs mount such maps should be kept short. .Pp -Entries in both direct and indirect maps can be modified at any time. The new -information is used when +Entries in both direct and indirect maps can be modified at any time. +The new information is used when .Nm automountd next uses the map entry to do a mount. .Pp New entries added to a master map or direct map will not be useful until the automount command is run to install them as new .Nm autofs -mount points. New entries added to an indirect map may be used immediately. +mount points. +New entries added to an indirect map may be used immediately. .Pp As of the Solaris 2.6 release, a listing .Po see @@ -668,19 +707,22 @@ As of the Solaris 2.6 release, a listing of the .Nm autofs directory associated with an indirect map shows all potential mountable -entries. The attributes associated with the potential mountable entries are -temporary. The real file system attributes will only be shown once the file -system has been mounted. +entries. +The attributes associated with the potential mountable entries are temporary. +The real file system attributes will only be shown once the file system has been +mounted. .Pp Default mount options can be assigned to an entire map when specified as an -optional third field in the master map. These options apply only to map entries -that have no mount options. Note that map entities with options override the -default options, as at this time, the options do not concatenate. The -concatenation feature is planned for a future release. +optional third field in the master map. +These options apply only to map entries that have no mount options. +Note that map entities with options override the default options, as at this +time, the options do not concatenate. +The concatenation feature is planned for a future release. .Pp When operating on a map that invokes an NFS mount, the default number of retries for the automounter is 0, that is, a single mount attempt, with no -retries. Note that this is significantly different from the default +retries. +Note that this is significantly different from the default .Pq 10000 for the .Xr mount_nfs 1M diff --git a/usr/src/man/man1m/automountd.1m b/usr/src/man/man1m/automountd.1m index 65f59d37b6..033bc50875 100644 --- a/usr/src/man/man1m/automountd.1m +++ b/usr/src/man/man1m/automountd.1m @@ -33,8 +33,9 @@ .Nm is an RPC server that answers file system mount and unmount requests from the .Nm autofs -file system. It uses local files or name service maps to locate file systems to -be mounted. These maps are described with the +file system. +It uses local files or name service maps to locate file systems to be mounted. +These maps are described with the .Xr automount 1M command. .Pp @@ -59,20 +60,23 @@ Assign .Ar value to the indicated .Nm automount -map substitution variable. These assignments cannot be used to substitute -variables in the master map +map substitution variable. +These assignments cannot be used to substitute variables in the master map .Sy auto_master . .It Fl n Turn off browsing for all .Nm autofs -mount points. This option overrides the +mount points. +This option overrides the .Sy -browse .Nm autofs map option on the local host. .It Fl T -Trace. Expand each RPC call and display it on the standard output. +Trace. +Expand each RPC call and display it on the standard output. .It Fl v -Verbose. Log status messages to the console. +Verbose. +Log status messages to the console. .El .Sh USAGE See diff --git a/usr/src/man/man1m/catman.1m b/usr/src/man/man1m/catman.1m index 5a79706553..9a49874838 100644 --- a/usr/src/man/man1m/catman.1m +++ b/usr/src/man/man1m/catman.1m @@ -32,8 +32,8 @@ database files suitable for use with .Xr apropos 1 and .Xr whatis 1 . -It is supplied for compatibility reasons. The same databases can -be generated using the +It is supplied for compatibility reasons. +The same databases can be generated using the .Fl w option with .Xr man 1 , diff --git a/usr/src/man/man1m/diskinfo.1m b/usr/src/man/man1m/diskinfo.1m index 867592fef9..8218c7f1ad 100644 --- a/usr/src/man/man1m/diskinfo.1m +++ b/usr/src/man/man1m/diskinfo.1m @@ -47,8 +47,8 @@ option selects physical mode. In this mode, each line of output likewise describes one disk device; however, the fields provided indicate the base name of the device in the .Pa /dev/dsk -directory, the disk's vendor and product identification strings, the serial number of the -device, whether the device is faulty as diagnosed by +directory, the disk's vendor and product identification strings, the serial +number of the device, whether the device is faulty as diagnosed by .Xr fmd 1M , whether the locate or identification indicator is on for the device .Pq if one is present , @@ -156,8 +156,8 @@ that report themselves as removable will be identified as such. .Pp This field is available only in default output mode. .It Sy SERIAL -The serial number of the device. The entire serial number is reported if the -device and its drivers provide it. +The serial number of the device. +The entire serial number is reported if the device and its drivers provide it. .Pp This field is available in compact and physical output modes. .It Sy SIZE diff --git a/usr/src/man/man1m/dns-sd.1m b/usr/src/man/man1m/dns-sd.1m index 5fa529bfcc..df37743662 100644 --- a/usr/src/man/man1m/dns-sd.1m +++ b/usr/src/man/man1m/dns-sd.1m @@ -79,18 +79,18 @@ The .Nm command is primarily intended for interactive use. Because its command-line arguments and output format are subject to change, -invoking it from a shell script will generally be fragile. Additionally, -the asynchronous nature of DNS Service Discovery does -not lend itself easily to script-oriented programming. For example, -calls like "browse" never complete; the action of performing a "browse" -sets in motion machinery to notify the client whenever instances of -that service type appear or disappear from the network. These -notifications continue to be delivered indefinitely, for minutes, +invoking it from a shell script will generally be fragile. +Additionally, the asynchronous nature of DNS Service Discovery does +not lend itself easily to script-oriented programming. +For example, calls like "browse" never complete; the action of performing a +"browse" sets in motion machinery to notify the client whenever instances of +that service type appear or disappear from the network. +These notifications continue to be delivered indefinitely, for minutes, hours, or even days, as services come and go, until the client -explicitly terminates the call. This style of asynchronous interaction -works best with applications that are either multi-threaded, or use a -main event-handling loop to receive keystrokes, network data, and other -asynchronous event notifications as they happen. +explicitly terminates the call. +This style of asynchronous interaction works best with applications that are +either multi-threaded, or use a main event-handling loop to receive keystrokes, +network data, and other asynchronous event notifications as they happen. .br If you wish to perform DNS Service Discovery operations from a scripting language, then the best way to do this is not to execute the @@ -109,7 +109,8 @@ return a list of domains recommended for registering(advertising) services. .It Nm Fl F return a list of domains recommended for browsing services. .Pp -Normally, on your home network, the only domain you are likely to see is "local". +Normally, on your home network, the only domain you are likely to see is +"local". However if your network administrator has created Domain Enumeration records, then you may also see other recommended domains for registering and browsing. .It Nm Fl R Ar name type domain port Op Ar key=value ... @@ -134,8 +135,10 @@ must be of the form "_app-proto._tcp" or "_app-proto._udp", where .Ar domain is the domain in which to register the service. In current implementations, only the local multicast domain "local" is -supported. In the future, registering will be supported in any arbitrary -domain that has a working DNS Update server [RFC 2136]. The +supported. +In the future, registering will be supported in any arbitrary domain that has a +working DNS Update server [RFC 2136]. +The .Ar domain "." is a synonym for "pick a sensible default" which today means "local". @@ -146,8 +149,8 @@ which the service is listening. .Pp Additional attributes of the service may optionally be described by key/value pairs, which are stored in the advertised service's DNS TXT -record. Allowable keys and values are listed with the service -registration at +record. +Allowable keys and values are listed with the service registration at .Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . .It Nm Fl B Ar type domain browse for instances of service @@ -159,7 +162,8 @@ For valid .Ar type Ns s see .Pa http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml . -as described above. Omitting the +as described above. +Omitting the .Ar domain or using "." means "pick a sensible default." .It Nm Fl L Ar name type domain @@ -168,32 +172,36 @@ named service: the hostname of the machine where that service is available, the port number on which the service is listening, and (if present) TXT record attributes describing properties of the service. .Pp -Note that in a typical application, browsing may only happen rarely, while lookup -(or "resolving") happens every time the service is used. For example, a -user browses the network to pick a default printer fairly rarely, but once -a default printer has been picked, that named service is resolved to its -current IP address and port number every time the user presses Cmd-P to +Note that in a typical application, browsing may only happen rarely, while +lookup (or "resolving") happens every time the service is used. +For example, a user browses the network to pick a default printer fairly rarely, +but once a default printer has been picked, that named service is resolved to +its current IP address and port number every time the user presses Cmd-P to print. .It Nm Fl P Ar name type domain port host IP Op Ar key=value ... -create a proxy advertisement for a service running on(offered by) some other machine. +create a proxy advertisement for a service running on(offered by) some other +machine. The two new options are Host, a name for the device and IP, the address of it. .Pp -The service for which you create a proxy advertisement does not necessarily have to be on your local network. +The service for which you create a proxy advertisement does not necessarily have +to be on your local network. You can set up a local proxy for a website on the Internet. .It Nm Fl q Ar name rrtype rrclass look up any DNS name, resource record type, and resource record class, not necessarily DNS-SD names and record types. If rrtype is not specified, it queries for the IPv4 address of the name, -if rrclass is not specified, IN class is assumed. If the name is not a fully -qualified domain name, then search domains may be appended. +if rrclass is not specified, IN class is assumed. +If the name is not a fully qualified domain name, then search domains may be +appended. .It Nm Fl Z Ar type domain browse for service instances and display output in zone file format. .It Nm Fl G Ns \ v4/v6/v4v6 Ar name look up the IP address information of the name. If v4 is specified, the IPv4 address of the name is looked up, -if v6 is specified the IPv6 address is looked up. If v4v6 is specified both the IPv4 and IPv6 -address is looked up. If the name is not a fully qualified domain name, -then search domains may be appended. +if v6 is specified the IPv6 address is looked up. +If v4v6 is specified both the IPv4 and IPv6 address is looked up. +If the name is not a fully qualified domain name, then search domains may be +appended. .It Nm Fl V return the version of the currently running daemon/system service. .El @@ -208,9 +216,9 @@ and other DNS-SD compatible printing clients, use: .Dl Nm Fl R Ns \ \&"My Test\&" _printer._tcp. \&. 515 pdl=application/postscript .Pp For this registration to be useful, you need to actually have LPR service -available on port 515. Advertising a service that does not exist is not -very useful, and will be confusing and annoying to other people on the -network. +available on port 515. +Advertising a service that does not exist is not very useful, and will be +confusing and annoying to other people on the network. .Pp Similarly, to advertise a web page being served by an HTTP server on port 80 on this machine, such that it will show up in the @@ -228,21 +236,23 @@ While that command is running, in another window, try the example given above to advertise a web page, and you should see the "Add" event reported to the .Nm Fl B -window. Now press Ctrl-C in the +window. +Now press Ctrl-C in the .Nm Fl R window and you should see the "Remove" event reported to the .Nm Fl B window. .Pp -In the example below, the www.apple.com web page is advertised as a service called "apple", +In the example below, the www.apple.com web page is advertised as a service +called "apple", running on a target host called apple.local, which resolves to 17.149.160.49. .Pp .Dl Nm Fl P Ns \ apple _http._tcp \&"\&"\& 80 apple.local 17.149.160.49 .Pp The Bonjour menu in the Safari web browser will now show "apple". The same IP address can be reached by entering apple.local in the web browser. -In either case, the request will be resolved to the IP address and browser will show -contents associated with www.apple.com. +In either case, the request will be resolved to the IP address and browser will +show contents associated with www.apple.com. .Pp If a client wants to be notified of changes in server state, it can initiate a query for the service's particular record and leave it running. @@ -250,7 +260,8 @@ For example, to monitor the status of an iChat user you can use: .Pp .Dl Nm Fl q Ns \ someone@ex1._presence._tcp.local txt .Pp -Everytime status of that user(someone) changes, you will see a new TXT record result reported. +Everytime status of that user(someone) changes, you will see a new TXT record +result reported. .Pp You can also query for a unicast name like www.apple.com and monitor its status. .Pp diff --git a/usr/src/man/man1m/installboot.1m b/usr/src/man/man1m/installboot.1m index d17d800f2f..0c1dd82c76 100644 --- a/usr/src/man/man1m/installboot.1m +++ b/usr/src/man/man1m/installboot.1m @@ -54,8 +54,9 @@ boot program is loaded from disk and is responsible of loading kernel and its support files from specific file system. .Pp The SPARC systems have one boot loader program file to be installed on the boot -area of a disk slice. As the SPARC zfs boot loader is too large to fit into -boot area at the start of the disk slice, +area of a disk slice. +As the SPARC zfs boot loader is too large to fit into boot area at the start of +the disk slice, .Nm command will split the zfs boot loader between disk slice boot area, and zfs pool boot area. @@ -69,7 +70,8 @@ is used as master boot record and partition boot program. .It Sy stage2 .Pa /boot/gptzfsboot -is responsible for loading files from file system. The +is responsible for loading files from file system. +The .Sy stage2 on x86 systems is always installed to zfs pool boot area, and therefore only zfs boot is supported. @@ -99,8 +101,9 @@ and starting the operating system kernel. In case of GPT partitioning scheme, if the file system to boot from is either UFS or PCFS, there must be .Sy boot -partition defined to store stage2 boot program. This is needed because UFS and -PCFS do not have sufficient space reserved to store boot programs. +partition defined to store stage2 boot program. +This is needed because UFS and PCFS do not have sufficient space reserved to +store boot programs. .Pp The boot partition must use following GPT UUID: .Bd -literal -offset indent @@ -123,19 +126,22 @@ Prints short usage message. .It Fl m Installs .Sy stage1 -on the master boot sector interactively. You must use this option if OS is -installed on an extended FDISK or an EFI/GPT partition. +on the master boot sector interactively. +You must use this option if OS is installed on an extended FDISK or an EFI/GPT +partition. .It Fl f Suppresses interaction when overwriting the master boot sector on x86. Force update on SPARC. .It Fl n -Dry run session. Will not write to disk. +Dry run session. +Will not write to disk. .It Fl F -On SPARC, specify file system type. On x86, inhibit version check and enforce -boot loader update. +On SPARC, specify file system type. +On x86, inhibit version check and enforce boot loader update. .It Fl u Ar verstr -Specify custom version string. Can be used to add version on non-versioned -boot loader or change built in version string. +Specify custom version string. +Can be used to add version on non-versioned boot loader or change built in +version string. .It Fl i Print version string from installed boot loader or from indicated file. .It Fl e @@ -157,8 +163,9 @@ The name of the loader stage 1 file. .It Ar stage2 The name of the loader stage 2 file. .It Ar raw-device -The name of the device onto which bootloader code is to be installed. It must be -a character device that is readable and writable and part of boot pool. +The name of the device onto which bootloader code is to be installed. +It must be a character device that is readable and writable and part of boot +pool. .El .Sh FILES .Bl -tag -width Ds @@ -199,11 +206,11 @@ on the master boot sector .Fl m option .Pc -overrides any boot loader currently installed on the machine. The system will -always boot the current OS partition regardless of which fdisk partition is -active. +overrides any boot loader currently installed on the machine. +The system will always boot the current OS partition regardless of which fdisk +partition is active. .Pp If version string indicates the source boot loader might be more recent, .Nm -will also verify md5 checksums to determine if update is really necessary. If -checksums match, the install will not be performed. +will also verify md5 checksums to determine if update is really necessary. +If checksums match, the install will not be performed. diff --git a/usr/src/man/man1m/ipadm.1m b/usr/src/man/man1m/ipadm.1m index 06e5f87cc2..dc3ea104c9 100644 --- a/usr/src/man/man1m/ipadm.1m +++ b/usr/src/man/man1m/ipadm.1m @@ -145,19 +145,22 @@ command is a stable replacement for the .Xr ifconfig 1M and .Xr ndd 1M -commands. It is used to create IP interfaces and to configure IP addresses on -those interfaces. It is also used to get, set or reset properties on interfaces, -addresses and protocols. +commands. +It is used to create IP interfaces and to configure IP addresses on those +interfaces. +It is also used to get, set or reset properties on interfaces, addresses and +protocols. .Pp For subcommands that take an .Em addrobj , the .Em addrobj -specifies a unique address on the system. It is made up of two parts, delimited -by a +specifies a unique address on the system. +It is made up of two parts, delimited by a .Sq / . The first part is the name of the interface and the second part is a string up -to 32 characters long. For example, +to 32 characters long. +For example, .Qq lo0/v4 is a loopback interface .Em addrobj @@ -183,9 +186,10 @@ The following subcommands are supported: .Op Fl t .Ar interface .Xc -Create an IP interface that will handle both IPv4 and IPv6 packets. The -interface will be enabled as part of the creation process. The IPv4 interface -will have the address 0.0.0.0. The IPv6 interface will have the address ::. +Create an IP interface that will handle both IPv4 and IPv6 packets. +The interface will be enabled as part of the creation process. +The IPv4 interface will have the address 0.0.0.0. +The IPv6 interface will have the address ::. .Bl -tag -width "" .It Fl t Ns , Ns Fl -temporary Temporary, not persistent across reboots. @@ -227,8 +231,8 @@ Permanently delete an IP interface. Show the current IP interface configuration. .Bl -tag -width "" .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -304,8 +308,8 @@ Set a property's value(s) on the IP interface. .It Fl m Ns , Ns Fl -module Specify which protocol the setting applies to. .It Fl p Ns , Ns Fl -prop -Specify the property name and value(s). The property name can be one of the -following: +Specify the property name and value(s). +The property name can be one of the following: .Bl -tag -compact -width "exchange_routes" .It Cm arp Address resolution protocol @@ -317,15 +321,16 @@ Exchange of routing data IP Forwarding .Pq Cm on Ns / Ns Cm off .It Cm metric -Set the routing metric to the numeric value. The value is treated as extra -hops to the destination. +Set the routing metric to the numeric value. +The value is treated as extra hops to the destination. .It Cm mtu Set the maximum transmission unit to the numeric value. .It Cm nud Neighbor unreachability detection .Pq Cm on Ns / Ns Cm off .It Cm usesrc -Indicates which interface to use for source address selection. A value +Indicates which interface to use for source address selection. +A value .Cm none may also be used. .El @@ -345,7 +350,8 @@ Reset an IP interface's property value to the default. .It Fl m Ns , Ns Fl -module Specify which protocol the setting applies to. .It Fl p Ns , Ns Fl -prop -Specify the property name. See the +Specify the property name. +See the .Nm ipadm Ic set-ifprop subcommand for the list of property names. .It Fl t Ns , Ns Fl -temporary @@ -366,8 +372,8 @@ Print the output in a parsable format. .It Fl m Ns , Ns Fl -module Specify which protocol to display. .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -392,7 +398,8 @@ The default value of the property. The possible values for the property. .El .It Fl p Ns , Ns Fl -prop -Specify which properties to display. See the +Specify which properties to display. +See the .Nm ipadm Ic set-ifprop subcommand for the list of property names. .El @@ -422,28 +429,32 @@ subcommand for the list of property names. .Bro Cm yes Ns | Ns Cm no Brc Oc Ns ... .Ar addrobj .Xc -Create an address on an IP interface. The address will be enabled but can -disabled using the +Create an address on an IP interface. +The address will be enabled but can disabled using the .Nm ipadm Ic disable-addr -subcommand. This subcommand has three different forms, depending on the -value of the +subcommand. +This subcommand has three different forms, depending on the value of the .Fl T option. .Bl -tag -width "" .It Fl T Cm static -Create a static addrobj. Note that +Create a static addrobj. +Note that .Cm addrconf address configured on an interface is required to configure .Cm static -IPv6 address on the same interface. This takes the following options: +IPv6 address on the same interface. +This takes the following options: .Bl -tag -width "" .It Fl a Ns , Ns Fl -address -Specify the address. The +Specify the address. +The .Cm local or .Cm remote -prefix can be used for a point-to-point interface. In this case, both addresses -must be given. Otherwise, the equal sign +prefix can be used for a point-to-point interface. +In this case, both addresses must be given. +Otherwise, the equal sign .Pq Qq = should be omitted and the address should be provided by itself without second address. @@ -451,13 +462,15 @@ address. The address is down. .El .It Fl T Cm dhcp -Obtain the address via DHCP. This takes the following options: +Obtain the address via DHCP. +This takes the following options: .Bl -tag -width "" .It Fl w Ns , Ns Fl -wait Specify the time, in seconds, that the command should wait to obtain an address. .El .It Fl T Cm addrconf -Create an auto-configured address. This takes the following options: +Create an auto-configured address. +This takes the following options: .Bl -tag -width "" .It Fl i Ns , Ns Fl -interface-id Specify the interface ID to be used. @@ -473,7 +486,8 @@ Temporary, not persistent across reboots. .Op Fl t .Ar addrobj .Xc -Down the address. This will stop packets from being sent or received. +Down the address. +This will stop packets from being sent or received. .Bl -tag -width "" .It Fl t Ns , Ns Fl -temporary Temporary, not persistent across reboots. @@ -484,7 +498,8 @@ Temporary, not persistent across reboots. .Op Fl t .Ar addrobj .Xc -Up the address. This will enable packets to be sent and received. +Up the address. +This will enable packets to be sent and received. .Bl -tag -width "" .It Fl t Ns , Ns Fl -temporary Temporary, not persistent across reboots. @@ -519,8 +534,8 @@ Temporary, not persistent across reboots. .Xc Extend the lease for .Sy DHCP -addresses. It also restarts duplicate address -detection for +addresses. +It also restarts duplicate address detection for .Cm static addresses. .Bl -tag -width "" @@ -547,8 +562,8 @@ Indicate that the DHCP-assigned address should be released. Show the current address properties. .Bl -tag -width "" .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -558,7 +573,8 @@ The name of the address. The type of the address .Pq Sy static Ns / Ns Sy dhcp Ns / Ns Sy addrconf . .It Cm STATE -The state of the address. It can be one of the following values: +The state of the address. +It can be one of the following values: .Bl -tag -compact -width "inaccessible" .It Sy disabled see the @@ -621,8 +637,8 @@ Print the output in a parsable format. Set a property's value(s) on the addrobj. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name and value(s). The property name can be one of the -following: +Specify the property name and value(s). +The property name can be one of the following: .Bl -tag -compact -width "deprecated" .It Cm broadcast The broadcast address (read-only). @@ -653,7 +669,8 @@ Temporary, not persistent across reboots. Reset an addrobj's property value to the default. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name. See the +Specify the property name. +See the .Nm ipadm Ic set-addrprop subcommand for the list of property names. .It Fl t Ns , Ns Fl -temporary @@ -671,8 +688,8 @@ Display the property values for one or all of the addrobjs. .It Fl c Ns , Ns Fl -parsable Print the output in a parsable format. .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -695,7 +712,8 @@ The default value of the property. The possible values for the property. .El .It Fl p Ns , Ns Fl -prop -Specify which properties to display. See the +Specify which properties to display. +See the .Nm ipadm Ic set-addrprop subcommand for the list of property names. .El @@ -709,10 +727,12 @@ subcommand for the list of property names. Set a property's value(s) on the protocol. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name and value(s). The optional +Specify the property name and value(s). +The optional .Sy + Ns | Ns Sy - syntax can be used to add/remove values from the current list of values on the -property. The property name can be one of the following: +property. +The property name can be one of the following: .Bl -tag -compact -width "smallest_nonpriv_port" .It Cm ecn Explicit congestion control @@ -775,7 +795,8 @@ Temporary, not persistent across reboots. Reset a protocol's property value to the default. .Bl -tag -width "" .It Fl p Ns , Ns Fl -prop -Specify the property name. See the +Specify the property name. +See the .Nm ipadm Ic set-prop subcommand for the list of property names. .It Fl t Ns , Ns Fl -temporary @@ -793,8 +814,8 @@ Display the property values for one or all of the protocols. .It Fl c Ns , Ns Fl -parsable Print the output in a parsable format. .It Fl o Ns , Ns Fl -output -Select which fields will be shown. The field value can be one of the following -names: +Select which fields will be shown. +The field value can be one of the following names: .Bl -tag -compact -width "PERSISTENT" .It Cm ALL Display all fields. @@ -817,7 +838,8 @@ The default value of the property. The possible values for the property. .El .It Fl p Ns , Ns Fl -prop -Specify which properties to display. See the +Specify which properties to display. +See the .Nm ipadm Ic set-prop subcommand for the list of property names. .El diff --git a/usr/src/man/man1m/lofiadm.1m b/usr/src/man/man1m/lofiadm.1m index 5eede96b52..750e2c732a 100644 --- a/usr/src/man/man1m/lofiadm.1m +++ b/usr/src/man/man1m/lofiadm.1m @@ -59,12 +59,14 @@ administers .Sy lofi , the loopback file driver. .Sy lofi -allows a file to be associated with a block device. That file can then be -accessed through the block device. This is useful when the file contains an -image of some filesystem (such as a floppy or +allows a file to be associated with a block device. +That file can then be accessed through the block device. +This is useful when the file contains an image of some filesystem (such as a +floppy or .Sy CD-ROM image), because the block device can then be used with the normal system -utilities for mounting, checking or repairing filesystems. See +utilities for mounting, checking or repairing filesystems. +See .Xr fsck 1M and .Xr mount 1M . @@ -98,16 +100,19 @@ partitioning by using partition management tools such as .Xr fdisk 1M . Once the device has been appropriately partitioned, the labeled device can be used as normal disk to create and mount file systems and to store -data. Mappings created by +data. +Mappings created by .Nm -are not permanent and not persisted by the system. If power is lost or the system -is rebooted, then the mappings will need to be created again. +are not permanent and not persisted by the system. +If power is lost or the system is rebooted, then the mappings will need to be +created again. .Pp The partition table requires space from the mapped file. .Sy lofi does not support converting previously created unlabeled loopback device images -to labeled loopback devices. If an unlabeled device is used as a labeled device, -writing to it will corrupt it. +to labeled loopback devices. +If an unlabeled device is used as a labeled device, writing to it will corrupt +it. .Sh OPTIONS The following options are supported: .Bl -tag -width Ds @@ -129,8 +134,9 @@ attempts to assign it to .Sy device must be available or .Nm -will fail. The ability to specify a device is provided for use in scripts that -wish to reestablish a particular set of associations. +will fail. +The ability to specify a device is provided for use in scripts that wish to +reestablish a particular set of associations. A device may not be specified when using a labeled lofi device. .It Fl C Ar {gzip | gzip-N | lzma} Compress the file with the specified compression algorithm. @@ -139,10 +145,12 @@ The .Sy gzip compression algorithm uses the same compression as the open-source .Sy gzip -command. You can specify the +command. +You can specify the .Sy gzip level by using the value gzip-\fR\fIN\fR where \fIN\fR is 6 (fast) or 9 -(best compression ratio). Currently, +(best compression ratio). +Currently, .Sy gzip , without a number, is equivalent to .Sy gzip-6 @@ -165,8 +173,8 @@ device. .It Fl l This option should be used with .Fl a -option to create labeled loopback device. If created in local zone, the device -has to be enabled in zone configuration. +option to create labeled loopback device. +If created in local zone, the device has to be enabled in zone configuration. .It Fl r If the .Fl r @@ -186,8 +194,9 @@ Uncompress a compressed file. The following options are used when the file is encrypted: .Bl -tag -width Ds .It Fl c Ar crypto_algorithm -Select the encryption algorithm. The algorithm must be specified when -encryption is enabled because the algorithm is not stored in the disk image. +Select the encryption algorithm. +The algorithm must be specified when encryption is enabled because the algorithm +is not stored in the disk image. .Pp If none of .Fl e , @@ -200,10 +209,11 @@ prompts for a passphrase, with a minimum length of eight characters, to be entered. The passphrase is used to derive a symmetric encryption key using PKCS#5 PBKD2. .It Fl k Ar raw_key_file | Ar wrapped_key_file -Path to raw or wrapped symmetric encryption key. If a PKCS#11 object is also -given with the +Path to raw or wrapped symmetric encryption key. +If a PKCS#11 object is also given with the .Fl T -option, then the key is wrapped by that object. If +option, then the key is wrapped by that object. +If .Fl T is not specified, the key is used raw. .It Fl T Ar token_key @@ -232,15 +242,15 @@ One of: Display the file name associated with the block device .Sy device . .Pp -Without arguments, print a list of the current associations. Filenames must be -valid absolute pathnames. +Without arguments, print a list of the current associations. +Filenames must be valid absolute pathnames. .Pp -When a file is added, it is opened for reading or writing by root. Any -restrictions apply (such as restricted root access over +When a file is added, it is opened for reading or writing by root. +Any restrictions apply (such as restricted root access over .Sy NFS Ns ). -The file is held open until the association is removed. It is not actually -accessed until the block device is used, so it will never be written to if the -block device is only opened read-only. +The file is held open until the association is removed. +It is not actually accessed until the block device is used, so it will never be +written to if the block device is only opened read-only. .Pp Note that the filename may appear as "?" if it is not possible to resolve the path in the current context (for example, if it's an NFS path in a non-global @@ -256,8 +266,8 @@ PKCS#11 token object in the format: .Pp .Ar token_name Ns : Ns Ar manufacturer_id Ns : Ns Ar serial_number Ns : Ns Ar key_label .Pp -All but the key label are optional and can be empty. For example, to specify a -token object with only its key label +All but the key label are optional and can be empty. +For example, to specify a token object with only its key label .Sy MylofiKey , use: .Pp @@ -300,8 +310,8 @@ image .Pf ( Sy sparc.iso Ns ), of the .Sy Red Hat 6.0 CD -which was downloaded from the Internet. It was created -with the +which was downloaded from the Internet. +It was created with the .Sy mkisofs utility from the Internet. .Pp @@ -315,7 +325,8 @@ to attach a block device to it: .Pp .Nm picks the device and prints the device name to the standard -output. You can run +output. +You can run .Nm again by issuing the following command: .Bd -literal @@ -352,8 +363,8 @@ README boot.cat* kernels/ modules/ RPM-PGP-KEY dev@ lib@ proc/ .Ed .Pp -Solaris can mount the CD-ROM image, and understand the filenames. The image was -created properly, and you can now create the +Solaris can mount the CD-ROM image, and understand the filenames. +The image was created properly, and you can now create the .Sy CD-ROM with confidence. .Pp @@ -371,8 +382,8 @@ Using .Sy lofi to help you mount files that contain floppy images is helpful if a floppy disk contains a file that you need, but the machine which you are -on does not have a floppy drive. It is also helpful if you do not want to take -the time to use the +on does not have a floppy drive. +It is also helpful if you do not want to take the time to use the .Sy dd command to copy the image to a floppy. .Pp @@ -394,8 +405,10 @@ APPEND.BAT* MAKEDIR.BAT* SOLARIS/ Making a .Sy UFS filesystem on a file can be useful, particularly if a test -suite requires a scratch filesystem. It can be painful (or annoying) to have to -repartition a disk just for the test suite, but you do not have to. You can +suite requires a scratch filesystem. +It can be painful (or annoying) to have to repartition a disk just for the test +suite, but you do not have to. +You can .Sy newfs a file with .Sy lofi . @@ -405,7 +418,8 @@ Create the file: # mkfile 35m /export/home/test .Ed .Pp -Attach it to a block device. You also get the character device that +Attach it to a block device. +You also get the character device that .Sy newfs requires, so .Sy newfs @@ -423,7 +437,8 @@ super-block backups (for fsck -F ufs -o b=#) at: .Pp Note that .Sy ufs -might not be able to use the entire file. Mount and use the filesystem: +might not be able to use the entire file. +Mount and use the filesystem: .Bd -literal # mount /dev/lofi/1 /mnt # df -k /mnt @@ -437,7 +452,8 @@ Filesystem kbytes used avail capacity Mounted on .It Sy Example 4 No Creating a PC (FAT) File System on a Unix File The following series of commands creates a .Sy FAT -file system on a Unix file. The file is associated with a block device created by +file system on a Unix file. +The file is associated with a block device created by .Nm . .Bd -literal @@ -575,8 +591,9 @@ Just as you would not directly access a disk device that has mounted file systems, you should not access a file associated with a block device except through the .Sy lofi -file driver. It might also be appropriate to ensure that -the file has appropriate permissions to prevent such access. +file driver. +It might also be appropriate to ensure that the file has appropriate permissions +to prevent such access. .Pp The abilities of .Nm @@ -584,8 +601,10 @@ The abilities of permissions of .Pa /dev/lofictl . Read-access allows query operations, such as -listing all the associations. Write-access is required to do any state-changing -operations, like adding an association. As shipped, +listing all the associations. +Write-access is required to do any state-changing operations, like adding an +association. +As shipped, .Pa /dev/lofictl is owned by .Sy root , @@ -603,15 +622,16 @@ In particular, the .Sy nosuid mount option might be appropriate for .Sy UFS -images whose origin is unknown. Also, some options might not be useful or -appropriate, like +images whose origin is unknown. +Also, some options might not be useful or appropriate, like .Sy logging or .Sy forcedirectio for .Sy UFS . For compatibility purposes, a raw device is also exported along with the block -device. For example, +device. +For example, .Xr newfs 1M requires one. .Pp diff --git a/usr/src/man/man1m/mount_nfs.1m b/usr/src/man/man1m/mount_nfs.1m index 7c26819813..4992fa1b7b 100644 --- a/usr/src/man/man1m/mount_nfs.1m +++ b/usr/src/man/man1m/mount_nfs.1m @@ -48,7 +48,8 @@ utility attaches a named .Ar resource to the file system hierarchy at the pathname location .Ar mount_point , -which must already exist. If +which must already exist. +If .Ar mount_point has any contents prior to the .Nm mount @@ -73,7 +74,8 @@ and .Nm mount consults .Pa /etc/vfstab -for more information. If the +for more information. +If the .Fl F option is omitted, .Nm mount @@ -88,12 +90,12 @@ and the .Ar mount_point . .Pp .Ar host -can be an IPv4 or IPv6 address string. As IPv6 addresses already contain colons, -enclose +can be an IPv4 or IPv6 address string. +As IPv6 addresses already contain colons, enclose .Ar host -in a pair of square brackets when specifying an IPv6 address string. Otherwise -the first occurrence of a colon can be interpreted as the separator between the -host name and path, for example, +in a pair of square brackets when specifying an IPv6 address string. +Otherwise the first occurrence of a colon can be interpreted as the separator +between the host name and path, for example, .Li [1080::8:800:200C:417A]:tmp/file . See .Xr inet 7P @@ -105,9 +107,10 @@ Where .Ar host is the name of the NFS server host, and .Ar pathname -is the path name of the directory on the server being mounted. The path name is -interpreted according to the server's path name parsing rules and is not -necessarily slash-separated, though on most servers, this is the case. +is the path name of the directory on the server being mounted. +The path name is interpreted according to the server's path name parsing rules +and is not necessarily slash-separated, though on most servers, this is the +case. .It No nfs:// Ns Ar host Ns Oo : Ns Ar port Oc Ns / Ns Ar pathname This is an NFS URL and follows the standard convention for NFS URLs as described in @@ -130,8 +133,8 @@ See the discussion of replicated file systems and failover under for a more detailed discussion. .It Ar hostlist pathname .Ar hostlist -is a comma-separated list of hosts. See the discussion of replicated file -systems and failover under +is a comma-separated list of hosts. +See the discussion of replicated file systems and failover under .Sx NFS FILE SYSTEMS for a more detailed discussion. .El @@ -144,7 +147,8 @@ described in .Xr mnttab 4 . .Pp .Nm mount_nfs -supports both NFSv3 and NFSv4 mounts. The default NFS version is NFSv4. +supports both NFSv3 and NFSv4 mounts. +The default NFS version is NFSv4. .Ss Options See .Xr mount 1M @@ -170,15 +174,18 @@ The default value is 60. .It Sy acdirmin Ns = Ns Ar n Hold cached attributes for at least .Ar n -seconds after directory update. The default value is 30. +seconds after directory update. +The default value is 30. .It Sy acregmax Ns = Ns Ar n Hold cached attributes for no more than .Ar n -seconds after file modification. The default value is 60. +seconds after file modification. +The default value is 60. .It Sy acregmin Ns = Ns Ar n Hold cached attributes for at least .Ar n -seconds after file modification. The default value is 3. +seconds after file modification. +The default value is 3. .It Sy actimeo Ns = Ns n Set .Sy min @@ -186,7 +193,8 @@ and .Sy max times for regular files and directories to .Ar n -seconds. See +seconds. +See .Sx File Attributes , below, for a description of the effect of setting this option to 0. .Pp @@ -200,22 +208,24 @@ are parsed on a .Nm mount command line. .It Sy bg Ns | Ns Sy fg -If the first attempt fails, retry in the background, or, in the foreground. The -default is +If the first attempt fails, retry in the background, or, in the foreground. +The default is .Sy fg . .It Sy forcedirectio Ns | Ns Sy noforcedirectio If .Sy forcedirectio -is specified, then for the duration of the mount, forced direct I/O is used. If -the filesystem is mounted using +is specified, then for the duration of the mount, forced direct I/O is used. +If the filesystem is mounted using .Sy forcedirectio , data is transferred directly between client and server, with no buffering on the -client. If the filesystem is mounted using +client. +If the filesystem is mounted using .Sy noforcedirectio , data is buffered on the client. .Sy forcedirectio is a performance option that is of benefit only in large sequential data -transfers. The default behavior is +transfers. +The default behavior is .Sy noforcedirectio . .It Sy grpid By default, the GID associated with a newly created file obeys the System V @@ -245,32 +255,37 @@ Note that NFSv4 clients do not support soft mounts. Allow .Pq do not allow keyboard interrupts to kill a process that is hung while waiting for a response -on a hard-mounted file system. The default is +on a hard-mounted file system. +The default is .Sy intr , which makes it possible for clients to interrupt applications that can be waiting for a remote mount. .It Sy noac -Suppress data and attribute caching. The data caching that is suppressed is the -write-behind. The local page cache is still maintained, but data copied into it -is immediately written to the server. +Suppress data and attribute caching. +The data caching that is suppressed is the write-behind. +The local page cache is still maintained, but data copied into it is immediately +written to the server. .It Sy nocto -Do not perform the normal close-to-open consistency. When a file is closed, all -modified data associated with the file is flushed to the server and not held on -the client. When a file is opened the client sends a request to the server to -validate the client's local caches. This behavior ensures a file's consistency -across multiple NFS clients. When +Do not perform the normal close-to-open consistency. +When a file is closed, all modified data associated with the file is flushed to +the server and not held on the client. +When a file is opened the client sends a request to the server to validate the +client's local caches. +This behavior ensures a file's consistency across multiple NFS clients. +When .Sy nocto is in effect, the client does not perform the flush on close and the request for validation, allowing the possibility of differences among copies of the same file as stored on multiple clients. .Pp This option can be used where it can be guaranteed that accesses to a specified -file system are made from only one client and only that client. Under such a -condition, the effect of +file system are made from only one client and only that client. +Under such a condition, the effect of .Sy nocto can be a slight performance gain. .It Sy port Ns = Ns Ar n -The server IP port number. The default is +The server IP port number. +The default is .Dv NFS_PORT . If the .Sy port @@ -278,20 +293,23 @@ option is specified, and if the resource includes one or more NFS URLs, and if any of the URLs include a port number, then the port number in the option and in the URL must be the same. .It Sy posix -Request POSIX.1 semantics for the file system. Requires a mount Version 2 +Request POSIX.1 semantics for the file system. +Requires a mount Version 2 .Xr mountd 1M -on the server. See +on the server. +See .Xr standards 5 for information regarding POSIX. .It Sy proto Ns = Ns Ar netid Ns | Ns Sy rdma By default, the transport protocol that the NFS mount uses is the first -available RDMA transport supported both by the client and the server. If no RDMA -transport is found, then it attempts to use a TCP transport or, failing that, a -UDP transport, as ordered in the +available RDMA transport supported both by the client and the server. +If no RDMA transport is found, then it attempts to use a TCP transport or, +failing that, a UDP transport, as ordered in the .Pa /etc/netconfig -file. If it does not find a connection oriented transport, it uses the first -available connectionless transport. Use this option to override the default -behavior. +file. +If it does not find a connection oriented transport, it uses the first available +connectionless transport. +Use this option to override the default behavior. .Pp .Sy proto is set to the value of @@ -305,16 +323,17 @@ field entry in the .Pa /etc/netconfig file. .Pp -The UDP protocol is not supported for NFS Version 4. If you specify a UDP -protocol with the +The UDP protocol is not supported for NFS Version 4. +If you specify a UDP protocol with the .Sy proto option, NFS version 4 is not used. .It Sy public The .Sy public option forces the use of the public file handle when connecting to the NFS -server. The resource specified might not have an NFS URL. See the discussion of -URLs and the public option under +server. +The resource specified might not have an NFS URL. +See the discussion of URLs and the public option under .Sx NFS FILE SYSTEMS for a more detailed discussion. .It Sy quota Ns | Ns Sy noquota @@ -341,29 +360,33 @@ assumed that the transport performs retransmissions on behalf of NFS. .It Sy retry Ns = Ns Ar n The number of times to retry the .Nm mount -operation. The default for the +operation. +The default for the .Nm mount command is 10000. .Pp -The default for the automounter is 0, in other words, do not retry. You might -find it useful to increase this value on heavily loaded servers, where +The default for the automounter is 0, in other words, do not retry. +You might find it useful to increase this value on heavily loaded servers, where automounter traffic is dropped, causing unnecessary .Qq server not responding errors. .It Sy rsize Ns = Ns Ar n Set the read buffer size to a maximum of .Ar n -bytes. The default value is 1048576 when using connection-oriented transports -with Version 3 or Version 4 of the NFS protocol, and 32768 when using -connection-less transports. The default can be negotiated down if the server -prefers a smaller transfer size. +bytes. +The default value is 1048576 when using connection-oriented transports with +Version 3 or Version 4 of the NFS protocol, and 32768 when using connection-less +transports. +The default can be negotiated down if the server prefers a smaller transfer +size. .Qq Read -operations may not necessarily use the maximum buffer size. When using Version -2, the default value is 32768 for all transports. +operations may not necessarily use the maximum buffer size. +When using Version 2, the default value is 32768 for all transports. .It Sy sec Ns = Ns Ar mode Set the security .Ar mode -for NFS transactions. If +for NFS transactions. +If .Sy sec Ns = is not specified, then the default action is to use AUTH_SYS over NFS Version 2 mounts, use a user-configured default @@ -375,19 +398,22 @@ The preferred mode for NFS Version 3 mounts is the default mode specified in .Po see .Xr nfssec.conf 4 .Pc -on the client. If there is no default configured in this file or if the server -does not export using the client's default mode, then the client picks the first -mode that it supports in the array of modes returned by the server. These -alternatives are limited to the security flavors listed in +on the client. +If there is no default configured in this file or if the server does not export +using the client's default mode, then the client picks the first mode that it +supports in the array of modes returned by the server. +These alternatives are limited to the security flavors listed in .Pa /etc/nfssec.conf . .Pp NFS Version 4 mounts negotiate a security mode when the server returns an array -of security modes. The client attempts the mount with each security mode, in -order, until one is successful. +of security modes. +The client attempts the mount with each security mode, in order, until one is +successful. .Pp Only one mode can be specified with the .Sy sec Ns = -option. See +option. +See .Xr nfssec 5 for the available .Ar mode @@ -399,30 +425,35 @@ option. .It Sy timeo Ns = Ns Ar n Set the NFS timeout to .Ar n -tenths of a second. The default value is 11 tenths of a second for -connectionless transports, and 600 tenths of a second for connection-oriented -transports. This value is ignored for connectionless transports. Such transports -might implement their own timeouts, which are outside the control of NFS. +tenths of a second. +The default value is 11 tenths of a second for connectionless transports, and +600 tenths of a second for connection-oriented transports. +This value is ignored for connectionless transports. +Such transports might implement their own timeouts, which are outside the +control of NFS. .It Sy vers Ns = Ns Ar "NFS version number" By default, the version of NFS protocol used between the client and the server -is the highest one available on both systems. If the NFS server does not support -the client's default maximum, the next lowest version attempted until a matching -version is found. See +is the highest one available on both systems. +If the NFS server does not support the client's default maximum, the next lowest +version attempted until a matching version is found. +See .Xr nfs 4 for more information on setting default minimum and maximum client versions. .It Sy wsize Ns = Ns Ar n Set the write buffer size to a maximum of .Ar n -bytes. The default value is 1048576 when using connection-oriented transports -with Version 3 or Version 4 of the NFS protocol, and 32768 when using -connection-less transports. The default can be negotiated down if the server -prefers a smaller transfer size. +bytes. +The default value is 1048576 when using connection-oriented transports with +Version 3 or Version 4 of the NFS protocol, and 32768 when using connection-less +transports. +The default can be negotiated down if the server prefers a smaller transfer +size. .Qq Write -operations may not necessarily use the maximum buffer size. When using Version -2, the default value is 32768 for all transports. +operations may not necessarily use the maximum buffer size. +When using Version 2, the default value is 32768 for all transports. .It Sy xattr Ns | Ns Sy noxattr -Allow or disallow the creation and manipulation of extended attributes. The -default is +Allow or disallow the creation and manipulation of extended attributes. +The default is .Sy xattr . See .Xr fsattr 5 @@ -453,9 +484,10 @@ above .Pc . Once the file system is mounted, each NFS request made in the kernel waits .Sy timeo Ns = Ns Ar n -tenths of a second for a response. If no response arrives, the time-out is -multiplied by 2 and the request is retransmitted. When the number of -retransmissions has reached the number specified in the +tenths of a second for a response. +If no response arrives, the time-out is multiplied by 2 and the request is +retransmitted. +When the number of retransmissions has reached the number specified in the .Sy retrans Ns = Ns Ar n option, a file system mounted with the .Sy soft @@ -466,16 +498,19 @@ option prints a warning message and continues to retry the request. File systems that are mounted read-write or that contain executable files should always be mounted with the .Sy hard -option. Applications using +option. +Applications using .Sy soft mounted file systems can incur unexpected I/O errors, file corruption, and -unexpected program core dumps. The +unexpected program core dumps. +The .Sy soft option is not recommended. .Ss Authenticated requests The server can require authenticated NFS requests from the client. .Sy sec Ns = Ns Sy dh -authentication might be required. See +authentication might be required. +See .Xr nfssec 5 . .Ss URLs and the public option If the @@ -500,12 +535,13 @@ daemons to get the port number of the .Nm mount server and the initial file handle of .Ar pathname , -respectively. If the NFS client and server are separated by a firewall that -allows all outbound connections through specific ports, such as +respectively. +If the NFS client and server are separated by a firewall that allows all +outbound connections through specific ports, such as .Dv NFS_PORT , -then this enables NFS operations through the firewall. The public option and the -NFS URL can be specified independently or together. They interact as specified -in the following matrix: +then this enables NFS operations through the firewall. +The public option and the NFS URL can be specified independently or together. +They interact as specified in the following matrix: .Bd -literal Resource Style @@ -525,40 +561,45 @@ default Use MOUNT protocol. Try public file handle .Ed .Pp A Native path is a path name that is interpreted according to conventions used -on the native operating system of the NFS server. A Canonical path is a -path name that is interpreted according to the URL rules. See +on the native operating system of the NFS server. +A Canonical path is a path name that is interpreted according to the URL rules. +See .Rs .%R Uniform Resource Locators (URL) .%T RFC 1738 .Re .Ss Replicated file systems and failover .Ar resource -can list multiple read-only file systems to be used to provide data. These file -systems should contain equivalent directory structures and identical files. It -is also recommended that they be created by a utility such as +can list multiple read-only file systems to be used to provide data. +These file systems should contain equivalent directory structures and identical +files. +It is also recommended that they be created by a utility such as .Xr rdist 1 . The file systems can be specified either with a comma-separated list of .Pa host:/pathname entries and/or NFS URL entries, or with a comma-separated list of hosts, if all -file system names are the same. If multiple file systems are named and the first -server in the list is down, failover uses the next alternate server to access -files. If the read-only option is not chosen, replication is disabled. File -access, for NFS Versions 2 and 3, is blocked on the original if NFS locks are -active for that file. +file system names are the same. +If multiple file systems are named and the first server in the list is down, +failover uses the next alternate server to access files. +If the read-only option is not chosen, replication is disabled. +File access, for NFS Versions 2 and 3, is blocked on the original if NFS locks +are active for that file. .Ss File Attributes -To improve NFS read performance, files and file attributes are cached. File -modification times get updated whenever a write occurs. However, file access -times can be temporarily out-of-date until the cache gets refreshed. +To improve NFS read performance, files and file attributes are cached. +File modification times get updated whenever a write occurs. +However, file access times can be temporarily out-of-date until the cache gets +refreshed. .Pp -The attribute cache retains file attributes on the client. Attributes for a -file are assigned a time to be flushed. If the file is modified before the -flush time, then the flush time is extended by the time since the last -modification +The attribute cache retains file attributes on the client. +Attributes for a file are assigned a time to be flushed. +If the file is modified before the flush time, then the flush time is extended +by the time since the last modification .Po under the assumption that files that changed recently are likely to change soon .Pc . There is a minimum and maximum flush time extension for regular files and for -directories. Setting +directories. +Setting .Sy actimeo Ns = Ns Ar n sets flush time to .Ar n @@ -566,19 +607,21 @@ seconds for both regular files and directories. .Pp Setting .Sy actimeo Ns = Ns Sy 0 -disables attribute caching on the client. This means that every reference to -attributes is satisfied directly from the server though file data is still -cached. While this guarantees that the client always has the latest file -attributes from the server, it has an adverse effect on performance through -additional latency, network load, and server load. +disables attribute caching on the client. +This means that every reference to attributes is satisfied directly from the +server though file data is still cached. +While this guarantees that the client always has the latest file attributes from +the server, it has an adverse effect on performance through additional latency, +network load, and server load. .Pp Setting the .Sy noac option also disables attribute caching, but has the further effect of disabling -client write caching. While this guarantees that data written by an application -is written directly to a server, where it can be viewed immediately by other -clients, it has a significant adverse effect on client write performance. Data -written into memory-mapped file pages +client write caching. +While this guarantees that data written by an application is written directly to +a server, where it can be viewed immediately by other clients, it has a +significant adverse effect on client write performance. +Data written into memory-mapped file pages .Pq Xr mmap 2 are not written directly to this server. .Ss Specifying Values for Attribute Cache Duration Options @@ -595,7 +638,8 @@ options specified following .Sy actimeo on a .Nm mount -command line. For example, consider the following command: +command line. +For example, consider the following command: .Bd -literal -offset indent example# mount -o acdirmax=10,actimeo=1000 server:/path /localpath .Ed @@ -748,7 +792,8 @@ example# mount serv-x:/usr/man,serv-y:/var/man,nfs://serv-z/man /usr/man .%D December 1994 .Re .Sh NOTES -An NFS server should not attempt to mount its own file systems. See +An NFS server should not attempt to mount its own file systems. +See .Xr lofs 7FS . .Pp If the directory on which a file system is to be mounted is a symbolic link, @@ -758,7 +803,8 @@ rather than being mounted on top of the symbolic link itself. SunOS 4.x used the .Sy biod maintenance procedure to perform parallel read-ahead and write-behind on NFS -clients. SunOS 5.x made +clients. +SunOS 5.x made .Sy biod obsolete with multi-threaded processing, which transparently performs parallel read-ahead and write-behind. diff --git a/usr/src/man/man1m/mountd.1m b/usr/src/man/man1m/mountd.1m index d33aefdffb..a38cf00d32 100644 --- a/usr/src/man/man1m/mountd.1m +++ b/usr/src/man/man1m/mountd.1m @@ -31,22 +31,26 @@ .Sh DESCRIPTION .Nm is an RPC server that answers requests for NFS access information and file -system mount requests. It reads the file +system mount requests. +It reads the file .Pa /etc/dfs/sharetab to determine which file systems are available for mounting by which remote -machines. See +machines. +See .Xr sharetab 4 . .Nm nfsd running on the local server will contact .Nm the first time an NFS client tries to access the file system to determine -whether the client should get read-write, read-only, or no access. This access -can be dependent on the security mode used in the remoted procedure call from -the client. See +whether the client should get read-write, read-only, or no access. +This access can be dependent on the security mode used in the remoted procedure +call from the client. +See .Xr share_nfs 1M . .Pp The command also provides information as to what file systems are mounted by -which clients. This information can be printed using the +which clients. +This information can be printed using the .Xr showmount 1M command. .Pp @@ -62,14 +66,15 @@ See for available configuration properties for .Nm . .Ss Options -The options shown below are supported for NFSv2/v3 clients. They are not -supported for NFSv4 clients. +The options shown below are supported for NFSv2/v3 clients. +They are not supported for NFSv4 clients. .Bl -tag -width Ds .It Fl r -Reject mount requests from clients. Clients that have file systems mounted will -not be affected. +Reject mount requests from clients. +Clients that have file systems mounted will not be affected. .It Fl v -Run the command in verbose mode. Each time +Run the command in verbose mode. +Each time .Nm determines what access a client should get, it will log the result to the console, as well as how it got that result. @@ -97,10 +102,12 @@ to function properly, .Nm is automatically started by the .Sy svc:/network/nfs/server -service. See +service. +See .Xr nfs 4 . .Pp Some routines that compare hostnames use case-sensitive string comparisons; -some do not. If an incoming request fails, verify that the case of the hostname -in the file to be parsed matches the case of the hostname called for, and -attempt the request again. +some do not. +If an incoming request fails, verify that the case of the hostname in the file +to be parsed matches the case of the hostname called for, and attempt the +request again. diff --git a/usr/src/man/man1m/ndp.1m b/usr/src/man/man1m/ndp.1m index 6301181f5f..57285b003f 100644 --- a/usr/src/man/man1m/ndp.1m +++ b/usr/src/man/man1m/ndp.1m @@ -52,9 +52,9 @@ tables used by the Neighbor Discovery Protocol .Pp Given just a hostname, .Nm -will display the current entry. Note that when getting, setting or deleting, -if a hostname refers to multiple IPv6 addresses, the operation will apply to -all of them. +will display the current entry. +Note that when getting, setting or deleting, if a hostname refers to multiple +IPv6 addresses, the operation will apply to all of them. .Pp The NDP translation tables can be modified with .Fl d , @@ -65,7 +65,8 @@ These flags can only be used when .Nm is given the .Sy PRIV_SYS_NET_CONFIG -privilege. See +privilege. +See .Xr privileges 5 for further information. .Pp @@ -75,11 +76,13 @@ modified or deleted. .Sh OPTIONS .Bl -tag -width 6m .It Fl a -Display all NDP entries. Entries can be one of several types: +Display all NDP entries. +Entries can be one of several types: .Bl -tag -offset indent -width 7n .It Sy dynamic -This is a normal NDP mapping and will eventually expire. This is the most -common type of mapping for non-local addresses that will be displayed. +This is a normal NDP mapping and will eventually expire. +This is the most common type of mapping for non-local addresses that will be +displayed. .It Sy local The IPv6 address is local to the machine. .It Sy other @@ -129,15 +132,16 @@ Delete NDP mappings for the host called .It Fl f Read in the lines from .Ar filename -and use each one to set a mapping. The syntax of each line is the -same as the arguments to +and use each one to set a mapping. +The syntax of each line is the same as the arguments to .Fl s . Lines beginning with `#' will be ignored. .It Fl i By default, .Nm will use the routing table to determine the appropriate interface to place the -mapping on. This flag allows forcing a specific interface +mapping on. +This flag allows forcing a specific interface .Ar iface . This argument will be ignored when using the .Fl a @@ -148,25 +152,27 @@ flags. Disable the default translation of numeric IP addresses to host names when printing. .It Fl s -Add or update an NDP mapping, and set the desired properties for the entry. The -list of flags should be the full set of flags desired on the entry, i.e., not -listing a flag will remove it if it already exists. The following flags can be -used: +Add or update an NDP mapping, and set the desired properties for the entry. +The list of flags should be the full set of flags desired on the entry, i.e., +not listing a flag will remove it if it already exists. +The following flags can be used: .Bl -tag -offset indent -width Ds .It Cm temp The entry should be temporary and eventually expire like a normal NDP -entry. By default, all entries created with the +entry. +By default, all entries created with the .Nm -command are static, and will not be deleted. To make a static entry temporary, -it should be deleted and recreated with the +command are static, and will not be deleted. +To make a static entry temporary, it should be deleted and recreated with the .Cm temp flag. .It Cm any -The address should be treated like an anycast address. This will prevent the -system from sending Neighbor Advertisements with the Override flag. +The address should be treated like an anycast address. +This will prevent the system from sending Neighbor Advertisements with the +Override flag. .It Cm router -The address should be treated like a router address. This cause the system to -send Neighbor Advertisements with the Router flag. +The address should be treated like a router address. +This cause the system to send Neighbor Advertisements with the Router flag. .El .El .Sh EXAMPLES diff --git a/usr/src/man/man1m/nfsd.1m b/usr/src/man/man1m/nfsd.1m index 70b4379bdd..e188fdd29b 100644 --- a/usr/src/man/man1m/nfsd.1m +++ b/usr/src/man/man1m/nfsd.1m @@ -35,7 +35,8 @@ .Op Ar nservers .Sh DESCRIPTION .Nm -is the daemon that handles client file system requests. Only users with +is the daemon that handles client file system requests. +Only users with .Brq Sy PRIV_SYS_NFS and sufficient privileges to write to .Pa /var/run @@ -51,9 +52,9 @@ option. .Pp By default, .Nm -starts over the TCP and UDP transports for versions 2 and 3. By default, it -starts over the TCP for version 4. You can change this -with the +starts over the TCP and UDP transports for versions 2 and 3. +By default, it starts over the TCP for version 4. +You can change this with the .Fl p option. .Pp @@ -72,28 +73,33 @@ The following options are supported: .Bl -tag -width Ds .It Fl a Start a NFS daemon over all available connectionless and connection-oriented -transports, including UDP and TCP. Equivalent of setting the +transports, including UDP and TCP. +Equivalent of setting the .Sy protocol property to .Sy all . .It Fl c Ar max_conn Set the maximum number of connections allowed to the NFS server over -connection-oriented transports. By default, the number of connections is -unlimited. Equivalent of the +connection-oriented transports. +By default, the number of connections is unlimited. +Equivalent of the .Sy max_connections property. .It Fl l Set connection queue length for the NFS server over a connection-oriented -transport. The default value is 32 entries. Equivalent of the +transport. +The default value is 32 entries. +Equivalent of the .Sy listen_backlog property. .It Fl p Ar protocol -Start a NFS daemon over the specified protocol. Equivalent of the +Start a NFS daemon over the specified protocol. +Equivalent of the .Sy protocol property. .It Fl t Ar device -Start a NFS daemon for the transport specified by the given device. Equivalent -of the +Start a NFS daemon for the transport specified by the given device. +Equivalent of the .Sy device property. .El @@ -102,16 +108,19 @@ The following operands are supported: .Bl -tag -width Ds .It Ar nservers This sets the maximum number of concurrent NFS requests that the server can -handle. This concurrency is achieved by up to +handle. +This concurrency is achieved by up to .Ar nservers threads created as needed in the kernel. .Ar nservers -should be based on the load expected on this server. 16 is the usual number of +should be based on the load expected on this server. +16 is the usual number of .Ar nservers . If .Ar nservers is not specified, the maximum number of concurrent NFS requests will default to -1. Equivalent of the +1. +Equivalent of the .Sy servers property. .El @@ -124,12 +133,14 @@ then clients are required to use privileged ports .Po ports < .Dv IPPORT_RESERVED .Pc -to get NFS services. This variable is equal to zero by default. This variable -has been moved from the +to get NFS services. +This variable is equal to zero by default. +This variable has been moved from the .Qq nfs module to the .Qq nfssrv -module. To set the variable, edit the +module. +To set the variable, edit the .Pa /etc/system file and add this entry: .Bd -literal -offset indent @@ -146,8 +157,8 @@ System configuration information file. .br .Pa /var/nfs/v4_oldstate .Xc -Directories used by the server to manage client state information. These -directories should not be removed. +Directories used by the server to manage client state information. +These directories should not be removed. .El .Sh EXIT STATUS .Bl -tag -width Ds @@ -171,7 +182,8 @@ Daemon failed to start. .Sh NOTES Manually starting and restarting .Nm -is not recommended. If it is necessary to do so, use +is not recommended. +If it is necessary to do so, use .Nm svcadm to enable or disable the nfs service .Pq svc:/network/nfs/server . @@ -205,7 +217,8 @@ If .Nm is killed with .Sy SIGTERM , -it will not be restarted by the service management facility. Instead, +it will not be restarted by the service management facility. +Instead, .Nm can be restarted by other signals, such as .Sy SIGINT . diff --git a/usr/src/man/man1m/nfsmapid.1m b/usr/src/man/man1m/nfsmapid.1m index 7b7eee6cb4..1eaed5f0fc 100644 --- a/usr/src/man/man1m/nfsmapid.1m +++ b/usr/src/man/man1m/nfsmapid.1m @@ -47,8 +47,8 @@ file to direct how it performs the mappings. .Pp The .Nm -daemon has no external, customer-accessible interfaces. You can, however, -administratively configure +daemon has no external, customer-accessible interfaces. +You can, however, administratively configure .Nm in one of the following ways: .Bl -bullet @@ -107,12 +107,14 @@ property is set to .Sy false . .Pp .Nm -caches a user's UID and GID. If a user subsequently changes a UID or GID, using -one of the utilities listed below, the +caches a user's UID and GID. +If a user subsequently changes a UID or GID, using one of the utilities listed +below, the .Nm -cache becomes stale. At this point, any NFS operation that gets or set -attributes will result in the exchange of this stale information. To resolve -this situation, restart +cache becomes stale. +At this point, any NFS operation that gets or set attributes will result in the +exchange of this stale information. +To resolve this situation, restart .Nm , as follows: .Bd -literal -offset indent diff --git a/usr/src/man/man1m/share_nfs.1m b/usr/src/man/man1m/share_nfs.1m index 9daaed00f9..8a2770cb79 100644 --- a/usr/src/man/man1m/share_nfs.1m +++ b/usr/src/man/man1m/share_nfs.1m @@ -38,8 +38,8 @@ .Sh DESCRIPTION The .Nm share -utility makes local file systems available for mounting by remote systems. It -starts the +utility makes local file systems available for mounting by remote systems. +It starts the .Xr nfsd 1M and .Xr mountd 1M @@ -60,7 +60,8 @@ Share NFS file system type. Specify .Ar specific_options in a comma-separated list of keywords and attribute-value-assertions for -interpretation by the file-system-type-specific command. If +interpretation by the file-system-type-specific command. +If .Ar specific_options is not specified, then by default sharing is read-write to all clients. .Ar specific_options @@ -68,18 +69,22 @@ can be any combination of the following: .Bl -tag -width "indented" .It Sy aclok Allows the NFS server to do access control for NFS Version 2 clients (running -SunOS 2.4 or earlier). When +SunOS 2.4 or earlier). +When .Sy aclok -is set on the server, maximal access is given to all clients. For example, with +is set on the server, maximal access is given to all clients. +For example, with .Sy aclok -set, if anyone has read permissions, then everyone does. If +set, if anyone has read permissions, then everyone does. +If .Sy aclok is not set, minimal access is given to all clients. .It Sy anon Ns = Ns Ar uid Set .Ar uid -to be the effective user ID of unknown users. By default, unknown users are -given the effective user ID UID_NOBODY. If uid is set to -1, access is denied. +to be the effective user ID of unknown users. +By default, unknown users are given the effective user ID UID_NOBODY. +If uid is set to -1, access is denied. .It Ar charset Ns = Ns Ar access_list Where .Ar charset @@ -106,13 +111,17 @@ For clients where the gid in the incoming request is and the client matches the .Ar access_list Ns , change the group ID to -.Ar srv Ns . If +.Ar srv Ns . +If .Ar clnt -is asterisk (*), all groups are mapped by this rule. If +is asterisk (*), all groups are mapped by this rule. +If .Ar clnt -is omitted, all unknown groups are mapped by this rule. If +is omitted, all unknown groups are mapped by this rule. +If .Ar srv -is set to -1, access is denied. If +is set to -1, access is denied. +If .Ar srv is omitted, the gid is mapped to UID_NOBODY. .Pp @@ -121,13 +130,15 @@ The particular are separated in the .Sy gidmap Ns = option by tilde (~) and are evaluated in the specified order until a match is -found. Both +found. +Both .Sy root Ns = and .Sy root_mapping Ns = options (if specified) are evaluated before the .Sy gidmap Ns = -option. The +option. +The .Sy gidmap Ns = option is skipped in the case where the client matches the .Sy root Ns = @@ -146,9 +157,11 @@ Load rather than a listing of the directory containing this file when the directory is referenced by an NFS URL. .It Sy log Ns Oo = Ns Ar tag Oc -Enables NFS server logging for the specified file system. The optional +Enables NFS server logging for the specified file system. +The optional .Ar tag -determines the location of the related log files. The +determines the location of the related log files. +The .Ar tag is defined in .Pa /etc/nfs/nfslog.conf . @@ -156,7 +169,8 @@ If no .Ar tag is specified, the default values associated with the global tag in .Pa /etc/nfs/nfslog.conf -are used. Support of NFS server logging is only available for NFS Version 2 and +are used. +Support of NFS server logging is only available for NFS Version 2 and Version 3 requests. .It Sy noaclfab By default, the NFS server will fabricate POSIX-draft style ACLs in response @@ -166,16 +180,16 @@ Specifying .Sy noaclfab disables this behavior. .It Sy none Ns = Ns Ar access_list -Access is not allowed to any client that matches the access list. The exception -is when the access list is an asterisk (*), in which case +Access is not allowed to any client that matches the access list. +The exception is when the access list is an asterisk (*), in which case .Sy ro or .Sy rw can override .Sy none . .It Sy nosub -Prevents clients from mounting subdirectories of shared directories. For -example, if +Prevents clients from mounting subdirectories of shared directories. +For example, if .Pa /export is shared with the .Sy nosub @@ -186,21 +200,24 @@ then a NFS client cannot do: mount -F nfs fooey:/export/home/mnt .Ed .Pp -NFS Version 4 does not use the MOUNT protocol. The +NFS Version 4 does not use the MOUNT protocol. +The .Sy nosub option only applies to NFS Version 2 and Version 3 requests. .It Sy nosuid By default, clients are allowed to create files on the shared file system with -the setuid or setgid mode enabled. Specifying +the setuid or setgid mode enabled. +Specifying .Sy nosuid causes the server file system to silently ignore any attempt to enable the setuid or setgid mode bits. .It Sy public Moves the location of the public file handle from root .Pa ( / ) -to the exported directory for WebNFS-enabled browsers and clients. This option -does not enable WebNFS service; WebNFS is always on. Only one file system per -server may use this option. Any other option, including the +to the exported directory for WebNFS-enabled browsers and clients. +This option does not enable WebNFS service; WebNFS is always on. +Only one file system per server may use this option. +Any other option, including the .Sy ro Ns = Ns Ar list and .Sy rw Ns = Ns Ar list @@ -214,19 +231,23 @@ Sharing is read-only to the clients listed in .Ar access_list ; overrides the .Sy rw -suboption for the clients specified. See +suboption for the clients specified. +See .Sx access_list below. .It Sy root Ns = Ns Ar access_list Only root users from the hosts specified in .Ar access_list -have root access. See +have root access. +See .Sx access_list -below. By default, no host has root access, so root users are mapped to an -anonymous user ID (see the +below. +By default, no host has root access, so root users are mapped to an anonymous +user ID (see the .Sy anon Ns = Ns Ar uid -option described above). Netgroups can be used if the file system shared is -using UNIX authentication (AUTH_SYS). +option described above). +Netgroups can be used if the file system shared is using UNIX authentication +(AUTH_SYS). .It Sy root_mapping Ns = Ns Ar uid For a client that is allowed root access, map the root UID to the specified user id. @@ -237,20 +258,25 @@ Sharing is read-write to the clients listed in .Ar access_list ; overrides the .Sy ro -suboption for the clients specified. See +suboption for the clients specified. +See .Sx access_list below. .It Sy sec Ns = Ns Ar mode Ns Oo : Ns Ar mode Oc Ns ... -Sharing uses one or more of the specified security modes. The +Sharing uses one or more of the specified security modes. +The .Ar mode in the .Sy sec Ns = Ns Ar mode -option must be a mode name supported on the client. If the +option must be a mode name supported on the client. +If the .Sy sec Ns = -option is not specified, the default security mode used is AUTH_SYS. Multiple +option is not specified, the default security mode used is AUTH_SYS. +Multiple .Sy sec Ns = options can be specified on the command line, although each mode can appear -only once. The security modes are defined in +only once. +The security modes are defined in .Xr nfssec 5 . .Pp Each @@ -282,7 +308,8 @@ If the option .Sy sec Ns = Ns Sy none is specified when the client uses AUTH_NONE, or if the client uses a security mode that is not one that the file system is shared with, then the credential -of each NFS request is treated as unauthenticated. See the +of each NFS request is treated as unauthenticated. +See the .Sy anon Ns = Ns Ar uid option for a description of how unauthenticated requests are handled. .It Sy secure @@ -304,13 +331,17 @@ For clients where the uid in the incoming request is and the client matches the .Ar access_list Ns , change the user ID to -.Ar srv Ns . If +.Ar srv Ns . +If .Ar clnt -is asterisk (*), all users are mapped by this rule. If +is asterisk (*), all users are mapped by this rule. +If .Ar clnt -is omitted, all unknown users are mapped by this rule. If +is omitted, all unknown users are mapped by this rule. +If .Ar srv -is set to -1, access is denied. If +is set to -1, access is denied. +If .Ar srv is omitted, the uid is mapped to UID_NOBODY. .Pp @@ -319,13 +350,15 @@ The particular are separated in the .Sy uidmap Ns = option by tilde (~) and are evaluated in the specified order until a match is -found. Both +found. +Both .Sy root Ns = and .Sy root_mapping Ns = options (if specified) are evaluated before the .Sy uidmap Ns = -option. The +option. +The .Sy uidmap Ns = option is skipped in the case where the client matches the .Sy root Ns = @@ -342,9 +375,10 @@ This option is supported only for AUTH_SYS. When sharing with .Sy sec Ns = Ns Sy dh , set the maximum life time (in seconds) of the RPC request's credential (in the -authentication header) that the NFS server allows. If a credential arrives with -a life time larger than what is allowed, the NFS server rejects the request. The -default value is 30000 seconds (8.3 hours). +authentication header) that the NFS server allows. +If a credential arrives with a life time larger than what is allowed, the NFS +server rejects the request. +The default value is 30000 seconds (8.3 hours). .El .El .Ss access_list @@ -354,13 +388,13 @@ argument is a colon-separated list whose components may be any number of the following: .Bl -tag -width "indented" .It Sy hostname -The name of a host. With a server configured for DNS or LDAP naming in the -nsswitch +The name of a host. +With a server configured for DNS or LDAP naming in the nsswitch .Sy hosts entry, any hostname must be represented as a fully qualified DNS or LDAP name. .It Sy netgroup -A netgroup contains a number of hostnames. With a server configured for DNS or -LDAP naming in the nsswitch +A netgroup contains a number of hostnames. +With a server configured for DNS or LDAP naming in the nsswitch .Sy hosts entry, any hostname in a netgroup must be represented as a fully qualified DNS or LDAP name. @@ -376,10 +410,11 @@ or .Sy ldap ahead of .Sy nis -since only DNS and LDAP return the full domain name of the host. Other name -services like NIS cannot be used to resolve hostnames on the server +since only DNS and LDAP return the full domain name of the host. +Other name services like NIS cannot be used to resolve hostnames on the server because when mapping an IP address to a hostname they do not return domain -information. For example, +information. +For example, .Bd -literal -offset indent NIS 172.16.45.9 --> "myhost" .Ed @@ -390,12 +425,14 @@ DNS or LDAP 172.16.45.9 --> "myhost.mydomain.mycompany.com" .Ed .Pp The domain name suffix is distinguished from hostnames and netgroups by a -prefixed dot. For example, +prefixed dot. +For example, .Bd -literal -offset indent rw=.mydomain.mycompany.com .Ed .Pp -A single dot can be used to match a hostname with no suffix. For example, +A single dot can be used to match a hostname with no suffix. +For example, .Bd -literal -offset indent rw=. .Ed @@ -407,8 +444,9 @@ but not This feature can be used to match hosts resolved through NIS rather than DNS and LDAP. .It Sy network -The network or subnet component is preceded by an at-sign (@). It can be either -a name or a dotted address. If a name, it is converted to a dotted address by +The network or subnet component is preceded by an at-sign (@). +It can be either a name or a dotted address. +If a name, it is converted to a dotted address by .Xr getnetbyname 3SOCKET . For example, .Bd -literal -offset indent @@ -422,9 +460,10 @@ would be equivalent to: .Pp The network prefix assumes an octet-aligned netmask determined from the zeroth octet in the low-order part of the address up to and including the high-order -octet, if you want to specify a single IP address (see below). In the case -where network prefixes are not byte-aligned, the syntax allows a mask length to -be specified explicitly following a slash (/) delimiter. For example, +octet, if you want to specify a single IP address (see below). +In the case where network prefixes are not byte-aligned, the syntax allows a +mask length to be specified explicitly following a slash (/) delimiter. +For example, .Bd -literal -offset indent =@theothernet/17 or =@172.16.132/22 .Ed @@ -433,7 +472,8 @@ where the mask is the number of leftmost contiguous significant bits in the corresponding IP address. .Pp When specifying individual IP addresses, use the same @ notation described -above, without a netmask specification. For example: +above, without a netmask specification. +For example: .Bd -literal -offset indent =@172.16.132.14 .Ed @@ -447,7 +487,8 @@ root=@172.16.132.20:@172.16.134.20 A prefixed minus sign (-) denies access to that component of .Ar access_list . The list is searched sequentially until a match is found that either grants or -denies access, or until the end of the list is reached. For example, if host +denies access, or until the end of the list is reached. +For example, if host .Qq terra is in the .Qq engineering @@ -494,16 +535,17 @@ share -o log /export .Ed .Pp The default global logging parameters are used since no tag identifier is -specified. The location of the log file, as well as the necessary logging work +specified. +The location of the log file, as well as the necessary logging work files, is specified by the global entry in .Pa /etc/nfs/nfslog.conf . The .Xr nfslogd 1M daemon runs only if at least one file system entry in .Pa /etc/dfs/dfstab -is shared with logging enabled upon starting or rebooting the system. Simply -sharing a file system with logging enabled from the command line does not start -the +is shared with logging enabled upon starting or rebooting the system. +Simply sharing a file system with logging enabled from the command line does not +start the .Xr nfslogd 1M . .Ss Example 2 Remap A User Coming From The Particular NFS Client The following example remaps the user with uid @@ -541,7 +583,8 @@ and .Sy root Ns = options must come after the first .Sy sec Ns = -option. If the +option. +If the .Sy sec Ns = option is not presented, then .Sy sec Ns = Ns Sy sys @@ -552,7 +595,8 @@ If one or more explicit options are presented, .Sy sys must appear in one of the options mode lists for accessing using the AUTH_SYS -security mode to be allowed. For example: +security mode to be allowed. +For example: .Bd -literal -offset indent share -F nfs /var share -F nfs -o sec=sys /var @@ -581,7 +625,8 @@ the .Sy ro Ns = and .Sy rw Ns = -options are used to control access to weaker security modes. In this example, +options are used to control access to weaker security modes. +In this example, .Bd -literal -offset indent share -F nfs -o sec=dh,rw,sec=sys,rw=hosta /var .Ed @@ -595,9 +640,10 @@ share -F nfs -o sec=dh,rw,sec=sys,ro /var .Ed .Pp is safer, because any client (intruder or legitimate) that avoids AUTH_DES only -gets read-only access. In general, multiple security modes per share command -should only be used in situations where the clients using more secure modes get -stronger access than clients using less secure modes. +gets read-only access. +In general, multiple security modes per share command should only be used in +situations where the clients using more secure modes get stronger access than +clients using less secure modes. .Pp If .Sy rw Ns = @@ -606,7 +652,8 @@ and options are specified in the same .Sy sec Ns = clause, and a client is in both lists, the order of the two options determines -the access the client gets. If client +the access the client gets. +If client .Qq hosta is in two netgroups, .Qq group1 @@ -631,8 +678,10 @@ clause, both the and .Sy rw Ns = options are specified, for compatibility, the order of the options rule is not -enforced. All hosts would get read-only access, with the exception to those in -the read-write list. Likewise, if the +enforced. +All hosts would get read-only access, with the exception to those in the +read-write list. +Likewise, if the .Sy ro Ns = and .Sy rw @@ -663,10 +712,13 @@ option and the .Sy rw Ns = , and .Sy ro Ns = -options. Putting a host in the root list does not override the semantics of the -other options. The access the host gets is the same as when the +options. +Putting a host in the root list does not override the semantics of the other +options. +The access the host gets is the same as when the .Sy root Ns = -option is absent. For example, the following share command denies access to +option is absent. +For example, the following share command denies access to .Qq hostb : .Bd -literal -offset indent share -F nfs -o ro=hosta,root=hostb /var @@ -685,8 +737,8 @@ share -F nfs -o ro=hosta,rw=hostb,root=hostb /var .Ed .Pp If the file system being shared is a symbolic link to a valid pathname, the -canonical path (the path which the symbolic link follows) is shared. For -example, if +canonical path (the path which the symbolic link follows) is shared. +For example, if .Pa /export/foo is a symbolic link to .Pa /export/bar , @@ -723,7 +775,8 @@ For example, .Pa /export/foo might be a symbolic link that refers to .Pa /export/bar -which has been specifically shared. When the client mounts +which has been specifically shared. +When the client mounts .Pa /export/foo the mountd processing follows the symbolic link and responds with the .Pa /export/bar . diff --git a/usr/src/man/man1m/sharectl.1m b/usr/src/man/man1m/sharectl.1m index e754a602b4..74d260d4e7 100644 --- a/usr/src/man/man1m/sharectl.1m +++ b/usr/src/man/man1m/sharectl.1m @@ -45,9 +45,10 @@ .Sh DESCRIPTION The .Nm -command operates on file sharing services. The command sets the client and -server operational properties, takes and restores configuration snapshots, and -gets status of the protocol service. Currently supported services are +command operates on file sharing services. +The command sets the client and server operational properties, takes and +restores configuration snapshots, and gets status of the protocol service. +Currently supported services are .Xr autofs 4 , .Xr nfs 4 , .Xr smb 4 @@ -64,9 +65,11 @@ authorizations, see appropriate sharing protocol man page. The following options are supported where applicable: .Bl -tag -width Ds .It Fl h -Displays usage message. Supported for all subcommands. +Displays usage message. +Supported for all subcommands. .It Fl p Ar property Ns Op = Ns Ar value -Specifies a property. See +Specifies a property. +See .Sx Subcommands , below. .El @@ -79,8 +82,8 @@ supports the subcommands described below: .Cm delsect .Ar section protocol .Xc -Delete configuration section for the specified protocol. Currently only protocol -that has configuration sections is +Delete configuration section for the specified protocol. +Currently only protocol that has configuration sections is .Nm smbfs .Po see .Xr nsmbrc 4 @@ -93,12 +96,14 @@ and .Oo Fl p Ar property Oc Ns ... .Ar protocol .Xc -Get the property values for the specified protocol. If no +Get the property values for the specified protocol. +If no .Fl p -option is provided, get all the properties for the specified protocol. For NFS, -properties correspond to entries in the +option is provided, get all the properties for the specified protocol. +For NFS, properties correspond to entries in the .Pa /etc/default/nfs -file. See +file. +See .Xr nfs 4 . .It Xo .Nm @@ -192,7 +197,8 @@ The following command shows how an authorized user can use the .Nm sharectl Cm get command to view the global settings for .Nm smbfs -in the SMF. The values shown are those set by the previous example. +in the SMF. +The values shown are those set by the previous example. .Bd -literal # sharectl get smbfs [default] diff --git a/usr/src/man/man1m/stmfadm.1m b/usr/src/man/man1m/stmfadm.1m index 8493c20d04..d99c31c3b3 100644 --- a/usr/src/man/man1m/stmfadm.1m +++ b/usr/src/man/man1m/stmfadm.1m @@ -121,7 +121,8 @@ The .Nm command configures logical units within the SCSI Target Mode Framework .Pq STMF -framework. The framework and this man page use the following terminology: +framework. +The framework and this man page use the following terminology: .Bl -tag -width Ds .It Sy initiator A device responsible for issuing SCSI I/O commands to a SCSI target and logical @@ -147,15 +148,16 @@ The set of logical units that a particular SCSI initiator can see is determined by the combined set of views. .Pp Each logical unit has a set of view entries, and each view entry specifies a -target group, host group, and a LUN. An initiator from that host group, when -connecting through that target group, is able to identify and connect to that -logical unit using the specified LUN. You can use views to restrict the set of -logical units that a specific initiator can see, and assign the set of LUNs -that will be used. +target group, host group, and a LUN. +An initiator from that host group, when connecting through that target group, is +able to identify and connect to that logical unit using the specified LUN. +You can use views to restrict the set of logical units that a specific initiator +can see, and assign the set of LUNs that will be used. .It Sy view A view defines the association of a host group, a target group, and a logical -unit number with a specified logical unit. Any view entry added to a logical -unit must not be in conflict with existing view entries for that logical unit. +unit number with a specified logical unit. +Any view entry added to a logical unit must not be in conflict with existing +view entries for that logical unit. A view entry is considered to be in conflict when an attempt is made to duplicate the association of any given host, target and logical unit number. .El @@ -165,31 +167,41 @@ The following logical unit properties can be set only when creating LU using subcommand: .Bl -tag -width Ds .It Sy blk Ns = Ns Ar num -Specifies the block size for the device. The default is 512. +Specifies the block size for the device. +The default is 512. .It Sy guid Ns = Ns Ar string 32 hexadecimal ASCII characters representing a valid NAA Registered Extended -Identifier. The default is set by the STMF to a generated value. +Identifier. +The default is set by the STMF to a generated value. .It Sy meta Ns = Ns Ar path -Metadata file name. When specified, will be used to hold the SCSI metadata for -the logical unit. There is no default. +Metadata file name. +When specified, will be used to hold the SCSI metadata for the logical unit. +There is no default. .It Sy oui Ns = Ns Ar string -Organizational Unique Identifier. Six hexadecimal ASCII characters representing -the IEEE OUI company ID assignment. This will be used to generate the device -identifier +Organizational Unique Identifier. +Six hexadecimal ASCII characters representing the IEEE OUI company ID +assignment. +This will be used to generate the device identifier .Pq GUID . The default is .Sy 00144F . .It Sy pid Ns = Ns Ar string -16 bytes ASCII string defining Product ID per SCSI SPC-3. This value will be -reflected in the Standard INQUIRY data returned for the device. The default is +16 bytes ASCII string defining Product ID per SCSI SPC-3. +This value will be reflected in the Standard INQUIRY data returned for the +device. +The default is .Sy COMSTAR . .It Sy serial Ns = Ns Ar string -Serial Number. Specifies the SCSI Vital Product Data Serial Number +Serial Number. +Specifies the SCSI Vital Product Data Serial Number .Pq page 80h . -It is a character value up to 252 bytes in length. There is no default value. +It is a character value up to 252 bytes in length. +There is no default value. .It Sy vid Ns = Ns Ar string -8 bytes ASCII string defining Vendor ID per SCSI SPC-3. This value will be -reflected in the Standard INQUIRY data returned for the device. The default is +8 bytes ASCII string defining Vendor ID per SCSI SPC-3. +This value will be reflected in the Standard INQUIRY data returned for the +device. +The default is .Sy SUN . .El .Pp @@ -200,22 +212,24 @@ subcommand or modified using subcommand: .Bl -tag -width Ds .It Sy alias Ns = Ns Ar string -Up to 255 characters, representing a user-defined name for the device. The -default is the name of the backing store. +Up to 255 characters, representing a user-defined name for the device. +The default is the name of the backing store. .It Sy mgmt-url Ns = Ns Ar string -Up to 1024 characters representing a Management Network Address URL. More than -one URL can be passed as a single parameter by using space-delimited URLs -enclosed inside a single pair of quotation marks +Up to 1024 characters representing a Management Network Address URL. +More than one URL can be passed as a single parameter by using space-delimited +URLs enclosed inside a single pair of quotation marks .Pq Sy \(dq . .It Sy wcd Ns = Ns Sy true Ns | Ns Sy false -Write-back cache disable. Determines write-back cache disable behavior. The -default is the write-back cache setting of the backing store device specified by -the +Write-back cache disable. +Determines write-back cache disable behavior. +The default is the write-back cache setting of the backing store device +specified by the .Ar lu-file argument. .It Sy wp Ns = Ns Sy true Ns | Ns Sy false -Write-protect bit. Determines whether the device reports as write-protected. The -default is +Write-protect bit. +Determines whether the device reports as write-protected. +The default is .Sy false . .El .Ss Subcommands @@ -271,14 +285,16 @@ where .Ar lu-name is the STMF name for the logical unit as displayed by the .Cm list-lu -subcommand. The +subcommand. +The .Cm add-view subcommand provides the user with a mechanism to implement access control for a logical unit and also provides a means of assigning a logical unit number to a -logical unit for a given set of initiators and targets. A logical unit will not -be available to any initiators until at least one view is applied. Each view -entry gets assigned an entry name, which can be used to reference the entry in -the +logical unit for a given set of initiators and targets. +A logical unit will not be available to any initiators until at least one view +is applied. +Each view entry gets assigned an entry name, which can be used to reference the +entry in the .Cm list-view and .Cm remove-view @@ -288,19 +304,22 @@ subcommands. .Ar host-group is the name of an host group previously created using .Cm create-hg -subcommand. If this option is not specified, the logical unit will be available -to all initiators that log in to the STMF framework. +subcommand. +If this option is not specified, the logical unit will be available to all +initiators that log in to the STMF framework. .It Fl n Ns , Ns Fl -lun Ar lu-number .Ar lu-number is an integer in the range 0-16383 to be assigned to the logical unit for this -view entry. If this option is not specified, a logical unit number will be -assigned by the STMF framework. +view entry. +If this option is not specified, a logical unit number will be assigned by the +STMF framework. .It Fl t Ns , Ns Fl -target-group Ar target-group .Ar target-group is the name of a target group previously created using .Cm create-tg -subcommand. If this option is not specified, the logical unit will be available -through all targets. +subcommand. +If this option is not specified, the logical unit will be available through all +targets. .El .It Xo .Nm @@ -310,8 +329,8 @@ through all targets. Create a host group with the name .Ar group-name . .Ar group-name -is a string of Unicode characters with a maximum length of 255. The group name -must be unique within the STMF system. +is a string of Unicode characters with a maximum length of 255. +The group name must be unique within the STMF system. .It Xo .Nm .Cm create-lu @@ -321,29 +340,34 @@ must be unique within the STMF system. .Xc Create a logical unit that can be registered with STMF. .Ar lu-file -is the file to be used as the backing store for the logical unit. If the +is the file to be used as the backing store for the logical unit. +If the .Fl s option is not specified, the size of the specified .Ar lu-file will be used as the size of the logical unit. .Pp Logical units registered with the STMF require space for the metadata to be -stored. When a +stored. +When a .Sy zvol is specified as the backing store device, the default will be to use a special property of the .Sy zvol -to contain the metadata. For all other devices, the default behavior will be to -use the first 64k of the device. An alternative approach would be to use the +to contain the metadata. +For all other devices, the default behavior will be to use the first 64k of the +device. +An alternative approach would be to use the .Sy meta property in a .Cm create-lu -subcommand to specify an alternate file to contain the metadata. It is advisable -to use a file that can provide sufficient storage of the logical unit metadata, -preferably 64k. +subcommand to specify an alternate file to contain the metadata. +It is advisable to use a file that can provide sufficient storage of the logical +unit metadata, preferably 64k. .Bl -tag -width Ds .It Fl p Ns , Ns Fl -lu-prop Ar property Ns = Ns Ar value -Set specified logical unit property. Check +Set specified logical unit property. +Check .Sx Logical Unit Properties for the list of available properties. .It Fl s Ns , Ns Fl -size Ar size @@ -362,8 +386,8 @@ respectively. Create a target group with the name .Ar group-name . .Ar group-name -is a string of Unicode characters with a maximum length of 255. The group name -must be unique within the STMF system. +is a string of Unicode characters with a maximum length of 255. +The group name must be unique within the STMF system. .It Xo .Nm .Cm delete-hg @@ -379,7 +403,8 @@ Delete the host group identified by .Xc Delete an existing logical unit that was created using .Cm create-lu -subcommand. This effectively unloads the logical unit from the STMF framework. +subcommand. +This effectively unloads the logical unit from the STMF framework. Any existing data on the logical unit remains intact. .Bl -tag -width Ds .It Fl k Ns , Ns Fl -keep-views @@ -401,12 +426,13 @@ Import and load a logical unit into the STMF that was previously created using .Cm create-lu subcommand and was then deleted from the STMF using .Cm delete-lu -subcommand. On success, the logical unit is again made available to the STMF. +subcommand. +On success, the logical unit is again made available to the STMF. .Ar lu-file is the filename used in the .Cm create-lu -subcommand. If this logical unit is using a separate metadata file, the filename -in the +subcommand. +If this logical unit is using a separate metadata file, the filename in the .Sy meta property value that was used in the .Cm create-lu @@ -501,7 +527,8 @@ Specify logical unit. .Xc Modify attributes of a logical unit created using the .Cm create-lu -subcommand. If +subcommand. +If .Fl f is not specified, .Ar lu-arg @@ -511,10 +538,12 @@ is interpreted as .It Fl f Ns , Ns Fl -file If specified, .Ar lu-arg -is interpreted as file name. This provides the ability to modify a logical unit -that is not currently imported into the STMF. +is interpreted as file name. +This provides the ability to modify a logical unit that is not currently +imported into the STMF. .It Fl p Ns , Ns Fl -lu-prop Ar property -Modify specified logical unit property. See +Modify specified logical unit property. +See .Sx Logical Unit Properties for the list of available properties. .It Fl s Ns , Ns Fl -size Ar size diff --git a/usr/src/man/man1m/zfs.1m b/usr/src/man/man1m/zfs.1m index 2f24b89339..6b872c5ac7 100644 --- a/usr/src/man/man1m/zfs.1m +++ b/usr/src/man/man1m/zfs.1m @@ -270,7 +270,8 @@ The .Nm command configures ZFS datasets within a ZFS storage pool, as described in .Xr zpool 1M . -A dataset is identified by a unique path within the ZFS namespace. For example: +A dataset is identified by a unique path within the ZFS namespace. +For example: .Bd -literal pool/{filesystem,volume,snapshot} .Ed @@ -285,28 +286,30 @@ A dataset can be one of the following: A ZFS dataset of type .Sy filesystem can be mounted within the standard system namespace and behaves like other file -systems. While ZFS file systems are designed to be POSIX compliant, known issues -exist that prevent compliance in some cases. Applications that depend on -standards conformance might fail due to non-standard behavior when checking file -system free space. +systems. +While ZFS file systems are designed to be POSIX compliant, known issues exist +that prevent compliance in some cases. +Applications that depend on standards conformance might fail due to non-standard +behavior when checking file system free space. .It Sy volume -A logical volume exported as a raw or block device. This type of dataset should -only be used under special circumstances. File systems are typically used in -most environments. +A logical volume exported as a raw or block device. +This type of dataset should only be used under special circumstances. +File systems are typically used in most environments. .It Sy snapshot -A read-only version of a file system or volume at a given point in time. It is -specified as +A read-only version of a file system or volume at a given point in time. +It is specified as .Ar filesystem Ns @ Ns Ar name or .Ar volume Ns @ Ns Ar name . .El .Ss ZFS File System Hierarchy A ZFS storage pool is a logical collection of devices that provide space for -datasets. A storage pool is also the root of the ZFS file system hierarchy. +datasets. +A storage pool is also the root of the ZFS file system hierarchy. .Pp The root of the pool can be accessed as a file system, such as mounting and -unmounting, taking snapshots, and setting properties. The physical storage -characteristics, however, are managed by the +unmounting, taking snapshots, and setting properties. +The physical storage characteristics, however, are managed by the .Xr zpool 1M command. .Pp @@ -314,31 +317,38 @@ See .Xr zpool 1M for more information on creating and administering pools. .Ss Snapshots -A snapshot is a read-only copy of a file system or volume. Snapshots can be -created extremely quickly, and initially consume no additional space within the -pool. As data within the active dataset changes, the snapshot consumes more -data than would otherwise be shared with the active dataset. +A snapshot is a read-only copy of a file system or volume. +Snapshots can be created extremely quickly, and initially consume no additional +space within the pool. +As data within the active dataset changes, the snapshot consumes more data than +would otherwise be shared with the active dataset. .Pp -Snapshots can have arbitrary names. Snapshots of volumes can be cloned or -rolled back, but cannot be accessed independently. +Snapshots can have arbitrary names. +Snapshots of volumes can be cloned or rolled back, but cannot be accessed +independently. .Pp File system snapshots can be accessed under the .Pa .zfs/snapshot -directory in the root of the file system. Snapshots are automatically mounted on -demand and may be unmounted at regular intervals. The visibility of the +directory in the root of the file system. +Snapshots are automatically mounted on demand and may be unmounted at regular +intervals. +The visibility of the .Pa .zfs directory can be controlled by the snapdir property. .Ss Clones A clone is a writable volume or file system whose initial contents are the same -as another dataset. As with snapshots, creating a clone is nearly instantaneous, -and initially consumes no additional space. -.Pp -Clones can only be created from a snapshot. When a snapshot is cloned, it -creates an implicit dependency between the parent and child. Even though the -clone is created somewhere else in the dataset hierarchy, the original snapshot -cannot be destroyed as long as a clone exists. The +as another dataset. +As with snapshots, creating a clone is nearly instantaneous, and initially +consumes no additional space. +.Pp +Clones can only be created from a snapshot. +When a snapshot is cloned, it creates an implicit dependency between the parent +and child. +Even though the clone is created somewhere else in the dataset hierarchy, the +original snapshot cannot be destroyed as long as a clone exists. +The .Sy origin property exposes this dependency, and the .Cm destroy @@ -346,28 +356,32 @@ command lists any such dependencies, if they exist. .Pp The clone parent-child dependency relationship can be reversed by using the .Cm promote -subcommand. This causes the +subcommand. +This causes the .Qq origin file system to become a clone of the specified file system, which makes it possible to destroy the file system that the clone was created from. .Ss "Mount Points" Creating a ZFS file system is a simple operation, so the number of file systems -per system is likely to be numerous. To cope with this, ZFS automatically -manages mounting and unmounting file systems without the need to edit the +per system is likely to be numerous. +To cope with this, ZFS automatically manages mounting and unmounting file +systems without the need to edit the .Pa /etc/vfstab -file. All automatically managed file systems are mounted by ZFS at boot time. +file. +All automatically managed file systems are mounted by ZFS at boot time. .Pp By default, file systems are mounted under .Pa /path , where .Ar path -is the name of the file system in the ZFS namespace. Directories are created and -destroyed as needed. +is the name of the file system in the ZFS namespace. +Directories are created and destroyed as needed. .Pp A file system can also have a mount point set in the .Sy mountpoint -property. This directory is created as needed, and ZFS automatically mounts the -file system when the +property. +This directory is created as needed, and ZFS automatically mounts the file +system when the .Nm zfs Cm mount Fl a command is invoked .Po without editing @@ -403,20 +417,25 @@ responsible for mounting and unmounting the file system. .Ss "Zones" A ZFS file system can be added to a non-global zone by using the .Nm zonecfg Cm add Sy fs -subcommand. A ZFS file system that is added to a non-global zone must have its +subcommand. +A ZFS file system that is added to a non-global zone must have its .Sy mountpoint property set to .Sy legacy . .Pp The physical properties of an added file system are controlled by the global -administrator. However, the zone administrator can create, modify, or destroy -files within the added file system, depending on how the file system is mounted. +administrator. +However, the zone administrator can create, modify, or destroy files within the +added file system, depending on how the file system is mounted. .Pp A dataset can also be delegated to a non-global zone by using the .Nm zonecfg Cm add Sy dataset -subcommand. You cannot delegate a dataset to one zone and the children of the -same dataset to another zone. The zone administrator can change properties of -the dataset or any of its children. However, the +subcommand. +You cannot delegate a dataset to one zone and the children of the same dataset +to another zone. +The zone administrator can change properties of the dataset or any of its +children. +However, the .Sy quota , .Sy filesystem_limit and @@ -426,7 +445,8 @@ administrator. .Pp A ZFS volume can be added as a device to a non-global zone by using the .Nm zonecfg Cm add Sy device -subcommand. However, its physical properties can be modified only by the global +subcommand. +However, its physical properties can be modified only by the global administrator. .Pp For more information about @@ -436,32 +456,33 @@ syntax, see .Pp After a dataset is delegated to a non-global zone, the .Sy zoned -property is automatically set. A zoned file system cannot be mounted in the -global zone, since the zone administrator might have to set the mount point to -an unacceptable value. +property is automatically set. +A zoned file system cannot be mounted in the global zone, since the zone +administrator might have to set the mount point to an unacceptable value. .Pp The global administrator can forcibly clear the .Sy zoned -property, though this should be done with extreme care. The global administrator -should verify that all the mount points are acceptable before clearing the -property. +property, though this should be done with extreme care. +The global administrator should verify that all the mount points are acceptable +before clearing the property. .Ss Native Properties Properties are divided into two types, native properties and user-defined .Po or .Qq user .Pc -properties. Native properties either export internal statistics or control ZFS -behavior. In addition, native properties are either editable or read-only. User -properties have no effect on ZFS behavior, but you can use them to annotate -datasets in a way that is meaningful in your environment. For more information -about user properties, see the +properties. +Native properties either export internal statistics or control ZFS behavior. +In addition, native properties are either editable or read-only. +User properties have no effect on ZFS behavior, but you can use them to annotate +datasets in a way that is meaningful in your environment. +For more information about user properties, see the .Sx User Properties section, below. .Pp Every dataset has a set of properties that export statistics about the dataset -as well as control various behaviors. Properties are inherited from the parent -unless overridden by the child. Some properties apply only to certain types of -datasets +as well as control various behaviors. +Properties are inherited from the parent unless overridden by the child. +Some properties apply only to certain types of datasets .Pq file systems, volumes, or snapshots . .Pp The values of numeric properties can be specified using human-readable suffixes @@ -487,28 +508,33 @@ and .Sy sharesmb . .Pp The following native properties consist of read-only statistics about the -dataset. These properties can be neither set, nor inherited. Native properties -apply to all dataset types unless otherwise noted. +dataset. +These properties can be neither set, nor inherited. +Native properties apply to all dataset types unless otherwise noted. .Bl -tag -width "usedbyrefreservation" .It Sy available The amount of space available to the dataset and all its children, assuming that -there is no other activity in the pool. Because space is shared within a pool, -availability can be limited by any number of factors, including physical pool -size, quotas, reservations, or other datasets within the pool. +there is no other activity in the pool. +Because space is shared within a pool, availability can be limited by any number +of factors, including physical pool size, quotas, reservations, or other +datasets within the pool. .Pp This property can also be referred to by its shortened column name, .Sy avail . .It Sy compressratio For non-snapshots, the compression ratio achieved for the .Sy used -space of this dataset, expressed as a multiplier. The +space of this dataset, expressed as a multiplier. +The .Sy used property includes descendant datasets, and, for clones, does not include the -space shared with the origin snapshot. For snapshots, the +space shared with the origin snapshot. +For snapshots, the .Sy compressratio is the same as the .Sy refcompressratio -property. Compression can be turned on by running: +property. +Compression can be turned on by running: .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . The default value is .Sy off . @@ -516,9 +542,11 @@ The default value is The time this dataset was created. .It Sy clones For snapshots, this property is a comma-separated list of filesystems or volumes -which are clones of this snapshot. The clones' +which are clones of this snapshot. +The clones' .Sy origin -property is this snapshot. If the +property is this snapshot. +If the .Sy clones property is not empty, then this snapshot can not be destroyed .Po even with the @@ -532,50 +560,59 @@ This property is .Sy on if the snapshot has been marked for deferred destroy by using the .Nm zfs Cm destroy Fl d -command. Otherwise, the property is +command. +Otherwise, the property is .Sy off . .It Sy filesystem_count The total number of filesystems and volumes that exist under this location in -the dataset tree. This value is only available when a +the dataset tree. +This value is only available when a .Sy filesystem_limit has been set somewhere in the tree under which the dataset resides. .It Sy logicalreferenced The amount of space that is .Qq logically -accessible by this dataset. See the +accessible by this dataset. +See the .Sy referenced -property. The logical space ignores the effect of the +property. +The logical space ignores the effect of the .Sy compression and .Sy copies properties, giving a quantity closer to the amount of data that applications -see. However, it does include space consumed by metadata. +see. +However, it does include space consumed by metadata. .Pp This property can also be referred to by its shortened column name, .Sy lrefer . .It Sy logicalused The amount of space that is .Qq logically -consumed by this dataset and all its descendents. See the +consumed by this dataset and all its descendents. +See the .Sy used -property. The logical space ignores the effect of the +property. +The logical space ignores the effect of the .Sy compression and .Sy copies properties, giving a quantity closer to the amount of data that applications -see. However, it does include space consumed by metadata. +see. +However, it does include space consumed by metadata. .Pp This property can also be referred to by its shortened column name, .Sy lused . .It Sy mounted -For file systems, indicates whether the file system is currently mounted. This -property can be either +For file systems, indicates whether the file system is currently mounted. +This property can be either .Sy yes or .Sy no . .It Sy origin For cloned file systems or volumes, the snapshot from which the clone was -created. See also the +created. +See also the .Sy clones property. .It Sy receive_resume_token @@ -587,21 +624,24 @@ to resume and complete the .Sy zfs receive . .It Sy referenced The amount of data that is accessible by this dataset, which may or may not be -shared with other datasets in the pool. When a snapshot or clone is created, it -initially references the same amount of space as the file system or snapshot it -was created from, since its contents are identical. +shared with other datasets in the pool. +When a snapshot or clone is created, it initially references the same amount of +space as the file system or snapshot it was created from, since its contents are +identical. .Pp This property can also be referred to by its shortened column name, .Sy refer . .It Sy refcompressratio The compression ratio achieved for the .Sy referenced -space of this dataset, expressed as a multiplier. See also the +space of this dataset, expressed as a multiplier. +See also the .Sy compressratio property. .It Sy snapshot_count The total number of snapshots that exist under this location in the dataset -tree. This value is only available when a +tree. +This value is only available when a .Sy snapshot_limit has been set somewhere in the tree under which the dataset resides. .It Sy type @@ -611,35 +651,39 @@ The type of dataset: or .Sy snapshot . .It Sy used -The amount of space consumed by this dataset and all its descendents. This is -the value that is checked against this dataset's quota and reservation. The -space used does not include this dataset's reservation, but does take into -account the reservations of any descendent datasets. The amount of space that a -dataset consumes from its parent, as well as the amount of space that is freed -if this dataset is recursively destroyed, is the greater of its space used and -its reservation. +The amount of space consumed by this dataset and all its descendents. +This is the value that is checked against this dataset's quota and reservation. +The space used does not include this dataset's reservation, but does take into +account the reservations of any descendent datasets. +The amount of space that a dataset consumes from its parent, as well as the +amount of space that is freed if this dataset is recursively destroyed, is the +greater of its space used and its reservation. .Pp The used space of a snapshot .Po see the .Sx Snapshots section .Pc -is space that is referenced exclusively by this snapshot. If this snapshot is -destroyed, the amount of +is space that is referenced exclusively by this snapshot. +If this snapshot is destroyed, the amount of .Sy used -space will be freed. Space that is shared by multiple snapshots isn't accounted -for in this metric. When a snapshot is destroyed, space that was previously -shared with this snapshot can become unique to snapshots adjacent to it, thus -changing the used space of those snapshots. The used space of the latest -snapshot can also be affected by changes in the file system. Note that the +space will be freed. +Space that is shared by multiple snapshots isn't accounted for in this metric. +When a snapshot is destroyed, space that was previously shared with this +snapshot can become unique to snapshots adjacent to it, thus changing the used +space of those snapshots. +The used space of the latest snapshot can also be affected by changes in the +file system. +Note that the .Sy used space of a snapshot is a subset of the .Sy written space of the snapshot. .Pp The amount of space used, available, or referenced does not take into account -pending changes. Pending changes are generally accounted for within a few -seconds. Committing a change to a disk using +pending changes. +Pending changes are generally accounted for within a few seconds. +Committing a change to a disk using .Xr fsync 3C or .Dv O_SYNC @@ -650,7 +694,8 @@ The .Sy usedby* properties decompose the .Sy used -properties into the various reasons that space is used. Specifically, +properties into the various reasons that space is used. +Specifically, .Sy used No = .Sy usedbychildren No + .Sy usedbydataset No + @@ -677,14 +722,15 @@ set on this dataset, which would be freed if the .Sy refreservation was removed. .It Sy usedbysnapshots -The amount of space consumed by snapshots of this dataset. In particular, it is -the amount of space that would be freed if all of this dataset's snapshots were -destroyed. Note that this is not simply the sum of the snapshots' +The amount of space consumed by snapshots of this dataset. +In particular, it is the amount of space that would be freed if all of this +dataset's snapshots were destroyed. +Note that this is not simply the sum of the snapshots' .Sy used properties because space can be shared by multiple snapshots. .It Sy userused Ns @ Ns Em user -The amount of space consumed by the specified user in this dataset. Space is -charged to the owner of each file, as displayed by +The amount of space consumed by the specified user in this dataset. +Space is charged to the owner of each file, as displayed by .Nm ls Fl l . The amount of space charged is displayed by .Nm du @@ -694,8 +740,8 @@ See the .Nm zfs Cm userspace subcommand for more information. .Pp -Unprivileged users can access only their own space usage. The root user, or a -user who has been granted the +Unprivileged users can access only their own space usage. +The root user, or a user who has been granted the .Sy userused privilege with .Nm zfs Cm allow , @@ -730,31 +776,34 @@ forms: .Pc .El .It Sy userrefs -This property is set to the number of user holds on this snapshot. User holds -are set by using the +This property is set to the number of user holds on this snapshot. +User holds are set by using the .Nm zfs Cm hold command. .It Sy groupused Ns @ Ns Em group -The amount of space consumed by the specified group in this dataset. Space is -charged to the group of each file, as displayed by +The amount of space consumed by the specified group in this dataset. +Space is charged to the group of each file, as displayed by .Nm ls Fl l . See the .Sy userused Ns @ Ns Em user property for more information. .Pp -Unprivileged users can only access their own groups' space usage. The root user, -or a user who has been granted the +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the .Sy groupused privilege with .Nm zfs Cm allow , can access all groups' usage. .It Sy volblocksize -For volumes, specifies the block size of the volume. The +For volumes, specifies the block size of the volume. +The .Sy blocksize cannot be changed once the volume has been written, so it should be set at -volume creation time. The default +volume creation time. +The default .Sy blocksize -for volumes is 8 Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid. +for volumes is 8 Kbytes. +Any power of 2 from 512 bytes to 128 Kbytes is valid. .Pp This property can also be referred to by its shortened column name, .Sy volblock . @@ -766,9 +815,9 @@ by this dataset, that was written since the previous snapshot .It Sy written Ns @ Ns Em snapshot The amount of .Sy referenced -space written to this dataset since the specified snapshot. This is the space -that is referenced by this dataset but was not referenced by the specified -snapshot. +space written to this dataset since the specified snapshot. +This is the space that is referenced by this dataset but was not referenced by +the specified snapshot. .Pp The .Em snapshot @@ -777,7 +826,8 @@ may be specified as a short snapshot name .Sy @ .Pc , in which case it will be interpreted as a snapshot in the same filesystem as -this dataset. The +this dataset. +The .Em snapshot may be a full snapshot name .Po Em filesystem Ns @ Ns Em snapshot Pc , @@ -854,7 +904,8 @@ non-trivial ACL, with entries in addition to those that represent the mode. .Pp .Xr chmod 2 is required to change the set user ID, set group ID, or sticky bit on a file or -directory, as they do not have equivalent ACEs. In order to use +directory, as they do not have equivalent ACEs. +In order to use .Xr chmod 2 on a file or directory with a non-trivial ACL when .Sy aclmode @@ -865,7 +916,8 @@ you must first remove all ACEs except for those that represent the current mode. Controls whether the access time for files is updated when they are read. Turning this property off avoids producing write traffic when reading files and can result in significant performance gains, though it might confuse mailers -and other similar utilities. The default value is +and other similar utilities. +The default value is .Sy on . .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto If this property is set to @@ -880,10 +932,11 @@ property to .Sy none , except that the dataset still has a normal .Sy mountpoint -property, which can be inherited. Setting this property to +property, which can be inherited. +Setting this property to .Sy off -allows datasets to be used solely as a mechanism to inherit properties. One -example of setting +allows datasets to be used solely as a mechanism to inherit properties. +One example of setting .Sy canmount Ns = Ns Sy off is to have two datasets with the same .Sy mountpoint , @@ -892,9 +945,9 @@ have different inherited characteristics. .Pp When set to .Sy noauto , -a dataset can only be mounted and unmounted explicitly. The dataset is not -mounted automatically when the dataset is created or imported, nor is it mounted -by the +a dataset can only be mounted and unmounted explicitly. +The dataset is not mounted automatically when the dataset is created or +imported, nor is it mounted by the .Nm zfs Cm mount Fl a command or unmounted by the .Nm zfs Cm unmount Fl a @@ -906,7 +959,8 @@ This property is not inherited. .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr .Xc -Controls the checksum used to verify data integrity. The default value is +Controls the checksum used to verify data integrity. +The default value is .Sy on , which automatically selects an appropriate algorithm .Po currently, @@ -915,11 +969,13 @@ but this may change in future releases .Pc . The value .Sy off -disables integrity checking on user data. The value +disables integrity checking on user data. +The value .Sy noparity not only disables integrity but also disables maintaining parity for user data. This setting is used internally by a dump device residing on a RAID-Z pool and -should not be used by any other dataset. Disabling checksums is +should not be used by any other dataset. +Disabling checksums is .Sy NOT a recommended practice. .Pp @@ -928,8 +984,8 @@ The .Sy skein , and .Sy edonr -checksum algorithms require enabling the appropriate features on the -pool. Please see +checksum algorithms require enabling the appropriate features on the pool. +Please see .Xr zpool-features 5 for more information on these algorithms. .Pp @@ -942,14 +998,15 @@ Controls the compression algorithm used for this dataset. .Pp Setting compression to .Sy on -indicates that the current default compression algorithm should be used. The -default balances compression and decompression speed, with compression ratio and -is expected to work well on a wide variety of workloads. Unlike all other -settings for this property, +indicates that the current default compression algorithm should be used. +The default balances compression and decompression speed, with compression ratio +and is expected to work well on a wide variety of workloads. +Unlike all other settings for this property, .Sy on -does not select a fixed compression type. As new compression algorithms are -added to ZFS and enabled on a pool, the default compression algorithm may -change. The current default compression algorithm is either +does not select a fixed compression type. +As new compression algorithms are added to ZFS and enabled on a pool, the +default compression algorithm may change. +The current default compression algorithm is either .Sy lzjb or, if the .Sy lz4_compress @@ -960,8 +1017,9 @@ The .Sy lz4 compression algorithm is a high-performance replacement for the .Sy lzjb -algorithm. It features significantly faster compression and decompression, as -well as a moderately higher compression ratio than +algorithm. +It features significantly faster compression and decompression, as well as a +moderately higher compression ratio than .Sy lzjb , but can only be used on pools with the .Sy lz4_compress @@ -982,7 +1040,8 @@ The .Sy gzip compression algorithm uses the same compression as the .Xr gzip 1 -command. You can specify the +command. +You can specify the .Sy gzip level by using the value .Sy gzip- Ns Em N , @@ -1005,31 +1064,35 @@ The compression algorithm compresses runs of zeros. .Pp This property can also be referred to by its shortened column name -\fBcompress\fR. Changing this property affects only newly-written data. +.Sy compress . +Changing this property affects only newly-written data. .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 -Controls the number of copies of data stored for this dataset. These copies are -in addition to any redundancy provided by the pool, for example, mirroring or -RAID-Z. The copies are stored on different disks, if possible. The space used -by multiple copies is charged to the associated file and dataset, changing the +Controls the number of copies of data stored for this dataset. +These copies are in addition to any redundancy provided by the pool, for +example, mirroring or RAID-Z. +The copies are stored on different disks, if possible. +The space used by multiple copies is charged to the associated file and dataset, +changing the .Sy used property and counting against quotas and reservations. .Pp -Changing this property only affects newly-written data. Therefore, set this -property at file system creation time by using the +Changing this property only affects newly-written data. +Therefore, set this property at file system creation time by using the .Fl o Sy copies Ns = Ns Ar N option. .It Sy devices Ns = Ns Sy on Ns | Ns Sy off -Controls whether device nodes can be opened on this file system. The default -value is +Controls whether device nodes can be opened on this file system. +The default value is .Sy on . .It Sy exec Ns = Ns Sy on Ns | Ns Sy off -Controls whether processes can be executed from within this file system. The -default value is +Controls whether processes can be executed from within this file system. +The default value is .Sy on . .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none Limits the number of filesystems and volumes that can exist under this point in -the dataset tree. The limit is not enforced if the user is allowed to change -the limit. Setting a +the dataset tree. +The limit is not enforced if the user is allowed to change the limit. +Setting a .Sy filesystem_limit to .Sy on @@ -1037,33 +1100,40 @@ a descendent of a filesystem that already has a .Sy filesystem_limit does not override the ancestor's .Sy filesystem_limit , -but rather imposes an additional limit. This feature must be enabled to be used +but rather imposes an additional limit. +This feature must be enabled to be used .Po see .Xr zpool-features 5 .Pc . .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy -Controls the mount point used for this file system. See the +Controls the mount point used for this file system. +See the .Sx Mount Points section for more information on how this property is used. .Pp When the .Sy mountpoint property is changed for a file system, the file system and any children that -inherit the mount point are unmounted. If the new value is +inherit the mount point are unmounted. +If the new value is .Sy legacy , -then they remain unmounted. Otherwise, they are automatically remounted in the -new location if the property was previously +then they remain unmounted. +Otherwise, they are automatically remounted in the new location if the property +was previously .Sy legacy or .Sy none , -or if they were mounted before the property was changed. In addition, any shared -file systems are unshared and shared in the new location. +or if they were mounted before the property was changed. +In addition, any shared file systems are unshared and shared in the new +location. .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off Controls whether the file system should be mounted with .Sy nbmand .Pq Non Blocking mandatory locks . -This is used for SMB clients. Changes to this property only take effect when the -file system is umounted and remounted. See +This is used for SMB clients. +Changes to this property only take effect when the file system is umounted and +remounted. +See .Xr mount 1M for more information on .Sy nbmand @@ -1073,60 +1143,68 @@ Controls what is cached in the primary cache .Pq ARC . If this property is set to .Sy all , -then both user data and metadata is cached. If this property is set to +then both user data and metadata is cached. +If this property is set to .Sy none , -then neither user data nor metadata is cached. If this property is set to +then neither user data nor metadata is cached. +If this property is set to .Sy metadata , -then only metadata is cached. The default value is +then only metadata is cached. +The default value is .Sy all . .It Sy quota Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space a dataset and its descendents can consume. This -property enforces a hard limit on the amount of space used. This includes all -space consumed by descendents, including file systems and snapshots. Setting a -quota on a descendent of a dataset that already has a quota does not override -the ancestor's quota, but rather imposes an additional limit. +Limits the amount of space a dataset and its descendents can consume. +This property enforces a hard limit on the amount of space used. +This includes all space consumed by descendents, including file systems and +snapshots. +Setting a quota on a descendent of a dataset that already has a quota does not +override the ancestor's quota, but rather imposes an additional limit. .Pp Quotas cannot be set on volumes, as the .Sy volsize property acts as an implicit quota. .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none Limits the number of snapshots that can be created on a dataset and its -descendents. Setting a +descendents. +Setting a .Sy snapshot_limit on a descendent of a dataset that already has a .Sy snapshot_limit does not override the ancestor's .Sy snapshot_limit , -but rather imposes an additional limit. The limit is not enforced if the user is -allowed to change the limit. For example, this means that recursive snapshots -taken from the global zone are counted against each delegated dataset within -a zone. This feature must be enabled to be used +but rather imposes an additional limit. +The limit is not enforced if the user is allowed to change the limit. +For example, this means that recursive snapshots taken from the global zone are +counted against each delegated dataset within a zone. +This feature must be enabled to be used .Po see .Xr zpool-features 5 .Pc . .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space consumed by the specified user. User space -consumption is identified by the +Limits the amount of space consumed by the specified user. +User space consumption is identified by the .Sy userspace@ Ns Em user property. .Pp -Enforcement of user quotas may be delayed by several seconds. This delay means -that a user might exceed their quota before the system notices that they are -over quota and begins to refuse additional writes with the +Enforcement of user quotas may be delayed by several seconds. +This delay means that a user might exceed their quota before the system notices +that they are over quota and begins to refuse additional writes with the .Er EDQUOT -error message. See the +error message. +See the .Nm zfs Cm userspace subcommand for more information. .Pp -Unprivileged users can only access their own groups' space usage. The root -user, or a user who has been granted the +Unprivileged users can only access their own groups' space usage. +The root user, or a user who has been granted the .Sy userquota privilege with .Nm zfs Cm allow , can get and set everyone's quota. .Pp This property is not available on volumes, on file systems before version 4, or -on pools before version 15. The +on pools before version 15. +The .Sy userquota@ Ns Em ... properties are not displayed by .Nm zfs Cm get Sy all . @@ -1156,40 +1234,46 @@ symbol, using one of the following forms: .Pc .El .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space consumed by the specified group. Group space -consumption is identified by the +Limits the amount of space consumed by the specified group. +Group space consumption is identified by the .Sy groupused@ Ns Em group property. .Pp -Unprivileged users can access only their own groups' space usage. The root -user, or a user who has been granted the +Unprivileged users can access only their own groups' space usage. +The root user, or a user who has been granted the .Sy groupquota privilege with .Nm zfs Cm allow , can get and set all groups' quotas. .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off -Controls whether this dataset can be modified. The default value is +Controls whether this dataset can be modified. +The default value is .Sy off . .Pp This property can also be referred to by its shortened column name, .Sy rdonly . .It Sy recordsize Ns = Ns Em size -Specifies a suggested block size for files in the file system. This property is -designed solely for use with database workloads that access files in fixed-size -records. ZFS automatically tunes block sizes according to internal algorithms -optimized for typical access patterns. +Specifies a suggested block size for files in the file system. +This property is designed solely for use with database workloads that access +files in fixed-size records. +ZFS automatically tunes block sizes according to internal algorithms optimized +for typical access patterns. .Pp For databases that create very large files but access them in small random -chunks, these algorithms may be suboptimal. Specifying a +chunks, these algorithms may be suboptimal. +Specifying a .Sy recordsize greater than or equal to the record size of the database can result in -significant performance gains. Use of this property for general purpose file -systems is strongly discouraged, and may adversely affect performance. +significant performance gains. +Use of this property for general purpose file systems is strongly discouraged, +and may adversely affect performance. .Pp The size specified must be a power of two greater than or equal to 512 and less -than or equal to 128 Kbytes. If the +than or equal to 128 Kbytes. +If the .Sy large_blocks -feature is enabled on the pool, the size may be up to 1 Mbyte. See +feature is enabled on the pool, the size may be up to 1 Mbyte. +See .Xr zpool-features 5 for details on ZFS feature flags. .Pp @@ -1200,10 +1284,10 @@ affects only files created afterward; existing files are unaffected. This property can also be referred to by its shortened column name, .Sy recsize . .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most -Controls what types of metadata are stored redundantly. ZFS stores an extra copy -of metadata, so that if a single block is corrupted, the amount of user data -lost is limited. This extra copy is in addition to any redundancy provided at -the pool level +Controls what types of metadata are stored redundantly. +ZFS stores an extra copy of metadata, so that if a single block is corrupted, +the amount of user data lost is limited. +This extra copy is in addition to any redundancy provided at the pool level .Pq e.g. by mirroring or RAID-Z , and is in addition to an extra copy specified by the .Sy copies @@ -1218,8 +1302,8 @@ metadata. .Pp When set to .Sy all , -ZFS stores an extra copy of all metadata. If a single on-disk block is corrupt, -at worst a single block of user data +ZFS stores an extra copy of all metadata. +If a single on-disk block is corrupt, at worst a single block of user data .Po which is .Sy recordsize bytes long @@ -1228,27 +1312,30 @@ can be lost. .Pp When set to .Sy most , -ZFS stores an extra copy of most types of metadata. This can improve performance -of random writes, because less metadata must be written. In practice, at worst -about 100 blocks +ZFS stores an extra copy of most types of metadata. +This can improve performance of random writes, because less metadata must be +written. +In practice, at worst about 100 blocks .Po of .Sy recordsize bytes each .Pc -of user data can be lost if a single on-disk block is corrupt. The exact -behavior of which metadata blocks are stored redundantly may change in future -releases. +of user data can be lost if a single on-disk block is corrupt. +The exact behavior of which metadata blocks are stored redundantly may change in +future releases. .Pp The default value is .Sy all . .It Sy refquota Ns = Ns Em size Ns | Ns Sy none -Limits the amount of space a dataset can consume. This property enforces a hard -limit on the amount of space used. This hard limit does not include space used -by descendents, including file systems and snapshots. +Limits the amount of space a dataset can consume. +This property enforces a hard limit on the amount of space used. +This hard limit does not include space used by descendents, including file +systems and snapshots. .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none The minimum amount of space guaranteed to a dataset, not including its -descendents. When the amount of space used is below this value, the dataset is -treated as if it were taking up the amount of space specified by +descendents. +When the amount of space used is below this value, the dataset is treated as if +it were taking up the amount of space specified by .Sy refreservation . The .Sy refreservation @@ -1265,11 +1352,11 @@ bytes in the dataset. This property can also be referred to by its shortened column name, .Sy refreserv . .It Sy reservation Ns = Ns Em size Ns | Ns Sy none -The minimum amount of space guaranteed to a dataset and its descendents. When -the amount of space used is below this value, the dataset is treated as if it -were taking up the amount of space specified by its reservation. Reservations -are accounted for in the parent datasets' space used, and count against the -parent datasets' quotas and reservations. +The minimum amount of space guaranteed to a dataset and its descendents. +When the amount of space used is below this value, the dataset is treated as if +it were taking up the amount of space specified by its reservation. +Reservations are accounted for in the parent datasets' space used, and count +against the parent datasets' quotas and reservations. .Pp This property can also be referred to by its shortened column name, .Sy reserv . @@ -1278,19 +1365,23 @@ Controls what is cached in the secondary cache .Pq L2ARC . If this property is set to .Sy all , -then both user data and metadata is cached. If this property is set to +then both user data and metadata is cached. +If this property is set to .Sy none , -then neither user data nor metadata is cached. If this property is set to +then neither user data nor metadata is cached. +If this property is set to .Sy metadata , -then only metadata is cached. The default value is +then only metadata is cached. +The default value is .Sy all . .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off -Controls whether the setuid bit is respected for the file system. The default -value is +Controls whether the setuid bit is respected for the file system. +The default value is .Sy on . .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts Controls whether the file system is shared via SMB, and what options are to be -used. A file system with the +used. +A file system with the .Sy sharesmb property set to .Sy off @@ -1300,24 +1391,30 @@ Otherwise, the file system is automatically shared and unshared with the .Nm zfs Cm share and .Nm zfs Cm unshare -commands. If the property is set to +commands. +If the property is set to .Sy on , the .Xr sharemgr 1M -command is invoked with no options. Otherwise, the +command is invoked with no options. +Otherwise, the .Xr sharemgr 1M command is invoked with options equivalent to the contents of this property. .Pp Because SMB shares requires a resource name, a unique resource name is -constructed from the dataset name. The constructed name is a copy of the dataset -name except that the characters in the dataset name, which would be illegal in -the resource name, are replaced with underscore +constructed from the dataset name. +The constructed name is a copy of the dataset name except that the characters in +the dataset name, which would be illegal in the resource name, are replaced with +underscore .Pq Sy _ -characters. A pseudo property +characters. +A pseudo property .Qq name is also supported that allows you to replace the data set name with a specified -name. The specified name is then used to replace the prefix dataset in the case -of inheritance. For example, if the dataset +name. +The specified name is then used to replace the prefix dataset in the case of +inheritance. +For example, if the dataset .Em data/home/john is set to .Sy name Ns = Ns Sy john , @@ -1332,7 +1429,8 @@ is shared, it has a resource name of .Pp When SMB shares are created, the SMB share name appears as an entry in the .Pa .zfs/shares -directory. You can use the +directory. +You can use the .Nm ls or .Nm chmod @@ -1344,13 +1442,14 @@ property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously set to .Sy off , -or if they were shared before the property was changed. If the new property is -set to +or if they were shared before the property was changed. +If the new property is set to .Sy off , the file systems are unshared. .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts Controls whether the file system is shared via NFS, and what options are to be -used. A file system with a +used. +A file system with a .Sy sharenfs property of .Sy off @@ -1363,10 +1462,12 @@ Otherwise, the file system is automatically shared and unshared with the .Nm zfs Cm share and .Nm zfs Cm unshare -commands. If the property is set to +commands. +If the property is set to .Sy on , .Xr share 1M -command is invoked with no options. Otherwise, the +command is invoked with no options. +Otherwise, the .Xr share 1M command is invoked with options equivalent to the contents of this property. .Pp @@ -1375,31 +1476,35 @@ When the property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously .Sy off , -or if they were shared before the property was changed. If the new property is +or if they were shared before the property was changed. +If the new property is .Sy off , the file systems are unshared. .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput -Provide a hint to ZFS about handling of synchronous requests in this dataset. If +Provide a hint to ZFS about handling of synchronous requests in this dataset. +If .Sy logbias is set to .Sy latency .Pq the default , ZFS will use pool log devices .Pq if configured -to handle the requests at low latency. If +to handle the requests at low latency. +If .Sy logbias is set to .Sy throughput , -ZFS will not use configured pool log devices. ZFS will instead optimize -synchronous operations for global pool throughput and efficient use of -resources. +ZFS will not use configured pool log devices. +ZFS will instead optimize synchronous operations for global pool throughput and +efficient use of resources. .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible Controls whether the .Pa .zfs directory is hidden or visible in the root of the file system as discussed in the .Sx Snapshots -section. The default value is +section. +The default value is .Sy hidden . .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled Controls the behavior of synchronous requests @@ -1413,24 +1518,29 @@ controllers .Pq this is the default . .Sy always causes every file system transaction to be written and flushed before its -system call returns. This has a large performance penalty. +system call returns. +This has a large performance penalty. .Sy disabled -disables synchronous requests. File system transactions are only committed to -stable storage periodically. This option will give the highest performance. +disables synchronous requests. +File system transactions are only committed to stable storage periodically. +This option will give the highest performance. However, it is very dangerous as ZFS would be ignoring the synchronous -transaction demands of applications such as databases or NFS. Administrators -should only use this option when the risks are understood. +transaction demands of applications such as databases or NFS. +Administrators should only use this option when the risks are understood. .It Sy version Ns = Ns Em N Ns | Ns Sy current The on-disk version of this file system, which is independent of the pool -version. This property can only be set to later supported versions. See the +version. +This property can only be set to later supported versions. +See the .Nm zfs Cm upgrade command. .It Sy volsize Ns = Ns Em size -For volumes, specifies the logical size of the volume. By default, creating a -volume establishes a reservation of equal size. For storage pools with a version -number of 9 or higher, a +For volumes, specifies the logical size of the volume. +By default, creating a volume establishes a reservation of equal size. +For storage pools with a version number of 9 or higher, a .Sy refreservation -is set instead. Any changes to +is set instead. +Any changes to .Sy volsize are reflected in an equivalent change to the reservation .Po or @@ -1443,10 +1553,10 @@ can only be set to a multiple of and cannot be zero. .Pp The reservation is kept equal to the volume's logical size to prevent unexpected -behavior for consumers. Without the reservation, the volume could run out of -space, resulting in undefined behavior or data corruption, depending on how the -volume is used. These effects can also occur when the volume size is changed -while it is in use +behavior for consumers. +Without the reservation, the volume could run out of space, resulting in +undefined behavior or data corruption, depending on how the volume is used. +These effects can also occur when the volume size is changed while it is in use .Pq particularly when shrinking the size . Extreme care should be used when adjusting the volume size. .Pp @@ -1459,40 +1569,46 @@ can be created by specifying the .Fl s option to the .Nm zfs Cm create Fl V -command, or by changing the reservation after the volume has been created. A +command, or by changing the reservation after the volume has been created. +A .Qq sparse volume -is a volume where the reservation is less then the volume size. Consequently, -writes to a sparse volume can fail with +is a volume where the reservation is less then the volume size. +Consequently, writes to a sparse volume can fail with .Er ENOSPC -when the pool is low on space. For a sparse volume, changes to +when the pool is low on space. +For a sparse volume, changes to .Sy volsize are not reflected in the reservation. .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off Controls whether regular files should be scanned for viruses when a file is -opened and closed. In addition to enabling this property, the virus scan -service must also be enabled for virus scanning to occur. The default value is +opened and closed. +In addition to enabling this property, the virus scan service must also be +enabled for virus scanning to occur. +The default value is .Sy off . .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off -Controls whether extended attributes are enabled for this file system. The -default value is +Controls whether extended attributes are enabled for this file system. +The default value is .Sy on . .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off -Controls whether the dataset is managed from a non-global zone. See the +Controls whether the dataset is managed from a non-global zone. +See the .Sx Zones -section for more information. The default value is +section for more information. +The default value is .Sy off . .El .Pp The following three properties cannot be changed after the file system is -created, and therefore, should be set when the file system is created. If the -properties are not set with the +created, and therefore, should be set when the file system is created. +If the properties are not set with the .Nm zfs Cm create or .Nm zpool Cm create -commands, these properties are inherited from the parent dataset. If the parent -dataset lacks these properties due to having been created prior to these -features being supported, the new file system will have the default values for -these properties. +commands, these properties are inherited from the parent dataset. +If the parent dataset lacks these properties due to having been created prior to +these features being supported, the new file system will have the default values +for these properties. .Bl -tag -width "" .It Xo .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns @@ -1500,7 +1616,8 @@ these properties. .Xc Indicates whether the file name matching algorithm used by the file system should be case-sensitive, case-insensitive, or allow a combination of both -styles of matching. The default value for the +styles of matching. +The default value for the .Sy casesensitivity property is .Sy sensitive . @@ -1515,9 +1632,10 @@ The value for the .Sy casesensitivity property indicates that the file system can support requests for both -case-sensitive and case-insensitive matching behavior. Currently, -case-insensitive matching behavior on a file system that supports mixed behavior -is limited to the SMB server product. For more information about the +case-sensitive and case-insensitive matching behavior. +Currently, case-insensitive matching behavior on a file system that supports +mixed behavior is limited to the SMB server product. +For more information about the .Sy mixed value behavior, see the "ZFS Administration Guide". .It Xo @@ -1527,9 +1645,10 @@ value behavior, see the "ZFS Administration Guide". Indicates whether the file system should perform a .Sy unicode normalization of file names whenever two file names are compared, and which -normalization algorithm should be used. File names are always stored unmodified, -names are normalized as part of any comparison process. If this property is set -to a legal value other than +normalization algorithm should be used. +File names are always stored unmodified, names are normalized as part of any +comparison process. +If this property is set to a legal value other than .Sy none , and the .Sy utf8only @@ -1546,7 +1665,8 @@ This property cannot be changed after the file system is created. Indicates whether the file system should reject file names that include characters that are not present in the .Sy UTF-8 -character code set. If this property is explicitly set to +character code set. +If this property is explicitly set to .Sy off , the normalization property must either not be explicitly set or be set to .Sy none . @@ -1570,7 +1690,8 @@ When a file system is mounted, either through for legacy mounts or the .Nm zfs Cm mount command for normal file systems, its mount options are set according to its -properties. The correlation between properties and mount options is as follows: +properties. +The correlation between properties and mount options is as follows: .Bd -literal PROPERTY MOUNT OPTION devices devices/nodevices @@ -1582,8 +1703,10 @@ properties. The correlation between properties and mount options is as follows: .Pp In addition, these options can be set on a per-mount basis using the .Fl o -option, without affecting the property that is stored on disk. The values -specified on the command line override the values stored in the dataset. The +option, without affecting the property that is stored on disk. +The values specified on the command line override the values stored in the +dataset. +The .Sy nosuid option is an alias for .Sy nodevices Ns , Ns Sy nosetuid . @@ -1591,18 +1714,21 @@ These properties are reported as .Qq temporary by the .Nm zfs Cm get -command. If the properties are changed while the dataset is mounted, the new -setting overrides any temporary settings. +command. +If the properties are changed while the dataset is mounted, the new setting +overrides any temporary settings. .Ss "User Properties" In addition to the standard native properties, ZFS supports arbitrary user -properties. User properties have no effect on ZFS behavior, but applications or +properties. +User properties have no effect on ZFS behavior, but applications or administrators can use them to annotate datasets .Pq file systems, volumes, and snapshots . .Pp User property names must contain a colon .Pq Qq Sy \&: -character to distinguish them from native properties. They may contain lowercase -letters, numbers, and the following punctuation characters: colon +character to distinguish them from native properties. +They may contain lowercase letters, numbers, and the following punctuation +characters: colon .Pq Qq Sy \&: , dash .Pq Qq Sy - , @@ -1627,23 +1753,29 @@ independently-developed packages use the same property name for different purposes. .Pp The values of user properties are arbitrary strings, are always inherited, and -are never validated. All of the commands that operate on properties +are never validated. +All of the commands that operate on properties .Po Nm zfs Cm list , .Nm zfs Cm get , .Nm zfs Cm set , and so forth .Pc -can be used to manipulate both native properties and user properties. Use the +can be used to manipulate both native properties and user properties. +Use the .Nm zfs Cm inherit -command to clear a user property. If the property is not defined in any parent -dataset, it is removed entirely. Property values are limited to 8192 bytes. +command to clear a user property. +If the property is not defined in any parent dataset, it is removed entirely. +Property values are limited to 8192 bytes. .Ss ZFS Volumes as Swap or Dump Devices During an initial installation a swap device and dump device are created on ZFS -volumes in the ZFS root pool. By default, the swap area size is based on 1/2 the -size of physical memory up to 2 Gbytes. The size of the dump device depends on -the kernel's requirements at installation time. Separate ZFS volumes must be -used for the swap area and dump devices. Do not swap to a file on a ZFS file -system. A ZFS swap file configuration is not supported. +volumes in the ZFS root pool. +By default, the swap area size is based on 1/2 the size of physical memory up to +2 Gbytes. +The size of the dump device depends on the kernel's requirements at installation +time. +Separate ZFS volumes must be used for the swap area and dump devices. +Do not swap to a file on a ZFS file system. +A ZFS swap file configuration is not supported. .Pp If you need to change your swap area or dump device after the system is installed or upgraded, use the @@ -1664,30 +1796,31 @@ Displays a help message. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Ar filesystem .Xc -Creates a new ZFS file system. The file system is automatically mounted -according to the +Creates a new ZFS file system. +The file system is automatically mounted according to the .Sy mountpoint property inherited from the parent. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value Sets the specified property as if the command .Nm zfs Cm set Ar property Ns = Ns Ar value -was invoked at the same time the dataset was created. Any editable ZFS property -can also be set at creation time. Multiple +was invoked at the same time the dataset was created. +Any editable ZFS property can also be set at creation time. +Multiple .Fl o -options can be specified. An error results if the same property is specified in -multiple +options can be specified. +An error results if the same property is specified in multiple .Fl o options. .It Fl p -Creates all the non-existing parent datasets. Datasets created in this manner -are automatically mounted according to the +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint -property inherited from their parent. Any property specified on the command line -using the +property inherited from their parent. +Any property specified on the command line using the .Fl o -option is ignored. If the target filesystem already exists, the operation -completes successfully. +option is ignored. +If the target filesystem already exists, the operation completes successfully. .El .It Xo .Nm @@ -1697,13 +1830,14 @@ completes successfully. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Fl V Ar size Ar volume .Xc -Creates a volume of the given size. The volume is exported as a block device in +Creates a volume of the given size. +The volume is exported as a block device in .Pa /dev/zvol/{dsk,rdsk}/path , where .Em path -is the name of the volume in the ZFS namespace. The size represents the logical -size as exported by the device. By default, a reservation of equal size is -created. +is the name of the volume in the ZFS namespace. +The size represents the logical size as exported by the device. +By default, a reservation of equal size is created. .Pp .Ar size is automatically rounded up to the nearest 128 Kbytes to ensure that the volume @@ -1719,24 +1853,26 @@ the resulting behavior is undefined. .It Fl o Ar property Ns = Ns Ar value Sets the specified property as if the .Nm zfs Cm set Ar property Ns = Ns Ar value -command was invoked at the same time the dataset was created. Any editable ZFS -property can also be set at creation time. Multiple +command was invoked at the same time the dataset was created. +Any editable ZFS property can also be set at creation time. +Multiple .Fl o -options can be specified. An error results if the same property is specified in -multiple +options can be specified. +An error results if the same property is specified in multiple .Fl o options. .It Fl p -Creates all the non-existing parent datasets. Datasets created in this manner -are automatically mounted according to the +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint -property inherited from their parent. Any property specified on the command line -using the +property inherited from their parent. +Any property specified on the command line using the .Fl o -option is ignored. If the target filesystem already exists, the operation -completes successfully. +option is ignored. +If the target filesystem already exists, the operation completes successfully. .It Fl s -Creates a sparse volume with no reservation. See +Creates a sparse volume with no reservation. +See .Sy volsize in the .Sx Native Properties @@ -1748,9 +1884,10 @@ section for more information about sparse volumes. .Op Fl Rfnprv .Ar filesystem Ns | Ns Ar volume .Xc -Destroys the given dataset. By default, the command unshares any file systems -that are currently shared, unmounts any file systems that are currently -mounted, and refuses to destroy a dataset that has active dependents +Destroys the given dataset. +By default, the command unshares any file systems that are currently shared, +unmounts any file systems that are currently mounted, and refuses to destroy a +dataset that has active dependents .Pq children or clones . .Bl -tag -width "-R" .It Fl R @@ -1759,12 +1896,14 @@ target hierarchy. .It Fl f Force an unmount of any file systems using the .Nm unmount Fl f -command. This option has no effect on non-file systems or unmounted file -systems. +command. +This option has no effect on non-file systems or unmounted file systems. .It Fl n Do a dry-run .Pq Qq No-op -deletion. No data will be deleted. This is useful in conjunction with the +deletion. +No data will be deleted. +This is useful in conjunction with the .Fl v or .Fl p @@ -1794,22 +1933,25 @@ The given snapshots are destroyed immediately if and only if the .Nm zfs Cm destroy command without the .Fl d -option would have destroyed it. Such immediate destruction would occur, for -example, if the snapshot had no clones and the user-initiated reference count -were zero. +option would have destroyed it. +Such immediate destruction would occur, for example, if the snapshot had no +clones and the user-initiated reference count were zero. .Pp If a snapshot does not qualify for immediate destruction, it is marked for -deferred deletion. In this state, it exists as a usable, visible snapshot until -both of the preconditions listed above are met, at which point it is destroyed. +deferred deletion. +In this state, it exists as a usable, visible snapshot until both of the +preconditions listed above are met, at which point it is destroyed. .Pp An inclusive range of snapshots may be specified by separating the first and -last snapshots with a percent sign. The first and/or last snapshots may be left -blank, in which case the filesystem's oldest or newest snapshot will be implied. +last snapshots with a percent sign. +The first and/or last snapshots may be left blank, in which case the +filesystem's oldest or newest snapshot will be implied. .Pp Multiple snapshots .Pq or ranges of snapshots of the same filesystem or volume may be specified in a comma-separated list of -snapshots. Only the snapshot's short name +snapshots. +Only the snapshot's short name .Po the part after the .Sy @ .Pc @@ -1818,7 +1960,8 @@ multiple snapshots. .Bl -tag -width "-R" .It Fl R Recursively destroy all clones of these snapshots, including the clones, -snapshots, and children. If this flag is specified, the +snapshots, and children. +If this flag is specified, the .Fl d flag will have no effect. .It Fl d @@ -1826,8 +1969,9 @@ Defer snapshot deletion. .It Fl n Do a dry-run .Pq Qq No-op -deletion. No data will be deleted. This is -useful in conjunction with the +deletion. +No data will be deleted. +This is useful in conjunction with the .Fl p or .Fl v @@ -1861,9 +2005,12 @@ The given bookmark is destroyed. .Oo Fl o Ar property Ns = Ns value Oc Ns ... .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... .Xc -Creates snapshots with the given names. All previous modifications by successful -system calls to the file system are part of the snapshots. Snapshots are taken -atomically, so that all snapshots correspond to the same moment in time. See the +Creates snapshots with the given names. +All previous modifications by successful system calls to the file system are +part of the snapshots. +Snapshots are taken atomically, so that all snapshots correspond to the same +moment in time. +See the .Sx Snapshots section for details. .Bl -tag -width "-o" @@ -1880,12 +2027,13 @@ Recursively create snapshots of all descendent datasets .Op Fl Rfr .Ar snapshot .Xc -Roll back the given dataset to a previous snapshot. When a dataset is rolled -back, all data that has changed since the snapshot is discarded, and the dataset -reverts to the state at the time of the snapshot. By default, the command -refuses to roll back to a snapshot other than the most recent one. In order to -do so, all intermediate snapshots and bookmarks must be destroyed by specifying -the +Roll back the given dataset to a previous snapshot. +When a dataset is rolled back, all data that has changed since the snapshot is +discarded, and the dataset reverts to the state at the time of the snapshot. +By default, the command refuses to roll back to a snapshot other than the most +recent one. +In order to do so, all intermediate snapshots and bookmarks must be destroyed by +specifying the .Fl r option. .Pp @@ -1893,8 +2041,9 @@ The .Fl rR options do not recursively destroy the child snapshots of a recursive snapshot. Only direct snapshots of the specified filesystem are destroyed by either of -these options. To completely roll back a recursive snapshot, you must rollback -the individual child snapshots. +these options. +To completely roll back a recursive snapshot, you must rollback the individual +child snapshots. .Bl -tag -width "-R" .It Fl R Destroy any more recent snapshots and bookmarks, as well as any clones of those @@ -1913,21 +2062,24 @@ Destroy any snapshots and bookmarks more recent than the one specified. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Ar snapshot Ar filesystem Ns | Ns Ar volume .Xc -Creates a clone of the given snapshot. See the +Creates a clone of the given snapshot. +See the .Sx Clones -section for details. The target dataset can be located anywhere in the ZFS -hierarchy, and is created as the same type as the original. +section for details. +The target dataset can be located anywhere in the ZFS hierarchy, and is created +as the same type as the original. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value Sets the specified property; see .Nm zfs Cm create for details. .It Fl p -Creates all the non-existing parent datasets. Datasets created in this manner -are automatically mounted according to the +Creates all the non-existing parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint -property inherited from their parent. If the target filesystem or volume already -exists, the operation completes successfully. +property inherited from their parent. +If the target filesystem or volume already exists, the operation completes +successfully. .El .It Xo .Nm @@ -1936,16 +2088,20 @@ exists, the operation completes successfully. .Xc Promotes a clone file system to no longer be dependent on its .Qq origin -snapshot. This makes it possible to destroy the file system that the clone was -created from. The clone parent-child dependency relationship is reversed, so -that the origin file system becomes a clone of the specified file system. +snapshot. +This makes it possible to destroy the file system that the clone was created +from. +The clone parent-child dependency relationship is reversed, so that the origin +file system becomes a clone of the specified file system. .Pp The snapshot that was cloned, and any snapshots previous to this snapshot, are -now owned by the promoted clone. The space they use moves from the origin file -system to the promoted clone, so enough space must be available to accommodate -these snapshots. No new space is consumed by this operation, but the space -accounting is adjusted. The promoted clone must not have any conflicting -snapshot names of its own. The +now owned by the promoted clone. +The space they use moves from the origin file system to the promoted clone, so +enough space must be available to accommodate these snapshots. +No new space is consumed by this operation, but the space accounting is +adjusted. +The promoted clone must not have any conflicting snapshot names of its own. +The .Cm rename subcommand can be used to rename any conflicting snapshots. .It Xo @@ -1961,18 +2117,20 @@ subcommand can be used to rename any conflicting snapshots. .Ar filesystem Ns | Ns Ar volume .Ar filesystem Ns | Ns Ar volume .Xc -Renames the given dataset. The new target can be located anywhere in the ZFS -hierarchy, with the exception of snapshots. Snapshots can only be renamed within -the parent file system or volume. When renaming a snapshot, the parent file -system of the snapshot does not need to be specified as part of the second -argument. Renamed file systems can inherit new mount points, in which case they -are unmounted and remounted at the new mount point. +Renames the given dataset. +The new target can be located anywhere in the ZFS hierarchy, with the exception +of snapshots. +Snapshots can only be renamed within the parent file system or volume. +When renaming a snapshot, the parent file system of the snapshot does not need +to be specified as part of the second argument. +Renamed file systems can inherit new mount points, in which case they are +unmounted and remounted at the new mount point. .Bl -tag -width "-a" .It Fl f Force unmount any filesystems that need to be unmounted in the process. .It Fl p -Creates all the nonexistent parent datasets. Datasets created in this manner are -automatically mounted according to the +Creates all the nonexistent parent datasets. +Datasets created in this manner are automatically mounted according to the .Sy mountpoint property inherited from their parent. .El @@ -1982,8 +2140,8 @@ property inherited from their parent. .Fl r .Ar snapshot Ar snapshot .Xc -Recursively rename the snapshots of all descendent datasets. Snapshots are the -only dataset that can be renamed recursively. +Recursively rename the snapshots of all descendent datasets. +Snapshots are the only dataset that can be renamed recursively. .It Xo .Nm .Cm list @@ -1995,9 +2153,10 @@ only dataset that can be renamed recursively. .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... .Xc -Lists the property information for the given datasets in tabular form. If -specified, you can list property information by the absolute pathname or the -relative pathname. By default, all file systems and volumes are displayed. +Lists the property information for the given datasets in tabular form. +If specified, you can list property information by the absolute pathname or the +relative pathname. +By default, all file systems and volumes are displayed. Snapshots are displayed if the .Sy listsnaps property is @@ -2010,8 +2169,9 @@ The following fields are displayed, .Sy mountpoint . .Bl -tag -width "-H" .It Fl H -Used for scripting mode. Do not print headers and separate fields by a single -tab instead of arbitrary white space. +Used for scripting mode. +Do not print headers and separate fields by a single tab instead of arbitrary +white space. .It Fl S Ar property Same as the .Fl s @@ -2025,7 +2185,8 @@ of .Sy 1 will display only the dataset and its direct children. .It Fl o Ar property -A comma-separated list of properties to display. The property must be: +A comma-separated list of properties to display. +The property must be: .Bl -bullet .It One of the properties described in the @@ -2040,8 +2201,8 @@ to display the dataset name .It The value .Sy space -to display space usage properties on file systems and volumes. This is a -shortcut for specifying +to display space usage properties on file systems and volumes. +This is a shortcut for specifying .Fl o Sy name Ns , Ns Sy avail Ns , Ns Sy used Ns , Ns Sy usedsnap Ns , Ns .Sy usedds Ns , Ns Sy usedrefreserv Ns , Ns Sy usedchild Fl t .Sy filesystem Ns , Ns Sy volume @@ -2055,18 +2216,19 @@ values. Recursively display any children of the dataset on the command line. .It Fl s Ar property A property for sorting the output by column in ascending order based on the -value of the property. The property must be one of the properties described in -the +value of the property. +The property must be one of the properties described in the .Sx Properties section, or the special value .Sy name -to sort by the dataset name. Multiple properties can be specified at one time -using multiple +to sort by the dataset name. +Multiple properties can be specified at one time using multiple .Fl s -property options. Multiple +property options. +Multiple .Fl s -options are evaluated from left to right in decreasing order of importance. The -following is a list of sorting criteria: +options are evaluated from left to right in decreasing order of importance. +The following is a list of sorting criteria: .Bl -bullet .It Numeric types sort in numeric order. @@ -2101,16 +2263,19 @@ displays only snapshots. .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... .Xc Sets the property or list of properties to the given value(s) for each dataset. -Only some properties can be edited. See the +Only some properties can be edited. +See the .Sx Properties section for more information on what properties can be set and acceptable -values. Numeric values can be specified as exact values, or in a human-readable -form with a suffix of +values. +Numeric values can be specified as exact values, or in a human-readable form +with a suffix of .Sy B , K , M , G , T , P , E , Z .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or zettabytes, respectively .Pc . -User properties can be set on snapshots. For more information, see the +User properties can be set on snapshots. +For more information, see the .Sx User Properties section. .It Xo @@ -2124,21 +2289,22 @@ section. .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... .Xc -Displays properties for the given datasets. If no datasets are specified, then -the command displays properties for all datasets on the system. For each -property, the following columns are displayed: +Displays properties for the given datasets. +If no datasets are specified, then the command displays properties for all +datasets on the system. +For each property, the following columns are displayed: .Bd -literal name Dataset name property Property name value Property value - source Property source. Can either be local, default, + source Property source. Can either be local, default, temporary, inherited, or none (-). .Ed .Pp All columns are displayed by default, though this can be controlled by using the .Fl o -option. This command takes a comma-separated list of properties as described in -the +option. +This command takes a comma-separated list of properties as described in the .Sx Native Properties and .Sx User Properties @@ -2150,9 +2316,9 @@ can be used to display all properties that apply to the given dataset's type .Pq filesystem, volume, snapshot, or bookmark . .Bl -tag -width "-H" .It Fl H -Display output in a form more easily parsed by scripts. Any headers are omitted, -and fields are explicitly separated by a single tab instead of an arbitrary -amount of space. +Display output in a form more easily parsed by scripts. +Any headers are omitted, and fields are explicitly separated by a single tab +instead of an arbitrary amount of space. .It Fl d Ar depth Recursively display any children of the dataset, limiting the recursion to .Ar depth . @@ -2170,9 +2336,9 @@ values. .It Fl r Recursively display properties for any children. .It Fl s Ar source -A comma-separated list of sources to display. Those properties coming from a -source other than those in this list are ignored. Each source must be one of the -following: +A comma-separated list of sources to display. +Those properties coming from a source other than those in this list are ignored. +Each source must be one of the following: .Sy local , .Sy default , .Sy inherited , @@ -2200,7 +2366,8 @@ or Clears the specified property, causing it to be inherited from an ancestor, restored to default if no ancestor has the property set, or with the .Fl S -option reverted to the received value if one exists. See the +option reverted to the received value if one exists. +See the .Sx Properties section for a listing of default values, and details on which properties can be inherited. @@ -2231,28 +2398,31 @@ Displays a list of currently supported file system versions. .Op Fl V Ar version .Fl a | Ar filesystem .Xc -Upgrades file systems to a new on-disk version. Once this is done, the file -systems will no longer be accessible on systems running older versions of the -software. +Upgrades file systems to a new on-disk version. +Once this is done, the file systems will no longer be accessible on systems +running older versions of the software. .Nm zfs Cm send streams generated from new snapshots of these file systems cannot be accessed on systems running older versions of the software. .Pp -In general, the file system version is independent of the pool version. See +In general, the file system version is independent of the pool version. +See .Xr zpool 1M for information on the .Nm zpool Cm upgrade command. .Pp In some cases, the file system version and the pool version are interrelated and -the pool version must be upgraded before the file system version can be upgraded. +the pool version must be upgraded before the file system version can be +upgraded. .Bl -tag -width "-V" .It Fl V Ar version Upgrade to the specified .Ar version . If the .Fl V -flag is not specified, this command upgrades to the most recent version. This +flag is not specified, this command upgrades to the most recent version. +This option can only be used to increase the version number, and only up to the most recent version supported by this software. .It Fl a @@ -2273,7 +2443,8 @@ Upgrade the specified file system and all descendent file systems. .Ar filesystem Ns | Ns Ar snapshot .Xc Displays space consumed by, and quotas on, each user in the specified filesystem -or snapshot. This corresponds to the +or snapshot. +This corresponds to the .Sy userused@ Ns Em user and .Sy userquota@ Ns Em user @@ -2282,10 +2453,12 @@ properties. .It Fl H Do not print headers, use tab-delimited output. .It Fl S Ar field -Sort by this field in reverse order. See +Sort by this field in reverse order. +See .Fl s . .It Fl i -Translate SID to POSIX ID. The POSIX ID may be ephemeral if no mapping exists. +Translate SID to POSIX ID. +The POSIX ID may be ephemeral if no mapping exists. Normal POSIX interfaces .Po for example, .Xr stat 2 , @@ -2295,11 +2468,14 @@ perform this translation, so the .Fl i option allows the output from .Nm zfs Cm userspace -to be compared directly with those utilities. However, +to be compared directly with those utilities. +However, .Fl i may lead to confusion if some files were created by an SMB user before a -SMB-to-POSIX name mapping was established. In such a case, some files will be -owned by the SMB entity and some by the POSIX entity. However, the +SMB-to-POSIX name mapping was established. +In such a case, some files will be owned by the SMB entity and some by the POSIX +entity. +However, the .Fl i option will report that the POSIX entity has the total usage and quota for both. .It Fl n @@ -2316,12 +2492,14 @@ Use exact .Pq parsable numeric output. .It Fl s Ar field -Sort output by this field. The +Sort output by this field. +The .Fl s and .Fl S flags may be specified multiple times to sort first by one field, then by -another. The default is +another. +The default is .Fl s Sy type Fl s Sy name . .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Print only the specified types from the following set: @@ -2345,7 +2523,8 @@ The default can be changed to include group types. .Ar filesystem Ns | Ns Ar snapshot .Xc Displays space consumed by, and quotas on, each group in the specified -filesystem or snapshot. This subcommand is identical to +filesystem or snapshot. +This subcommand is identical to .Nm zfs Cm userspace , except that the default types to display are .Fl t Sy posixgroup Ns , Ns Sy smbgroup . @@ -2364,17 +2543,19 @@ Displays all ZFS file systems currently mounted. Mounts ZFS file systems. .Bl -tag -width "-O" .It Fl O -Perform an overlay mount. See +Perform an overlay mount. +See .Xr mount 1M for more information. .It Fl a -Mount all available ZFS file systems. Invoked automatically as part of the boot -process. +Mount all available ZFS file systems. +Invoked automatically as part of the boot process. .It Ar filesystem Mount the specified filesystem. .It Fl o Ar options An optional, comma-separated list of mount options to use temporarily for the -duration of the mount. See the +duration of the mount. +See the .Sx Temporary Mount Point Properties section for details. .It Fl v @@ -2389,11 +2570,12 @@ Report mount progress. Unmounts currently mounted ZFS file systems. .Bl -tag -width "-a" .It Fl a -Unmount all available ZFS file systems. Invoked automatically as part of the -shutdown process. +Unmount all available ZFS file systems. +Invoked automatically as part of the shutdown process. .It Ar filesystem Ns | Ns Ar mountpoint -Unmount the specified filesystem. The command can also be given a path to a ZFS -file system mount point on the system. +Unmount the specified filesystem. +The command can also be given a path to a ZFS file system mount point on the +system. .It Fl f Forcefully unmount the file system, even if it is currently in use. .El @@ -2405,14 +2587,15 @@ Forcefully unmount the file system, even if it is currently in use. Shares available ZFS file systems. .Bl -tag -width "-a" .It Fl a -Share all available ZFS file systems. Invoked automatically as part of the boot -process. +Share all available ZFS file systems. +Invoked automatically as part of the boot process. .It Ar filesystem Share the specified filesystem according to the .Sy sharenfs and .Sy sharesmb -properties. File systems are shared when the +properties. +File systems are shared when the .Sy sharenfs or .Sy sharesmb @@ -2426,23 +2609,25 @@ property is set. Unshares currently shared ZFS file systems. .Bl -tag -width "-a" .It Fl a -Unshare all available ZFS file systems. Invoked automatically as part of the -shutdown process. +Unshare all available ZFS file systems. +Invoked automatically as part of the shutdown process. .It Ar filesystem Ns | Ns Ar mountpoint -Unshare the specified filesystem. The command can also be given a path to a ZFS -file system shared on the system. +Unshare the specified filesystem. +The command can also be given a path to a ZFS file system shared on the system. .El .It Xo .Nm .Cm bookmark .Ar snapshot bookmark .Xc -Creates a bookmark of the given snapshot. Bookmarks mark the point in time when -the snapshot was created, and can be used as the incremental source for a +Creates a bookmark of the given snapshot. +Bookmarks mark the point in time when the snapshot was created, and can be used +as the incremental source for a .Nm zfs Cm send command. .Pp -This feature must be enabled to be used. See +This feature must be enabled to be used. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy bookmarks @@ -2456,18 +2641,20 @@ feature. .Xc Creates a stream representation of the second .Ar snapshot , -which is written to standard output. The output can be redirected to a file or -to a different system +which is written to standard output. +The output can be redirected to a file or to a different system .Po for example, using .Xr ssh 1 .Pc . By default, a full stream is generated. .Bl -tag -width "-D" .It Fl D, -dedup -Generate a deduplicated stream. Blocks which would have been sent multiple times -in the send stream will only be sent once. The receiving system must also -support this feature to receive a deduplicated stream. This flag can be used -regardless of the dataset's +Generate a deduplicated stream. +Blocks which would have been sent multiple times in the send stream will only be +sent once. +The receiving system must also support this feature to receive a deduplicated +stream. +This flag can be used regardless of the dataset's .Sy dedup property, but performance will be much better if the filesystem uses a dedup-capable checksum @@ -2476,7 +2663,8 @@ dedup-capable checksum .Pc . .It Fl I Ar snapshot Generate a stream package that sends all intermediary snapshots from the first -snapshot to the second snapshot. For example, +snapshot to the second snapshot. +For example, .Fl I Em @a Em fs@d is similar to .Fl i Em @a Em fs@b Ns ; Fl i Em @b Em fs@c Ns ; Fl i Em @c Em fs@d . @@ -2484,15 +2672,16 @@ The incremental source may be specified as with the .Fl i option. .It Fl L, -large-block -Generate a stream which may contain blocks larger than 128KB. This flag has no -effect if the +Generate a stream which may contain blocks larger than 128KB. +This flag has no effect if the .Sy large_blocks pool feature is disabled, or if the .Sy recordsize -property of this filesystem has never been set above 128KB. The receiving system -must have the +property of this filesystem has never been set above 128KB. +The receiving system must have the .Sy large_blocks -pool feature enabled as well. See +pool feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy large_blocks @@ -2501,9 +2690,9 @@ feature. Print machine-parsable verbose information about the stream package generated. .It Fl R, -replicate Generate a replication stream package, which will replicate the specified -file system, and all descendent file systems, up to the named snapshot. When -received, all properties, snapshots, descendent file systems, and clones are -preserved. +file system, and all descendent file systems, up to the named snapshot. +When received, all properties, snapshots, descendent file systems, and clones +are preserved. .Pp If the .Fl i @@ -2511,9 +2700,10 @@ or .Fl I flags are used in conjunction with the .Fl R -flag, an incremental replication stream is generated. The current values of -properties, and current snapshot and file system names are set when the stream -is received. If the +flag, an incremental replication stream is generated. +The current values of properties, and current snapshot and file system names are +set when the stream is received. +If the .Fl F flag is specified when this stream is received, snapshots and file systems that do not exist on the sending side are destroyed. @@ -2522,28 +2712,41 @@ Generate a more compact stream by using .Sy WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the .Sy embedded_data -pool feature. This flag has no effect if the +pool feature. +This flag has no effect if the .Sy embedded_data -feature is disabled. The receiving system must have the +feature is disabled. +The receiving system must have the .Sy embedded_data -feature enabled. If the +feature enabled. +If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have -that feature enabled as well. See +that feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy embedded_data feature. .It Fl c, -compressed Generate a more compact stream by using compressed WRITE records for blocks -which are compressed on disk and in memory (see the -.Sy compression No property for details). If the Sy lz4_compress No feature -is active on the sending system, then the receiving system must have that -feature enabled as well. If the -.Sy large_blocks No feature is enabled on the sending system but the Fl L +which are compressed on disk and in memory +.Po see the +.Sy compression +property for details +.Pc . +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +If the +.Sy large_blocks +feature is enabled on the sending system but the +.Fl L option is not supplied in conjunction with -.Fl c, No then the data will be decompressed before sending so it can be split -into smaller block sizes. +.Fl c , +then the data will be decompressed before sending so it can be split into +smaller block sizes. .It Fl i Ar snapshot Generate an incremental stream from the first .Ar snapshot @@ -2569,26 +2772,29 @@ not just .It Fl n, -dryrun Do a dry-run .Pq Qq No-op -send. Do not generate any actual send data. This is useful in conjunction with -the +send. +Do not generate any actual send data. +This is useful in conjunction with the .Fl v or .Fl P -flags to determine what data will be sent. In this case, the verbose output will -be written to standard output +flags to determine what data will be sent. +In this case, the verbose output will be written to standard output .Po contrast with a non-dry-run, where the stream is written to standard output and the verbose output goes to standard error .Pc . .It Fl p, -props -Include the dataset's properties in the stream. This flag is implicit when +Include the dataset's properties in the stream. +This flag is implicit when .Fl R -is specified. The receiving system must also support this feature. +is specified. +The receiving system must also support this feature. .It Fl v, -verbose -Print verbose information about the stream package generated. This information -includes a per-second report of how much data has been sent. +Print verbose information about the stream package generated. +This information includes a per-second report of how much data has been sent. .Pp -The format of the stream is committed. You will be able to receive your streams -on future versions of ZFS . +The format of the stream is committed. +You will be able to receive your streams on future versions of ZFS . .El .It Xo .Nm @@ -2598,57 +2804,73 @@ on future versions of ZFS . .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Xc Generate a send stream, which may be of a filesystem, and may be incremental -from a bookmark. If the destination is a filesystem or volume, the pool must be -read-only, or the filesystem must not be mounted. When the stream generated from -a filesystem or volume is received, the default snapshot name will be +from a bookmark. +If the destination is a filesystem or volume, the pool must be read-only, or the +filesystem must not be mounted. +When the stream generated from a filesystem or volume is received, the default +snapshot name will be .Qq --head-- . .Bl -tag -width "-L" .It Fl L, -large-block -Generate a stream which may contain blocks larger than 128KB. This flag has no -effect if the +Generate a stream which may contain blocks larger than 128KB. +This flag has no effect if the .Sy large_blocks pool feature is disabled, or if the .Sy recordsize -property of this filesystem has never been set above 128KB. The receiving system -must have the +property of this filesystem has never been set above 128KB. +The receiving system must have the .Sy large_blocks -pool feature enabled as well. See +pool feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy large_blocks feature. .It Fl c, -compressed Generate a more compact stream by using compressed WRITE records for blocks -which are compressed on disk and in memory (see the -.Sy compression No property for details). If the Sy lz4_compress No feature is -active on the sending system, then the receiving system must have that feature -enabled as well. If the -.Sy large_blocks No feature is enabled on the sending system but the Fl L +which are compressed on disk and in memory +.Po see the +.Sy compression +property for details +.Pc . +If the +.Sy lz4_compress +feature is active on the sending system, then the receiving system must have +that feature enabled as well. +If the +.Sy large_blocks +feature is enabled on the sending system but the +.Fl L option is not supplied in conjunction with -.Fl c, No then the data will be decompressed before sending so it can be split -into smaller block sizes. +.Fl c , +then the data will be decompressed before sending so it can be split into +smaller block sizes. .It Fl e, -embed Generate a more compact stream by using .Sy WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the .Sy embedded_data -pool feature. This flag has no effect if the +pool feature. +This flag has no effect if the .Sy embedded_data -feature is disabled. The receiving system must have the +feature is disabled. +The receiving system must have the .Sy embedded_data -feature enabled. If the +feature enabled. +If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have -that feature enabled as well. See +that feature enabled as well. +See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy embedded_data feature. .It Fl i Ar snapshot Ns | Ns Ar bookmark -Generate an incremental send stream. The incremental source must be an earlier -snapshot in the destination's history. It will commonly be an earlier snapshot -in the destination's file system, in which case it can be specified as the last -component of the name +Generate an incremental send stream. +The incremental source must be an earlier snapshot in the destination's history. +It will commonly be an earlier snapshot in the destination's file system, in +which case it can be specified as the last component of the name .Po the .Sy # or @@ -2667,10 +2889,12 @@ origin, etc. .Fl t .Ar receive_resume_token .Xc -Creates a send stream which resumes an interrupted receive. The +Creates a send stream which resumes an interrupted receive. +The .Ar receive_resume_token -is the value of this property on the filesystem -or volume that was being received into. See the documentation for +is the value of this property on the filesystem or volume that was being +received into. +See the documentation for .Sy zfs receive -s for more details. .It Xo @@ -2688,8 +2912,9 @@ for more details. .Ar filesystem .Xc Creates a snapshot whose contents are as specified in the stream provided on -standard input. If a full stream is received, then a new file system is created -as well. Streams are created using the +standard input. +If a full stream is received, then a new file system is created as well. +Streams are created using the .Nm zfs Cm send subcommand, which by default creates a full stream. .Nm zfs Cm recv @@ -2698,7 +2923,8 @@ can be used as an alias for .Pp If an incremental stream is received, then the destination file system must already exist, and its most recent snapshot must match the incremental stream's -source. For +source. +For .Sy zvols , the destination device link is destroyed and recreated, which means the .Sy zvol @@ -2723,8 +2949,9 @@ options. .Pp If the argument is a snapshot name, the specified .Ar snapshot -is created. If the argument is a file system or volume name, a snapshot with the -same name as the sent snapshot is created within the specified +is created. +If the argument is a file system or volume name, a snapshot with the same name +as the sent snapshot is created within the specified .Ar filesystem or .Ar volume . @@ -2748,7 +2975,8 @@ option is specified, all but the first element of the sent snapshot's file system path .Pq usually the pool name is used and any required intermediate file systems within the specified one are -created. If the +created. +If the .Fl e option is specified, then only the last element of the sent snapshot's file system name @@ -2757,7 +2985,8 @@ is used as the target file system name. .Bl -tag -width "-F" .It Fl F Force a rollback of the file system to the most recent snapshot before -performing the receive operation. If receiving an incremental replication stream +performing the receive operation. +If receiving an incremental replication stream .Po for example, one generated by .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I .Pc , @@ -2771,16 +3000,18 @@ Discard all but the last element of the sent snapshot's file system name, using that element to determine the name of the target file system for the new snapshot as described in the paragraph above. .It Fl n -Do not actually receive the stream. This can be useful in conjunction with the +Do not actually receive the stream. +This can be useful in conjunction with the .Fl v option to verify the name the receive operation would use. .It Fl o Sy origin Ns = Ns Ar snapshot Forces the stream to be received as a clone of the given snapshot. If the stream is a full send stream, this will create the filesystem -described by the stream as a clone of the specified snapshot. Which -snapshot was specified will not affect the success or failure of the -receive, as long as the snapshot does exist. If the stream is an -incremental send stream, all the normal verification will be performed. +described by the stream as a clone of the specified snapshot. +Which snapshot was specified will not affect the success or failure of the +receive, as long as the snapshot does exist. +If the stream is an incremental send stream, all the normal verification will be +performed. .It Fl u File system that is associated with the received stream is not mounted. .It Fl v @@ -2788,8 +3019,8 @@ Print verbose information about the stream and the time required to perform the receive operation. .It Fl s If the receive is interrupted, save the partially received state, rather -than deleting it. Interruption may be due to premature termination of -the stream +than deleting it. +Interruption may be due to premature termination of the stream .Po e.g. due to network failure or failure of the remote system if the stream is being read over a network connection .Pc , @@ -2807,7 +3038,8 @@ property of the filesystem or volume which is received into. .Pp To use this flag, the storage pool must have the .Sy extensible_dataset -feature enabled. See +feature enabled. +See .Xr zpool-features 5 for details on ZFS feature flags. .El @@ -2826,7 +3058,8 @@ deleting its saved partially received state. .Ar filesystem Ns | Ns Ar volume .Xc Displays permissions that have been delegated on the specified filesystem or -volume. See the other forms of +volume. +See the other forms of .Nm zfs Cm allow for more information. .It Xo @@ -2862,32 +3095,36 @@ only for the specified file system. .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... Explicitly specify that permissions are delegated to the user. .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... -Specifies to whom the permissions are delegated. Multiple entities can be -specified as a comma-separated list. If neither of the +Specifies to whom the permissions are delegated. +Multiple entities can be specified as a comma-separated list. +If neither of the .Fl gu options are specified, then the argument is interpreted preferentially as the keyword .Sy everyone , -then as a user name, and lastly as a group name. To specify a user or group -named +then as a user name, and lastly as a group name. +To specify a user or group named .Qq everyone , use the .Fl g or .Fl u -options. To specify a group with the same name as a user, use the +options. +To specify a group with the same name as a user, use the .Fl g options. .It Xo .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns .Ar setname Oc Ns ... .Xc -The permissions to delegate. Multiple permissions may be specified as a -comma-separated list. Permission names are the same as ZFS subcommand and -property names. See the property list below. Property set names, -which begin with +The permissions to delegate. +Multiple permissions may be specified as a comma-separated list. +Permission names are the same as ZFS subcommand and property names. +See the property list below. +Property set names, which begin with .Sy @ , -may be specified. See the +may be specified. +See the .Fl s form below for details. .El @@ -2898,7 +3135,8 @@ options are specified, or both are, then the permissions are allowed for the file system or volume, and all of its descendents. .Pp Permissions are generally the ability to use a ZFS subcommand or change a ZFS -property. The following permissions are available: +property. +The following permissions are available: .Bd -literal NAME TYPE NOTES allow subcommand Must also have the permission that is being @@ -2973,7 +3211,8 @@ zoned property .Xc Sets .Qq create time -permissions. These permissions are granted +permissions. +These permissions are granted .Pq locally to the creator of any newly-created descendent file system. .It Xo @@ -2984,12 +3223,13 @@ to the creator of any newly-created descendent file system. .Ar setname Oc Ns ... .Ar filesystem Ns | Ns Ar volume .Xc -Defines or adds permissions to a permission set. The set can be used by other +Defines or adds permissions to a permission set. +The set can be used by other .Nm zfs Cm allow -commands for the specified file system and its descendents. Sets are evaluated -dynamically, so changes to a set are immediately reflected. Permission sets -follow the same naming restrictions as ZFS file systems, but the name must begin -with +commands for the specified file system and its descendents. +Sets are evaluated dynamically, so changes to a set are immediately reflected. +Permission sets follow the same naming restrictions as ZFS file systems, but the +name must begin with .Sy @ , and can be no more than 64 characters long. .It Xo @@ -3019,21 +3259,25 @@ and can be no more than 64 characters long. .Xc Removes permissions that were granted with the .Nm zfs Cm allow -command. No permissions are explicitly denied, so other permissions granted are -still in effect. For example, if the permission is granted by an ancestor. If no -permissions are specified, then all permissions for the specified +command. +No permissions are explicitly denied, so other permissions granted are still in +effect. +For example, if the permission is granted by an ancestor. +If no permissions are specified, then all permissions for the specified .Ar user , .Ar group , or .Sy everyone -are removed. Specifying +are removed. +Specifying .Sy everyone .Po or using the .Fl e option .Pc only removes the permissions that were granted to everyone, not all permissions -for every user and group. See the +for every user and group. +See the .Nm zfs Cm allow command for a description of the .Fl ldugec @@ -3051,8 +3295,9 @@ Recursively remove the permissions from this file system and all descendents. .Ar setname Oc Ns ... Oc .Ar filesystem Ns | Ns Ar volume .Xc -Removes permissions from a permission set. If no permissions are specified, then -all permissions are removed, thus removing the set entirely. +Removes permissions from a permission set. +If no permissions are specified, then all permissions are removed, thus removing +the set entirely. .It Xo .Nm .Cm hold @@ -3061,8 +3306,9 @@ all permissions are removed, thus removing the set entirely. .Xc Adds a single reference, named with the .Ar tag -argument, to the specified snapshot or snapshots. Each snapshot has its own tag -namespace, and tags must be unique within that space. +argument, to the specified snapshot or snapshots. +Each snapshot has its own tag namespace, and tags must be unique within that +space. .Pp If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy @@ -3093,9 +3339,9 @@ listing the holds on the named snapshot. .Xc Removes a single reference, named with the .Ar tag -argument, from the specified snapshot or snapshots. The tag must already exist -for each snapshot. If a hold exists on a snapshot, attempts to destroy that -snapshot by using the +argument, from the specified snapshot or snapshots. +The tag must already exist for each snapshot. +If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy command return .Er EBUSY . @@ -3112,11 +3358,12 @@ descendent file systems. .Xc Display the difference between a snapshot of a given filesystem and another snapshot of that filesystem from a later time or the current contents of the -filesystem. The first column is a character indicating the type of change, the -other columns indicate pathname, new pathname +filesystem. +The first column is a character indicating the type of change, the other columns +indicate pathname, new pathname .Pq in case of rename , -change in link count, and optionally file type and/or change time. The types of -change are: +change in link count, and optionally file type and/or change time. +The types of change are: .Bd -literal - The path has been removed + The path has been created @@ -3184,11 +3431,11 @@ The following command creates snapshots named .Sy yesterday of .Em pool/home -and all of its descendent file systems. Each snapshot is mounted on demand in -the +and all of its descendent file systems. +Each snapshot is mounted on demand in the .Pa .zfs/snapshot -directory at the root of its file system. The second command destroys the newly -created snapshots. +directory at the root of its file system. +The second command destroys the newly created snapshots. .Bd -literal # zfs snapshot -r pool/home@yesterday # zfs destroy -r pool/home@yesterday @@ -3382,9 +3629,9 @@ property for a dataset. .Ed .It Sy Example 15 No Performing a Rolling Snapshot The following example shows how to maintain a history of snapshots with a -consistent naming scheme. To keep a week's worth of snapshots, the user -destroys the oldest snapshot, renames the remaining snapshots, and then creates -a new snapshot, as follows: +consistent naming scheme. +To keep a week's worth of snapshots, the user destroys the oldest snapshot, +renames the remaining snapshots, and then creates a new snapshot, as follows: .Bd -literal # zfs destroy -r pool/users@7daysago # zfs rename -r pool/users@6daysago @7daysago @@ -3447,7 +3694,8 @@ The following example shows how to grant anyone in the group to create file systems in .Em tank/users . This syntax also allows staff members to destroy their own file systems, but not -destroy anyone else's file system. The permissions on +destroy anyone else's file system. +The permissions on .Em tank/users are also displayed. .Bd -literal @@ -3463,7 +3711,8 @@ Local+Descendent permissions: .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset The following example shows how to define and grant a permission set on the .Em tank/users -file system. The permissions on +file system. +The permissions on .Em tank/users are also displayed. .Bd -literal @@ -3480,7 +3729,8 @@ Local+Descendent permissions: The following example shows to grant the ability to set quotas and reservations on the .Em users/home -file system. The permissions on +file system. +The permissions on .Em users/home are also displayed. .Bd -literal @@ -3499,7 +3749,8 @@ The following example shows how to remove the snapshot permission from the .Sy staff group on the .Em tank/users -file system. The permissions on +file system. +The permissions on .Em tank/users are also displayed. .Bd -literal @@ -3513,7 +3764,8 @@ Local+Descendent permissions: .Ed .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset The following example shows how to see what has changed between a prior -snapshot of a ZFS dataset and its current state. The +snapshot of a ZFS dataset and its current state. +The .Fl F option is used to indicate type information for the files affected. .Bd -literal diff --git a/usr/src/man/man1m/zpool.1m b/usr/src/man/man1m/zpool.1m index ed2e98b68f..7ec16df3aa 100644 --- a/usr/src/man/man1m/zpool.1m +++ b/usr/src/man/man1m/zpool.1m @@ -168,22 +168,24 @@ .Sh DESCRIPTION The .Nm -command configures ZFS storage pools. A storage pool is a collection of devices -that provides physical storage and data replication for ZFS datasets. All -datasets within a storage pool share the same space. See +command configures ZFS storage pools. +A storage pool is a collection of devices that provides physical storage and +data replication for ZFS datasets. +All datasets within a storage pool share the same space. +See .Xr zfs 1M for information on managing datasets. .Ss Virtual Devices (vdevs) A "virtual device" describes a single device or a collection of devices -organized according to certain performance and fault characteristics. The -following virtual devices are supported: +organized according to certain performance and fault characteristics. +The following virtual devices are supported: .Bl -tag -width Ds .It Sy disk A block device, typically located under .Pa /dev/dsk . ZFS can use individual slices or partitions, though the recommended mode of -operation is to use whole disks. A disk can be specified by a full path, or it -can be a shorthand name +operation is to use whole disks. +A disk can be specified by a full path, or it can be a shorthand name .Po the relative portion of the path under .Pa /dev/dsk .Pc . @@ -194,15 +196,16 @@ is equivalent to .Pa /dev/dsk/c0t0d0s2 . When given a whole disk, ZFS automatically labels the disk, if necessary. .It Sy file -A regular file. The use of files as a backing store is strongly discouraged. It -is designed primarily for experimental purposes, as the fault tolerance of a -file is only as good as the file system of which it is a part. A file must be -specified by a full path. +A regular file. +The use of files as a backing store is strongly discouraged. +It is designed primarily for experimental purposes, as the fault tolerance of a +file is only as good as the file system of which it is a part. +A file must be specified by a full path. .It Sy mirror -A mirror of two or more devices. Data is replicated in an identical fashion -across all components of a mirror. A mirror with N disks of size X can hold X -bytes and can withstand (N-1) devices failing before data integrity is -compromised. +A mirror of two or more devices. +Data is replicated in an identical fashion across all components of a mirror. +A mirror with N disks of size X can hold X bytes and can withstand (N-1) devices +failing before data integrity is compromised. .It Sy raidz , raidz1 , raidz2 , raidz3 A variation on RAID-5 that allows for better distribution of parity and eliminates the RAID-5 @@ -212,43 +215,50 @@ Data and parity is striped across all disks within a raidz group. .Pp A raidz group can have single-, double-, or triple-parity, meaning that the raidz group can sustain one, two, or three failures, respectively, without -losing any data. The +losing any data. +The .Sy raidz1 vdev type specifies a single-parity raidz group; the .Sy raidz2 vdev type specifies a double-parity raidz group; and the .Sy raidz3 -vdev type specifies a triple-parity raidz group. The +vdev type specifies a triple-parity raidz group. +The .Sy raidz vdev type is an alias for .Sy raidz1 . .Pp A raidz group with N disks of size X with P parity disks can hold approximately (N-P)*X bytes and can withstand P device(s) failing before data integrity is -compromised. The minimum number of devices in a raidz group is one more than -the number of parity disks. The recommended number is between 3 and 9 to help -increase performance. +compromised. +The minimum number of devices in a raidz group is one more than the number of +parity disks. +The recommended number is between 3 and 9 to help increase performance. .It Sy spare -A special pseudo-vdev which keeps track of available hot spares for a pool. For -more information, see the +A special pseudo-vdev which keeps track of available hot spares for a pool. +For more information, see the .Sx Hot Spares section. .It Sy log -A separate intent log device. If more than one log device is specified, then -writes are load-balanced between devices. Log devices can be mirrored. However, -raidz vdev types are not supported for the intent log. For more information, -see the +A separate intent log device. +If more than one log device is specified, then writes are load-balanced between +devices. +Log devices can be mirrored. +However, raidz vdev types are not supported for the intent log. +For more information, see the .Sx Intent Log section. .It Sy cache -A device used to cache storage pool data. A cache device cannot be configured -as a mirror or raidz group. For more information, see the +A device used to cache storage pool data. +A cache device cannot be configured as a mirror or raidz group. +For more information, see the .Sx Cache Devices section. .El .Pp Virtual devices cannot be nested, so a mirror or raidz virtual device can only -contain files or disks. Mirrors of mirrors +contain files or disks. +Mirrors of mirrors .Pq or other combinations are not allowed. .Pp @@ -257,68 +267,72 @@ A pool can have any number of virtual devices at the top of the configuration .Qq root vdevs .Pc . Data is dynamically distributed across all top-level devices to balance data -among devices. As new virtual devices are added, ZFS automatically places data -on the newly available devices. +among devices. +As new virtual devices are added, ZFS automatically places data on the newly +available devices. .Pp Virtual devices are specified one at a time on the command line, separated by -whitespace. The keywords +whitespace. +The keywords .Sy mirror and .Sy raidz -are used to distinguish where a group ends and another begins. For example, -the following creates two root vdevs, each a mirror of two disks: +are used to distinguish where a group ends and another begins. +For example, the following creates two root vdevs, each a mirror of two disks: .Bd -literal # zpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0 .Ed .Ss Device Failure and Recovery ZFS supports a rich set of mechanisms for handling device failure and data -corruption. All metadata and data is checksummed, and ZFS automatically repairs -bad data from a good copy when corruption is detected. +corruption. +All metadata and data is checksummed, and ZFS automatically repairs bad data +from a good copy when corruption is detected. .Pp In order to take advantage of these features, a pool must make use of some form -of redundancy, using either mirrored or raidz groups. While ZFS supports -running in a non-redundant configuration, where each root vdev is simply a disk -or file, this is strongly discouraged. A single case of bit corruption can -render some or all of your data unavailable. +of redundancy, using either mirrored or raidz groups. +While ZFS supports running in a non-redundant configuration, where each root +vdev is simply a disk or file, this is strongly discouraged. +A single case of bit corruption can render some or all of your data unavailable. .Pp A pool's health status is described by one of three states: online, degraded, -or faulted. An online pool has all devices operating normally. A degraded pool -is one in which one or more devices have failed, but the data is still -available due to a redundant configuration. A faulted pool has corrupted -metadata, or one or more faulted devices, and insufficient replicas to continue -functioning. +or faulted. +An online pool has all devices operating normally. +A degraded pool is one in which one or more devices have failed, but the data is +still available due to a redundant configuration. +A faulted pool has corrupted metadata, or one or more faulted devices, and +insufficient replicas to continue functioning. .Pp The health of the top-level vdev, such as mirror or raidz device, is potentially impacted by the state of its associated vdevs, or component -devices. A top-level vdev or component device is in one of the following -states: +devices. +A top-level vdev or component device is in one of the following states: .Bl -tag -width "DEGRADED" .It Sy DEGRADED One or more top-level vdevs is in the degraded state because one or more -component devices are offline. Sufficient replicas exist to continue -functioning. +component devices are offline. +Sufficient replicas exist to continue functioning. .Pp One or more component devices is in the degraded or faulted state, but -sufficient replicas exist to continue functioning. The underlying conditions -are as follows: +sufficient replicas exist to continue functioning. +The underlying conditions are as follows: .Bl -bullet .It The number of checksum errors exceeds acceptable levels and the device is -degraded as an indication that something may be wrong. ZFS continues to use the -device as necessary. +degraded as an indication that something may be wrong. +ZFS continues to use the device as necessary. .It -The number of I/O errors exceeds acceptable levels. The device could not be -marked as faulted because there are insufficient replicas to continue -functioning. +The number of I/O errors exceeds acceptable levels. +The device could not be marked as faulted because there are insufficient +replicas to continue functioning. .El .It Sy FAULTED One or more top-level vdevs is in the faulted state because one or more -component devices are offline. Insufficient replicas exist to continue -functioning. +component devices are offline. +Insufficient replicas exist to continue functioning. .Pp One or more component devices is in the faulted state, and insufficient -replicas exist to continue functioning. The underlying conditions are as -follows: +replicas exist to continue functioning. +The underlying conditions are as follows: .Bl -bullet .It The device could be opened, but the contents did not match expected values. @@ -333,25 +347,29 @@ command. .It Sy ONLINE The device is online and functioning. .It Sy REMOVED -The device was physically removed while the system was running. Device removal -detection is hardware-dependent and may not be supported on all platforms. +The device was physically removed while the system was running. +Device removal detection is hardware-dependent and may not be supported on all +platforms. .It Sy UNAVAIL -The device could not be opened. If a pool is imported when a device was -unavailable, then the device will be identified by a unique identifier instead -of its path since the path was never correct in the first place. +The device could not be opened. +If a pool is imported when a device was unavailable, then the device will be +identified by a unique identifier instead of its path since the path was never +correct in the first place. .El .Pp If a device is removed and later re-attached to the system, ZFS attempts -to put the device online automatically. Device attach detection is -hardware-dependent and might not be supported on all platforms. +to put the device online automatically. +Device attach detection is hardware-dependent and might not be supported on all +platforms. .Ss Hot Spares ZFS allows devices to be associated with pools as .Qq hot spares . These devices are not actively used in the pool, but when an active device -fails, it is automatically replaced by a hot spare. To create a pool with hot -spares, specify a +fails, it is automatically replaced by a hot spare. +To create a pool with hot spares, specify a .Sy spare -vdev with any number of devices. For example, +vdev with any number of devices. +For example, .Bd -literal # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0 .Ed @@ -360,11 +378,12 @@ Spares can be shared across multiple pools, and can be added with the .Nm zpool Cm add command and removed with the .Nm zpool Cm remove -command. Once a spare replacement is initiated, a new +command. +Once a spare replacement is initiated, a new .Sy spare vdev is created within the configuration that will remain there until the -original device is replaced. At this point, the hot spare becomes available -again if another device fails. +original device is replaced. +At this point, the hot spare becomes available again if another device fails. .Pp If a pool has a shared spare that is currently being used, the pool can not be exported since other pools may use this shared spare, which may lead to @@ -378,74 +397,82 @@ pools. Spares cannot replace log devices. .Ss Intent Log The ZFS Intent Log (ZIL) satisfies POSIX requirements for synchronous -transactions. For instance, databases often require their transactions to be on -stable storage devices when returning from a system call. NFS and other -applications can also use +transactions. +For instance, databases often require their transactions to be on stable storage +devices when returning from a system call. +NFS and other applications can also use .Xr fsync 3C -to ensure data stability. By default, the intent log is allocated from blocks -within the main pool. However, it might be possible to get better performance -using separate intent log devices such as NVRAM or a dedicated disk. For -example: +to ensure data stability. +By default, the intent log is allocated from blocks within the main pool. +However, it might be possible to get better performance using separate intent +log devices such as NVRAM or a dedicated disk. +For example: .Bd -literal # zpool create pool c0d0 c1d0 log c2d0 .Ed .Pp -Multiple log devices can also be specified, and they can be mirrored. See the +Multiple log devices can also be specified, and they can be mirrored. +See the .Sx EXAMPLES section for an example of mirroring multiple log devices. .Pp Log devices can be added, replaced, attached, detached, and imported and -exported as part of the larger pool. Mirrored log devices can be removed by -specifying the top-level mirror for the log. +exported as part of the larger pool. +Mirrored log devices can be removed by specifying the top-level mirror for the +log. .Ss Cache Devices Devices can be added to a storage pool as .Qq cache devices . These devices provide an additional layer of caching between main memory and -disk. For read-heavy workloads, where the working set size is much larger than -what can be cached in main memory, using cache devices allow much more of this -working set to be served from low latency media. Using cache devices provides -the greatest performance improvement for random read-workloads of mostly static -content. +disk. +For read-heavy workloads, where the working set size is much larger than what +can be cached in main memory, using cache devices allow much more of this +working set to be served from low latency media. +Using cache devices provides the greatest performance improvement for random +read-workloads of mostly static content. .Pp To create a pool with cache devices, specify a .Sy cache -vdev with any number of devices. For example: +vdev with any number of devices. +For example: .Bd -literal # zpool create pool c0d0 c1d0 cache c2d0 c3d0 .Ed .Pp -Cache devices cannot be mirrored or part of a raidz configuration. If a read -error is encountered on a cache device, that read I/O is reissued to the -original storage pool device, which might be part of a mirrored or raidz +Cache devices cannot be mirrored or part of a raidz configuration. +If a read error is encountered on a cache device, that read I/O is reissued to +the original storage pool device, which might be part of a mirrored or raidz configuration. .Pp The content of the cache devices is considered volatile, as is the case with other system caches. .Ss Properties -Each pool has several properties associated with it. Some properties are -read-only statistics while others are configurable and change the behavior of -the pool. +Each pool has several properties associated with it. +Some properties are read-only statistics while others are configurable and +change the behavior of the pool. .Pp The following are read-only properties: .Bl -tag -width Ds .It Sy available -Amount of storage available within the pool. This property can also be referred -to by its shortened column name, +Amount of storage available within the pool. +This property can also be referred to by its shortened column name, .Sy avail . .It Sy bootsize -The size of the system boot partition. This property can only be set at pool -creation time and is read-only once pool is created. Setting this property -implies using the +The size of the system boot partition. +This property can only be set at pool creation time and is read-only once pool +is created. +Setting this property implies using the .Fl B option. .It Sy capacity -Percentage of pool space used. This property can also be referred to by its -shortened column name, +Percentage of pool space used. +This property can also be referred to by its shortened column name, .Sy cap . .It Sy expandsize Amount of uninitialized space within the pool or device that can be used to -increase the total capacity of the pool. Uninitialized space consists of -any space on an EFI labeled vdev which has not been brought online +increase the total capacity of the pool. +Uninitialized space consists of any space on an EFI labeled vdev which has not +been brought online .Po e.g, using .Nm zpool Cm online Fl e .Pc . @@ -458,20 +485,23 @@ The amount of free space available in the pool. After a file system or snapshot is destroyed, the space it was using is returned to the pool asynchronously. .Sy freeing -is the amount of space remaining to be reclaimed. Over time +is the amount of space remaining to be reclaimed. +Over time .Sy freeing will decrease while .Sy free increases. .It Sy health -The current health of the pool. Health can be one of +The current health of the pool. +Health can be one of .Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL . .It Sy guid A unique identifier for the pool. .It Sy size Total size of the storage pool. .It Sy unsupported@ Ns Em feature_guid -Information about unsupported features that are enabled on the pool. See +Information about unsupported features that are enabled on the pool. +See .Xr zpool-features 5 for details. .It Sy used @@ -479,27 +509,32 @@ Amount of storage space used within the pool. .El .Pp The space usage properties report actual physical space available to the -storage pool. The physical space can be different from the total amount of -space that any contained datasets can actually use. The amount of space used in -a raidz configuration depends on the characteristics of the data being -written. In addition, ZFS reserves some space for internal accounting -that the +storage pool. +The physical space can be different from the total amount of space that any +contained datasets can actually use. +The amount of space used in a raidz configuration depends on the characteristics +of the data being written. +In addition, ZFS reserves some space for internal accounting that the .Xr zfs 1M command takes into account, but the .Nm -command does not. For non-full pools of a reasonable size, these effects should -be invisible. For small pools, or pools that are close to being completely -full, these discrepancies may become more noticeable. +command does not. +For non-full pools of a reasonable size, these effects should be invisible. +For small pools, or pools that are close to being completely full, these +discrepancies may become more noticeable. .Pp The following property can be set at creation time and import time: .Bl -tag -width Ds .It Sy altroot -Alternate root directory. If set, this directory is prepended to any mount -points within the pool. This can be used when examining an unknown pool where -the mount points cannot be trusted, or in an alternate boot environment, where -the typical paths are not valid. +Alternate root directory. +If set, this directory is prepended to any mount points within the pool. +This can be used when examining an unknown pool where the mount points cannot be +trusted, or in an alternate boot environment, where the typical paths are not +valid. .Sy altroot -is not a persistent property. It is valid only while the system is up. Setting +is not a persistent property. +It is valid only while the system is up. +Setting .Sy altroot defaults to using .Sy cachefile Ns = Ns Sy none , @@ -511,8 +546,8 @@ The following property can be set only at import time: .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off If set to .Sy on , -the pool will be imported in read-only mode. This property can also be referred -to by its shortened column name, +the pool will be imported in read-only mode. +This property can also be referred to by its shortened column name, .Sy rdonly . .El .Pp @@ -522,39 +557,46 @@ changed with the command: .Bl -tag -width Ds .It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off -Controls automatic pool expansion when the underlying LUN is grown. If set to +Controls automatic pool expansion when the underlying LUN is grown. +If set to .Sy on , -the pool will be resized according to the size of the expanded device. If the -device is part of a mirror or raidz then all devices within that mirror/raidz -group must be expanded before the new space is made available to the pool. The -default behavior is +the pool will be resized according to the size of the expanded device. +If the device is part of a mirror or raidz then all devices within that +mirror/raidz group must be expanded before the new space is made available to +the pool. +The default behavior is .Sy off . This property can also be referred to by its shortened column name, .Sy expand . .It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off -Controls automatic device replacement. If set to +Controls automatic device replacement. +If set to .Sy off , device replacement must be initiated by the administrator by using the .Nm zpool Cm replace -command. If set to +command. +If set to .Sy on , any new device, found in the same physical location as a device that previously -belonged to the pool, is automatically formatted and replaced. The default -behavior is +belonged to the pool, is automatically formatted and replaced. +The default behavior is .Sy off . This property can also be referred to by its shortened column name, .Sy replace . .It Sy bootfs Ns = Ns Ar pool Ns / Ns Ar dataset -Identifies the default bootable dataset for the root pool. This property is -expected to be set mainly by the installation and upgrade programs. +Identifies the default bootable dataset for the root pool. +This property is expected to be set mainly by the installation and upgrade +programs. .It Sy cachefile Ns = Ns Ar path Ns | Ns Sy none -Controls the location of where the pool configuration is cached. Discovering -all pools on system startup requires a cached copy of the configuration data -that is stored on the root file system. All pools in this cache are -automatically imported when the system boots. Some environments, such as -install and clustering, need to cache this information in a different location -so that pools are not automatically imported. Setting this property caches the -pool configuration in a different location that can later be imported with +Controls the location of where the pool configuration is cached. +Discovering all pools on system startup requires a cached copy of the +configuration data that is stored on the root file system. +All pools in this cache are automatically imported when the system boots. +Some environments, such as install and clustering, need to cache this +information in a different location so that pools are not automatically +imported. +Setting this property caches the pool configuration in a different location that +can later be imported with .Nm zpool Cm import Fl c . Setting it to the special value .Sy none @@ -563,43 +605,48 @@ creates a temporary pool that is never cached, and the special value .Pq empty string uses the default location. .Pp -Multiple pools can share the same cache file. Because the kernel destroys and -recreates this file when pools are added and removed, care should be taken when -attempting to access this file. When the last pool using a +Multiple pools can share the same cache file. +Because the kernel destroys and recreates this file when pools are added and +removed, care should be taken when attempting to access this file. +When the last pool using a .Sy cachefile is exported or destroyed, the file is removed. .It Sy comment Ns = Ns Ar text A text string consisting of printable ASCII characters that will be stored -such that it is available even if the pool becomes faulted. An administrator -can provide additional information about a pool using this property. +such that it is available even if the pool becomes faulted. +An administrator can provide additional information about a pool using this +property. .It Sy dedupditto Ns = Ns Ar number -Threshold for the number of block ditto copies. If the reference count for a -deduplicated block increases above this number, a new ditto copy of this block -is automatically stored. The default setting is +Threshold for the number of block ditto copies. +If the reference count for a deduplicated block increases above this number, a +new ditto copy of this block is automatically stored. +The default setting is .Sy 0 -which causes no ditto copies to be created for deduplicated blocks. The minimum -legal nonzero setting is +which causes no ditto copies to be created for deduplicated blocks. +The minimum legal nonzero setting is .Sy 100 . .It Sy delegation Ns = Ns Sy on Ns | Ns Sy off Controls whether a non-privileged user is granted access based on the dataset -permissions defined on the dataset. See +permissions defined on the dataset. +See .Xr zfs 1M for more information on ZFS delegated administration. .It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy panic -Controls the system behavior in the event of catastrophic pool failure. This -condition is typically a result of a loss of connectivity to the underlying -storage device(s) or a failure of all devices within the pool. The behavior of -such an event is determined as follows: +Controls the system behavior in the event of catastrophic pool failure. +This condition is typically a result of a loss of connectivity to the underlying +storage device(s) or a failure of all devices within the pool. +The behavior of such an event is determined as follows: .Bl -tag -width "continue" .It Sy wait Blocks all I/O access until the device connectivity is recovered and the errors -are cleared. This is the default behavior. +are cleared. +This is the default behavior. .It Sy continue Returns .Er EIO to any new write I/O requests but allows reads to any of the remaining healthy -devices. Any write requests that have yet to be committed to disk would be -blocked. +devices. +Any write requests that have yet to be committed to disk would be blocked. .It Sy panic Prints out a message to the console and generates a system crash dump. .El @@ -610,7 +657,8 @@ The only valid value when setting this property is .Sy enabled which moves .Ar feature_name -to the enabled state. See +to the enabled state. +See .Xr zpool-features 5 for details on feature states. .It Sy listsnaps Ns = Ns Sy on Ns | Ns Sy off @@ -619,15 +667,18 @@ output when .Nm zfs Cm list is run without the .Fl t -option. The default value is +option. +The default value is .Sy off . .It Sy version Ns = Ns Ar version -The current on-disk version of the pool. This can be increased, but never -decreased. The preferred method of updating pools is with the +The current on-disk version of the pool. +This can be increased, but never decreased. +The preferred method of updating pools is with the .Nm zpool Cm upgrade command, though this property can be used when a specific version is needed for -backwards compatibility. Once feature flags is enabled on a pool this property -will no longer have a value. +backwards compatibility. +Once feature flags is enabled on a pool this property will no longer have a +value. .El .Ss Subcommands All subcommands that modify state are logged persistently to the pool in their @@ -636,8 +687,8 @@ original form. The .Nm command provides subcommands to create and destroy storage pools, add capacity -to storage pools, and provide information about the storage pools. The -following subcommands are supported: +to storage pools, and provide information about the storage pools. +The following subcommands are supported: .Bl -tag -width Ds .It Xo .Nm @@ -650,11 +701,13 @@ Displays a help message. .Op Fl fn .Ar pool vdev Ns ... .Xc -Adds the specified virtual devices to the given pool. The +Adds the specified virtual devices to the given pool. +The .Ar vdev specification is described in the .Sx Virtual Devices -section. The behavior of the +section. +The behavior of the .Fl f option, and the device checks performed are described in the .Nm zpool Cm create @@ -663,8 +716,8 @@ subcommand. .It Fl f Forces use of .Ar vdev Ns s , -even if they appear in use or specify a conflicting replication level. Not all -devices can be overridden in this manner. +even if they appear in use or specify a conflicting replication level. +Not all devices can be overridden in this manner. .It Fl n Displays the configuration that would be used without actually adding the .Ar vdev Ns s . @@ -681,7 +734,8 @@ Attaches .Ar new_device to the existing .Ar device . -The existing device cannot be part of a raidz configuration. If +The existing device cannot be part of a raidz configuration. +If .Ar device is not currently part of a mirrored configuration, .Ar device @@ -693,15 +747,16 @@ If .Ar device is part of a two-way mirror, attaching .Ar new_device -creates a three-way mirror, and so on. In either case, +creates a three-way mirror, and so on. +In either case, .Ar new_device begins to resilver immediately. .Bl -tag -width Ds .It Fl f Forces use of .Ar new_device , -even if its appears to be in use. Not all devices can be overridden in this -manner. +even if its appears to be in use. +Not all devices can be overridden in this manner. .El .It Xo .Nm @@ -709,9 +764,10 @@ manner. .Ar pool .Op Ar device .Xc -Clears device errors in a pool. If no arguments are specified, all device -errors within the pool are cleared. If one or more devices is specified, only -those errors associated with the specified device or devices are cleared. +Clears device errors in a pool. +If no arguments are specified, all device errors within the pool are cleared. +If one or more devices is specified, only those errors associated with the +specified device or devices are cleared. .It Xo .Nm .Cm create @@ -724,7 +780,8 @@ those errors associated with the specified device or devices are cleared. .Ar pool vdev Ns ... .Xc Creates a new storage pool containing the virtual devices specified on the -command line. The pool name must begin with a letter, and can only contain +command line. +The pool name must begin with a letter, and can only contain alphanumeric characters as well as underscore .Pq Qq Sy _ , dash @@ -746,19 +803,22 @@ specification is described in the section. .Pp The command verifies that each device specified is accessible and not currently -in use by another subsystem. There are some uses, such as being currently -mounted, or specified as the dedicated dump device, that prevents a device from -ever being used by ZFS . Other uses, such as having a preexisting UFS file -system, can be overridden with the +in use by another subsystem. +There are some uses, such as being currently mounted, or specified as the +dedicated dump device, that prevents a device from ever being used by ZFS. +Other uses, such as having a preexisting UFS file system, can be overridden with +the .Fl f option. .Pp The command also checks that the replication strategy for the pool is -consistent. An attempt to combine redundant and non-redundant storage in a -single pool, or to mix disks and files, results in an error unless +consistent. +An attempt to combine redundant and non-redundant storage in a single pool, or +to mix disks and files, results in an error unless .Fl f -is specified. The use of differently sized devices within a single raidz or -mirror group is also flagged as an error unless +is specified. +The use of differently sized devices within a single raidz or mirror group is +also flagged as an error unless .Fl f is specified. .Pp @@ -767,7 +827,8 @@ Unless the option is specified, the default mount point is .Pa / Ns Ar pool . The mount point must not exist or must be empty, or else the root dataset -cannot be mounted. This can be overridden with the +cannot be mounted. +This can be overridden with the .Fl m option. .Pp @@ -777,36 +838,41 @@ option is specified. .Bl -tag -width Ds .It Fl B Create whole disk pool with EFI System partition to support booting system -with UEFI firmware. Default size is 256MB. To create boot partition with -custom size, set the +with UEFI firmware. +Default size is 256MB. +To create boot partition with custom size, set the .Sy bootsize property with the .Fl o -option. See the +option. +See the .Sx Properties section for details. .It Fl d -Do not enable any features on the new pool. Individual features can be enabled -by setting their corresponding properties to +Do not enable any features on the new pool. +Individual features can be enabled by setting their corresponding properties to .Sy enabled with the .Fl o -option. See +option. +See .Xr zpool-features 5 for details about feature properties. .It Fl f Forces use of .Ar vdev Ns s , -even if they appear in use or specify a conflicting replication level. Not all -devices can be overridden in this manner. +even if they appear in use or specify a conflicting replication level. +Not all devices can be overridden in this manner. .It Fl m Ar mountpoint -Sets the mount point for the root dataset. The default mount point is +Sets the mount point for the root dataset. +The default mount point is .Pa /pool or .Pa altroot/pool if .Ar altroot -is specified. The mount point must be an absolute path, +is specified. +The mount point must be an absolute path, .Sy legacy , or .Sy none . @@ -814,15 +880,17 @@ For more information on dataset mount points, see .Xr zfs 1M . .It Fl n Displays the configuration that would be used without actually creating the -pool. The actual pool creation can still fail due to insufficient privileges or +pool. +The actual pool creation can still fail due to insufficient privileges or device sharing. .It Fl o Ar property Ns = Ns Ar value -Sets the given pool properties. See the +Sets the given pool properties. +See the .Sx Properties section for a list of valid properties that can be set. .It Fl O Ar file-system-property Ns = Ns Ar value -Sets the given file system properties in the root file system of the pool. See -the +Sets the given file system properties in the root file system of the pool. +See the .Sx Properties section of .Xr zfs 1M @@ -837,8 +905,8 @@ Equivalent to .Op Fl f .Ar pool .Xc -Destroys the given pool, freeing up any devices for other use. This command -tries to unmount any active datasets before destroying the pool. +Destroys the given pool, freeing up any devices for other use. +This command tries to unmount any active datasets before destroying the pool. .Bl -tag -width Ds .It Fl f Forces any active datasets contained within the pool to be unmounted. @@ -850,28 +918,31 @@ Forces any active datasets contained within the pool to be unmounted. .Xc Detaches .Ar device -from a mirror. The operation is refused if there are no other valid replicas of -the data. +from a mirror. +The operation is refused if there are no other valid replicas of the data. .It Xo .Nm .Cm export .Op Fl f .Ar pool Ns ... .Xc -Exports the given pools from the system. All devices are marked as exported, -but are still considered in use by other subsystems. The devices can be moved -between systems +Exports the given pools from the system. +All devices are marked as exported, but are still considered in use by other +subsystems. +The devices can be moved between systems .Pq even those of different endianness and imported as long as a sufficient number of devices are present. .Pp -Before exporting the pool, all datasets within the pool are unmounted. A pool -can not be exported if it has a shared spare that is currently being used. +Before exporting the pool, all datasets within the pool are unmounted. +A pool can not be exported if it has a shared spare that is currently being +used. .Pp For pools to be portable, you must give the .Nm command whole disks, not just slices, so that ZFS can label the disks with -portable EFI labels. Otherwise, disk drivers on platforms of different -endianness will not recognize the disks. +portable EFI labels. +Otherwise, disk drivers on platforms of different endianness will not recognize +the disks. .Bl -tag -width Ds .It Fl f Forcefully unmount all datasets, using the @@ -879,7 +950,8 @@ Forcefully unmount all datasets, using the command. .Pp This command will forcefully export the pool even if it has a shared spare that -is currently being used. This may lead to potential data corruption. +is currently being used. +This may lead to potential data corruption. .El .It Xo .Nm @@ -895,8 +967,8 @@ or all properties if .Sy all is used .Pc -for the specified storage pool(s). These properties are displayed with -the following fields: +for the specified storage pool(s). +These properties are displayed with the following fields: .Bd -literal name Name of storage pool property Property name @@ -909,8 +981,9 @@ See the section for more information on the available pool properties. .Bl -tag -width Ds .It Fl H -Scripted mode. Do not display headers, and separate fields by a single tab -instead of arbitrary space. +Scripted mode. +Do not display headers, and separate fields by a single tab instead of arbitrary +space. .It Fl o Ar field A comma-separated list of columns to display. .Sy name Ns , Ns Sy property Ns , Ns Sy value Ns , Ns Sy source @@ -940,17 +1013,18 @@ performed. .Op Fl D .Op Fl d Ar dir .Xc -Lists pools available to import. If the +Lists pools available to import. +If the .Fl d option is not specified, this command searches for devices in .Pa /dev/dsk . The .Fl d -option can be specified multiple times, and all directories are searched. If the -device appears to be part of an exported pool, this command displays a summary -of the pool with the name of the pool, a numeric identifier, as well as the vdev -layout and current health of the device for each device or file. Destroyed -pools, pools that were previously destroyed with the +option can be specified multiple times, and all directories are searched. +If the device appears to be part of an exported pool, this command displays a +summary of the pool with the name of the pool, a numeric identifier, as well as +the vdev layout and current health of the device for each device or file. +Destroyed pools, pools that were previously destroyed with the .Nm zpool Cm destroy command, are not listed unless the .Fl D @@ -964,7 +1038,8 @@ Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile -pool property. This +pool property. +This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir @@ -987,9 +1062,10 @@ Lists destroyed pools only. .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... .Op Fl R Ar root .Xc -Imports all pools found in the search directories. Identical to the previous -command, except that all pools with a sufficient number of devices available are -imported. Destroyed pools, pools that were previously destroyed with the +Imports all pools found in the search directories. +Identical to the previous command, except that all pools with a sufficient +number of devices available are imported. +Destroyed pools, pools that were previously destroyed with the .Nm zpool Cm destroy command, will not be imported unless the .Fl D @@ -1002,7 +1078,8 @@ Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile -pool property. This +pool property. +This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir @@ -1010,41 +1087,47 @@ Searches for devices or files in .Ar dir . The .Fl d -option can be specified multiple times. This option is incompatible with the +option can be specified multiple times. +This option is incompatible with the .Fl c option. .It Fl D -Imports destroyed pools only. The +Imports destroyed pools only. +The .Fl f option is also required. .It Fl f Forces import, even if the pool appears to be potentially active. .It Fl F -Recovery mode for a non-importable pool. Attempt to return the pool to an -importable state by discarding the last few transactions. Not all damaged pools -can be recovered by using this option. If successful, the data from the -discarded transactions is irretrievably lost. This option is ignored if the pool -is importable or already imported. +Recovery mode for a non-importable pool. +Attempt to return the pool to an importable state by discarding the last few +transactions. +Not all damaged pools can be recovered by using this option. +If successful, the data from the discarded transactions is irretrievably lost. +This option is ignored if the pool is importable or already imported. .It Fl m -Allows a pool to import when there is a missing log device. Recent transactions -can be lost because the log device will be discarded. +Allows a pool to import when there is a missing log device. +Recent transactions can be lost because the log device will be discarded. .It Fl n Used with the .Fl F -recovery option. Determines whether a non-importable pool can be made importable -again, but does not actually perform the pool recovery. For more details about -pool recovery mode, see the +recovery option. +Determines whether a non-importable pool can be made importable again, but does +not actually perform the pool recovery. +For more details about pool recovery mode, see the .Fl F option, above. .It Fl N Import the pool without mounting any file systems. .It Fl o Ar mntopts Comma-separated list of mount options to use when mounting datasets within the -pool. See +pool. +See .Xr zfs 1M for a description of dataset properties and mount options. .It Fl o Ar property Ns = Ns Ar value -Sets the specified property on the imported pool. See the +Sets the specified property on the imported pool. +See the .Sx Properties section for more information on the available pool properties. .It Fl R Ar root @@ -1069,8 +1152,9 @@ property to .Ar pool Ns | Ns Ar id .Op Ar newpool .Xc -Imports a specific pool. A pool can be identified by its name or the numeric -identifier. If +Imports a specific pool. +A pool can be identified by its name or the numeric identifier. +If .Ar newpool is specified, the pool is imported using the name .Ar newpool . @@ -1078,9 +1162,10 @@ Otherwise, it is imported with the same name as its exported name. .Pp If a device is removed from a system without running .Nm zpool Cm export -first, the device appears as potentially active. It cannot be determined if -this was a failed export, or whether the device is really in use from another -host. To import a pool in this state, the +first, the device appears as potentially active. +It cannot be determined if this was a failed export, or whether the device is +really in use from another host. +To import a pool in this state, the .Fl f option is required. .Bl -tag -width Ds @@ -1089,7 +1174,8 @@ Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile -pool property. This +pool property. +This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir @@ -1097,39 +1183,45 @@ Searches for devices or files in .Ar dir . The .Fl d -option can be specified multiple times. This option is incompatible with the +option can be specified multiple times. +This option is incompatible with the .Fl c option. .It Fl D -Imports destroyed pool. The +Imports destroyed pool. +The .Fl f option is also required. .It Fl f Forces import, even if the pool appears to be potentially active. .It Fl F -Recovery mode for a non-importable pool. Attempt to return the pool to an -importable state by discarding the last few transactions. Not all damaged pools -can be recovered by using this option. If successful, the data from the -discarded transactions is irretrievably lost. This option is ignored if the pool -is importable or already imported. +Recovery mode for a non-importable pool. +Attempt to return the pool to an importable state by discarding the last few +transactions. +Not all damaged pools can be recovered by using this option. +If successful, the data from the discarded transactions is irretrievably lost. +This option is ignored if the pool is importable or already imported. .It Fl m -Allows a pool to import when there is a missing log device. Recent transactions -can be lost because the log device will be discarded. +Allows a pool to import when there is a missing log device. +Recent transactions can be lost because the log device will be discarded. .It Fl n Used with the .Fl F -recovery option. Determines whether a non-importable pool can be made importable -again, but does not actually perform the pool recovery. For more details about -pool recovery mode, see the +recovery option. +Determines whether a non-importable pool can be made importable again, but does +not actually perform the pool recovery. +For more details about pool recovery mode, see the .Fl F option, above. .It Fl o Ar mntopts Comma-separated list of mount options to use when mounting datasets within the -pool. See +pool. +See .Xr zfs 1M for a description of dataset properties and mount options. .It Fl o Ar property Ns = Ns Ar value -Sets the specified property on the imported pool. See the +Sets the specified property on the imported pool. +See the .Sx Properties section for more information on the available pool properties. .It Fl R Ar root @@ -1150,29 +1242,35 @@ property to .Oo Ar pool Oc Ns ... .Op Ar interval Op Ar count .Xc -Displays I/O statistics for the given pools. When given an +Displays I/O statistics for the given pools. +When given an .Ar interval , the statistics are printed every .Ar interval -seconds until ^C is pressed. If no +seconds until ^C is pressed. +If no .Ar pool Ns s -are specified, statistics for every pool in the system is shown. If +are specified, statistics for every pool in the system is shown. +If .Ar count is specified, the command exits after .Ar count reports are printed. .Bl -tag -width Ds .It Fl T Sy u Ns | Ns Sy d -Display a time stamp. Specify +Display a time stamp. +Specify .Sy u -for a printed representation of the internal representation of time. See +for a printed representation of the internal representation of time. +See .Xr time 2 . Specify .Sy d -for standard date format. See +for standard date format. +See .Xr date 1 . .It Fl v -Verbose statistics. Reports usage statistics for individual vdevs within the +Verbose statistics Reports usage statistics for individual vdevs within the pool, in addition to the pool-wide statistics. .El .It Xo @@ -1199,25 +1297,31 @@ Treat exported or foreign devices as inactive. .Oo Ar pool Oc Ns ... .Op Ar interval Op Ar count .Xc -Lists the given pools along with a health status and space usage. If no +Lists the given pools along with a health status and space usage. +If no .Ar pool Ns s -are specified, all pools in the system are listed. When given an +are specified, all pools in the system are listed. +When given an .Ar interval , the information is printed every .Ar interval -seconds until ^C is pressed. If +seconds until ^C is pressed. +If .Ar count is specified, the command exits after .Ar count reports are printed. .Bl -tag -width Ds .It Fl H -Scripted mode. Do not display headers, and separate fields by a single tab -instead of arbitrary space. +Scripted mode. +Do not display headers, and separate fields by a single tab instead of arbitrary +space. .It Fl o Ar property -Comma-separated list of properties to display. See the +Comma-separated list of properties to display. +See the .Sx Properties -section for a list of valid properties. The default list is +section for a list of valid properties. +The default list is .Sy name , size , used , available , fragmentation , expandsize , capacity , .Sy dedupratio , health , altroot . .It Fl p @@ -1225,17 +1329,21 @@ Display numbers in parsable .Pq exact values. .It Fl T Sy u Ns | Ns Sy d -Display a time stamp. Specify +Display a time stamp. +Specify .Fl u -for a printed representation of the internal representation of time. See +for a printed representation of the internal representation of time. +See .Xr time 2 . Specify .Fl d -for standard date format. See +for standard date format. +See .Xr date 1 . .It Fl v -Verbose statistics. Reports usage statistics for individual vdevs within the -pool, in addition to the pool-wise statistics. +Verbose statistics. +Reports usage statistics for individual vdevs within the pool, in addition to +the pool-wise statistics. .El .It Xo .Nm @@ -1243,14 +1351,15 @@ pool, in addition to the pool-wise statistics. .Op Fl t .Ar pool Ar device Ns ... .Xc -Takes the specified physical device offline. While the +Takes the specified physical device offline. +While the .Ar device -is offline, no attempt is made to read or write to the device. This command is -not applicable to spares. +is offline, no attempt is made to read or write to the device. +This command is not applicable to spares. .Bl -tag -width Ds .It Fl t -Temporary. Upon reboot, the specified physical device reverts to its previous -state. +Temporary. +Upon reboot, the specified physical device reverts to its previous state. .El .It Xo .Nm @@ -1258,21 +1367,22 @@ state. .Op Fl e .Ar pool Ar device Ns ... .Xc -Brings the specified physical device online. This command is not applicable to -spares. +Brings the specified physical device online. +This command is not applicable to spares. .Bl -tag -width Ds .It Fl e -Expand the device to use all available space. If the device is part of a mirror -or raidz then all devices must be expanded before the new space will become -available to the pool. +Expand the device to use all available space. +If the device is part of a mirror or raidz then all devices must be expanded +before the new space will become available to the pool. .El .It Xo .Nm .Cm reguid .Ar pool .Xc -Generates a new unique identifier for the pool. You must ensure that all devices -in this pool are online and healthy before performing this action. +Generates a new unique identifier for the pool. +You must ensure that all devices in this pool are online and healthy before +performing this action. .It Xo .Nm .Cm reopen @@ -1284,12 +1394,16 @@ Reopen all the vdevs associated with the pool. .Cm remove .Ar pool Ar device Ns ... .Xc -Removes the specified device from the pool. This command currently only supports -removing hot spares, cache, and log devices. A mirrored log device can be -removed by specifying the top-level mirror for the log. Non-log devices that are -part of a mirrored configuration can be removed using the +Removes the specified device from the pool. +This command currently only supports removing hot spares, cache, and log +devices. +A mirrored log device can be removed by specifying the top-level mirror for the +log. +Non-log devices that are part of a mirrored configuration can be removed using +the .Nm zpool Cm detach -command. Non-redundant and raidz devices cannot be removed from a pool. +command. +Non-redundant and raidz devices cannot be removed from a pool. .It Xo .Nm .Cm replace @@ -1311,21 +1425,23 @@ must be greater than or equal to the minimum size of all the devices in a mirror or raidz configuration. .Pp .Ar new_device -is required if the pool is not redundant. If +is required if the pool is not redundant. +If .Ar new_device is not specified, it defaults to .Ar old_device . This form of replacement is useful after an existing disk has failed and has -been physically replaced. In this case, the new disk may have the same +been physically replaced. +In this case, the new disk may have the same .Pa /dev/dsk -path as the old device, even though it is actually a different disk. ZFS -recognizes this. +path as the old device, even though it is actually a different disk. +ZFS recognizes this. .Bl -tag -width Ds .It Fl f Forces use of .Ar new_device , -even if its appears to be in use. Not all devices can be overridden in this -manner. +even if its appears to be in use. +Not all devices can be overridden in this manner. .El .It Xo .Nm @@ -1333,16 +1449,20 @@ manner. .Op Fl s .Ar pool Ns ... .Xc -Begins a scrub. The scrub examines all data in the specified pools to verify -that it checksums correctly. For replicated +Begins a scrub. +The scrub examines all data in the specified pools to verify that it checksums +correctly. +For replicated .Pq mirror or raidz -devices, ZFS automatically repairs any damage discovered during the scrub. The +devices, ZFS automatically repairs any damage discovered during the scrub. +The .Nm zpool Cm status command reports the progress of the scrub and summarizes the results of the scrub upon completion. .Pp -Scrubbing and resilvering are very similar operations. The difference is that -resilvering only examines data that ZFS knows to be out of date +Scrubbing and resilvering are very similar operations. +The difference is that resilvering only examines data that ZFS knows to be out +of date .Po for example, when attaching a new device to a mirror or replacing an existing device @@ -1351,10 +1471,12 @@ whereas scrubbing examines all data to discover silent errors due to hardware faults or disk failure. .Pp Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows -one at a time. If a scrub is already in progress, the +one at a time. +If a scrub is already in progress, the .Nm zpool Cm scrub -command terminates it and starts a new scrub. If a resilver is in progress, ZFS -does not allow a scrub to be started until the resilver completes. +command terminates it and starts a new scrub. +If a resilver is in progress, ZFS does not allow a scrub to be started until the +resilver completes. .Bl -tag -width Ds .It Fl s Stop scrubbing. @@ -1365,7 +1487,8 @@ Stop scrubbing. .Ar property Ns = Ns Ar value .Ar pool .Xc -Sets the given property on the specified pool. See the +Sets the given property on the specified pool. +See the .Sx Properties section for more information on what properties can be set and acceptable values. @@ -1383,14 +1506,15 @@ creating .Ar newpool . All vdevs in .Ar pool -must be mirrors. At the time of the split, +must be mirrors. +At the time of the split, .Ar newpool will be a replica of .Ar pool . .Bl -tag -width Ds .It Fl n -Do dry run, do not actually perform the split. Print out the expected -configuration of +Do dry run, do not actually perform the split. +Print out the expected configuration of .Ar newpool . .It Fl o Ar property Ns = Ns Ar value Sets the specified property for @@ -1415,17 +1539,18 @@ and automaticaly import it. .Oo Ar pool Oc Ns ... .Op Ar interval Op Ar count .Xc -Displays the detailed health status for the given pools. If no +Displays the detailed health status for the given pools. +If no .Ar pool -is specified, then the status of each pool in the system is displayed. For more -information on pool and device health, see the +is specified, then the status of each pool in the system is displayed. +For more information on pool and device health, see the .Sx Device Failure and Recovery section. .Pp If a scrub or resilver is in progress, this command reports the percentage done -and the estimated time to completion. Both of these are only approximate, -because the amount of data in the pool and the other workloads on the system can -change. +and the estimated time to completion. +Both of these are only approximate, because the amount of data in the pool and +the other workloads on the system can change. .Bl -tag -width Ds .It Fl D Display a histogram of deduplication statistics, showing the allocated @@ -1434,29 +1559,33 @@ and referenced .Pq logically referenced in the pool block counts and sizes by reference count. .It Fl T Sy u Ns | Ns Sy d -Display a time stamp. Specify +Display a time stamp. +Specify .Fl u -for a printed representation of the internal representation of time. See +for a printed representation of the internal representation of time. +See .Xr time 2 . Specify .Fl d -for standard date format. See +for standard date format. +See .Xr date 1 . .It Fl v Displays verbose data error information, printing out a complete list of all data errors since the last complete pool scrub. .It Fl x Only display status for pools that are exhibiting errors or are otherwise -unavailable. Warnings about pools not using the latest on-disk format will not -be included. +unavailable. +Warnings about pools not using the latest on-disk format will not be included. .El .It Xo .Nm .Cm upgrade .Xc Displays pools which do not have all supported features enabled and pools -formatted using a legacy ZFS version number. These pools can continue to be -used, but some features may not be available. Use +formatted using a legacy ZFS version number. +These pools can continue to be used, but some features may not be available. +Use .Nm zpool Cm upgrade Fl a to enable all features on all pools. .It Xo @@ -1464,7 +1593,8 @@ to enable all features on all pools. .Cm upgrade .Fl v .Xc -Displays legacy ZFS versions supported by the current software. See +Displays legacy ZFS versions supported by the current software. + See .Xr zpool-features 5 for a description of feature flags features supported by the current software. .It Xo @@ -1473,8 +1603,10 @@ for a description of feature flags features supported by the current software. .Op Fl V Ar version .Fl a Ns | Ns Ar pool Ns ... .Xc -Enables all supported features on the given pool. Once this is done, the pool -will no longer be accessible on systems that do not support feature flags. See +Enables all supported features on the given pool. +Once this is done, the pool will no longer be accessible on systems that do not +support feature flags. +See .Xr zpool-features 5 for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool. @@ -1482,11 +1614,12 @@ support all features enabled on the pool. .It Fl a Enables all supported features on all pools. .It Fl V Ar version -Upgrade to the specified legacy version. If the +Upgrade to the specified legacy version. +If the .Fl V -flag is specified, no features will be enabled on the pool. This option can only -be used to increase the version number up to the last supported legacy version -number. +flag is specified, no features will be enabled on the pool. +This option can only be used to increase the version number up to the last +supported legacy version number. .El .El .Sh EXIT STATUS @@ -1519,25 +1652,26 @@ The following command creates an unmirrored pool using two disk slices. # zpool create tank /dev/dsk/c0t0d0s1 c0t1d0s4 .Ed .It Sy Example 4 No Creating a ZFS Storage Pool by Using Files -The following command creates an unmirrored pool using files. While not -recommended, a pool based on files can be useful for experimental purposes. +The following command creates an unmirrored pool using files. +While not recommended, a pool based on files can be useful for experimental +purposes. .Bd -literal # zpool create tank /path/to/file/a /path/to/file/b .Ed .It Sy Example 5 No Adding a Mirror to a ZFS Storage Pool The following command adds two mirrored disks to the pool .Em tank , -assuming the pool is already made up of two-way mirrors. The additional space -is immediately available to any datasets within the pool. +assuming the pool is already made up of two-way mirrors. +The additional space is immediately available to any datasets within the pool. .Bd -literal # zpool add tank mirror c1t0d0 c1t1d0 .Ed .It Sy Example 6 No Listing Available ZFS Storage Pools -The following command lists all available pools on the system. In this case, -the pool +The following command lists all available pools on the system. +In this case, the pool .Em zion -is faulted due to a missing device. The results from this command are similar -to the following: +is faulted due to a missing device. +The results from this command are similar to the following: .Bd -literal # zpool list NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT @@ -1562,8 +1696,8 @@ so that they can be relocated or later imported. .It Sy Example 9 No Importing a ZFS Storage Pool The following command displays available pools, and then imports the pool .Em tank -for use on the system. The results from this command are similar to the -following: +for use on the system. +The results from this command are similar to the following: .Bd -literal # zpool import pool: tank @@ -1593,14 +1727,16 @@ The following command creates a new pool with an available hot spare: .Ed .Pp If one of the disks were to fail, the pool would be reduced to the degraded -state. The failed device can be replaced using the following command: +state. +The failed device can be replaced using the following command: .Bd -literal # zpool replace tank c0t0d0 c0t3d0 .Ed .Pp Once the data has been resilvered, the spare is automatically removed and is -made available should another device fails. The hot spare can be permanently -removed from the pool using the following command: +made available should another device fails. +The hot spare can be permanently removed from the pool using the following +command: .Bd -literal # zpool remove tank c0t2d0 .Ed @@ -1620,7 +1756,8 @@ pool: .Pp Once added, the cache devices gradually fill with content from main memory. Depending on the size of your cache devices, it could take over an hour for -them to fill. Capacity and reads can be monitored using the +them to fill. +Capacity and reads can be monitored using the .Cm iostat option as follows: .Bd -literal @@ -1660,9 +1797,9 @@ is: The following command dipslays the detailed information for the pool .Em data . This pool is comprised of a single raidz vdev where one of its devices -increased its capacity by 10GB. In this example, the pool will not be able to -utilize this extra capacity until all the devices under the raidz vdev have -been expanded. +increased its capacity by 10GB. +In this example, the pool will not be able to utilize this extra capacity until +all the devices under the raidz vdev have been expanded. .Bd -literal # zpool list -v data NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT diff --git a/usr/src/man/man2/vfork.2 b/usr/src/man/man2/vfork.2 index e6b39b04c0..7cff5d8009 100644 --- a/usr/src/man/man2/vfork.2 +++ b/usr/src/man/man2/vfork.2 @@ -25,8 +25,8 @@ The and .Fn vforkx functions create a new process without -fully copying the address space of the old process. These functions are useful -in instances where the purpose of a +fully copying the address space of the old process. +These functions are useful in instances where the purpose of a .Xr fork 2 operation is to create a new system context for an @@ -56,7 +56,8 @@ borrow only the thread of control that called .Fn vfork or .Fn vforkx -in the parent; that is, the child contains only one thread. The use of +in the parent; that is, the child contains only one thread. +The use of .Fn vfork or .Fn vforkx @@ -73,14 +74,15 @@ functions can normally be used the same way as .Fn fork and .Fn forkx , -respectively. The calling procedure, -however, should not return while running in the child's context, since the -eventual return from +respectively. +The calling procedure, however, should not return while running in the child's +context, since the eventual return from .Fn vfork or .Fn vforkx in the parent would be to -a stack frame that no longer exists. The +a stack frame that no longer exists. +The .Fn _exit function should be used in favor of @@ -92,9 +94,9 @@ operation, since will invoke all functions registered by .Xr atexit 3C and will flush and close standard I/O channels, thereby corrupting the parent -process's standard I/O data structures. Care must be taken in the child process -not to modify any global or local data that affects the behavior of the parent -process on return from +process's standard I/O data structures. +Care must be taken in the child process not to modify any global or local data +that affects the behavior of the parent process on return from .Fn vfork or .Fn vforkx , @@ -115,8 +117,9 @@ The .Fn vfork and .Fn vforkx -functions are deprecated. Their sole -legitimate use as a prelude to an immediate call to a function from the +functions are deprecated. +Their sole legitimate use as a prelude to an immediate call to a function from +the .Xr exec 2 family can be achieved safely by .Xr posix_spawn 3C @@ -141,7 +144,8 @@ in the header .Lp See .Xr fork 2 -for descriptions of these flags. If the +for descriptions of these flags. +If the .Fa flags argument is 0, .Fn vforkx @@ -154,8 +158,9 @@ and .Fn vforkx return 0 to the child process and return the process ID of the child process to the parent -process. Otherwise, \(mi1 is returned to the parent process, no child -process is created, and +process. +Otherwise, \(mi1 is returned to the parent process, no child process is created, +and .Va errno is set to indicate the error. .Sh ERRORS @@ -167,8 +172,8 @@ functions will fail if: .Bl -tag -width Er .It Er EAGAIN The system-imposed limit on the total number of processes under execution -(either system-quality or by a single user) would be exceeded. This limit is -determined when the system is generated. +(either system-quality or by a single user) would be exceeded. +This limit is determined when the system is generated. . .It Er ENOMEM There is insufficient swap space for the new process. @@ -250,8 +255,8 @@ On some systems, the implementation of and .Fn vforkx cause -the parent to inherit register values from the child. This can create problems -for certain optimizing compilers if +the parent to inherit register values from the child. +This can create problems for certain optimizing compilers if .In unistd.h is not included in the source calling .Fn vfork @@ -263,7 +268,8 @@ source calling .Sh STANDARDS The .Fn vfork -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3avl/avl_add.3avl b/usr/src/man/man3avl/avl_add.3avl index 3d1629408b..8c94d2baf1 100644 --- a/usr/src/man/man3avl/avl_add.3avl +++ b/usr/src/man/man3avl/avl_add.3avl @@ -46,7 +46,8 @@ function inserts into the tree. .Fa node must not already be in the tree, thus implying it must not compare equal -to any other node in the tree. Adding +to any other node in the tree. +Adding .Fa node to .Fa tree diff --git a/usr/src/man/man3avl/avl_create.3avl b/usr/src/man/man3avl/avl_create.3avl index 4eb687e3e8..908ae0a9af 100644 --- a/usr/src/man/man3avl/avl_create.3avl +++ b/usr/src/man/man3avl/avl_create.3avl @@ -35,10 +35,12 @@ function initializes an AVL tree rooted at .Pp An AVL tree needs to encode information about the type of data structures being stored inside of it and needs to be told how to compare -two different entries in the same tree. The +two different entries in the same tree. +The .Fa size argument represents the total size of the data structure being used in -the tree. This is a constant that is generally expressed to +the tree. +This is a constant that is generally expressed to .Fn avl_create using the .Sy sizeof @@ -46,9 +48,11 @@ operator. .Pp The data structure that is being stored in the AVL tree must include an .Sy avl_node_t -as a member of the structure. The structure may have multiple +as a member of the structure. +The structure may have multiple .Sy avl_node_t Ns 's, -one for each AVL tree that it may concurrently be a member of. The +one for each AVL tree that it may concurrently be a member of. +The .Fa offset argument indicates what the offset of the .Sy avl_node_t @@ -56,11 +60,11 @@ is for the data structure that this AVL tree contains. .Pp The .Fa compare -function pointer is used to compare two nodes in the tree. This is used as part -of all operations on the tree that cause traversal. The function is -given, as arguments, two pointers to the actual data nodes, which should be -cast to the corresponding type of actual data. The return value must -adhere to the following rules: +function pointer is used to compare two nodes in the tree. +This is used as part of all operations on the tree that cause traversal. +The function is given, as arguments, two pointers to the actual data nodes, +which should be cast to the corresponding type of actual data. +The return value must adhere to the following rules: .Bl -enum .It If the first argument, @@ -80,8 +84,8 @@ function must return Otherwise, if they compare to the same value, then it should return .Sy 0 . .It -Only the return values, -1, 0, and 1, are valid. Returning values -other than those will result in undefined behavior. +Only the return values, -1, 0, and 1, are valid. +Returning values other than those will result in undefined behavior. .El .Pp When two nodes in the tree compare equal, then that means that they diff --git a/usr/src/man/man3avl/avl_destroy.3avl b/usr/src/man/man3avl/avl_destroy.3avl index b892fbb7f5..eb4ad6e933 100644 --- a/usr/src/man/man3avl/avl_destroy.3avl +++ b/usr/src/man/man3avl/avl_destroy.3avl @@ -33,9 +33,11 @@ At the time that .Fn avl_destroy is called, .Fa tree -must be empty. It is a programmer error to call +must be empty. +It is a programmer error to call .Fn avl_destroy -otherwise. To efficiently remove all entries in the tree, see +otherwise. +To efficiently remove all entries in the tree, see .Xr avl_destroy_nodes 3AVL . .Pp After a call to diff --git a/usr/src/man/man3avl/avl_destroy_nodes.3avl b/usr/src/man/man3avl/avl_destroy_nodes.3avl index 2ca330db04..ed28650854 100644 --- a/usr/src/man/man3avl/avl_destroy_nodes.3avl +++ b/usr/src/man/man3avl/avl_destroy_nodes.3avl @@ -48,8 +48,9 @@ to and pass a pointer to it as the argument .Fa cookie . This is an opaque value that will be used to maintain where to next -delete items from the tree. Callers should never modify it after -initializing it. After each call to +delete items from the tree. +Callers should never modify it after initializing it. +After each call to .Fn avl_destroy_nodes , .Fa cookie will be updated and must be passed to subsequent calls to @@ -59,7 +60,8 @@ Each time .Fn avl_destroy_nodes is called, it will return a pointer to an object that had previously been inserted into the tree, allowing a caller the opportunity to delete -or clean it up. Once +or clean it up. +Once .Fn avl_destroy_nodes returns a .Sy NULL diff --git a/usr/src/man/man3avl/avl_find.3avl b/usr/src/man/man3avl/avl_find.3avl index a43ceac4be..7a7ab32d17 100644 --- a/usr/src/man/man3avl/avl_find.3avl +++ b/usr/src/man/man3avl/avl_find.3avl @@ -63,12 +63,13 @@ will be updated to a value that can be used with both .Xr avl_insert 3AVL and .Xr avl_nearest 3AVL . -This value is only valid as long as the tree is not modified. If -anything is added or removed from the tree, then the value of +This value is only valid as long as the tree is not modified. +If anything is added or removed from the tree, then the value of .Fa where -is no longer valid. This is commonly used as part of a pattern to see if -something that should be added to the tree already exists, and if not, -insert it. For more information, see the examples in +is no longer valid. +This is commonly used as part of a pattern to see if something that should be +added to the tree already exists, and if not, insert it. +For more information, see the examples in .Xr libavl 3LIB . .Pp If the lookup is successful, then the contents of @@ -77,7 +78,8 @@ are undefined. .Sh RETURN VALUES If .Fa node -matches an entry in the tree, the matching entry is returned. Otherwise, +matches an entry in the tree, the matching entry is returned. +Otherwise, .Sy NULL is returned and if .Fa where diff --git a/usr/src/man/man3avl/avl_first.3avl b/usr/src/man/man3avl/avl_first.3avl index a4417c60cf..d5e7c06b3d 100644 --- a/usr/src/man/man3avl/avl_first.3avl +++ b/usr/src/man/man3avl/avl_first.3avl @@ -75,7 +75,8 @@ beginning or end of the tree, then is returned. .Pp These constructs are generally used as part of loops to iterate the -tree. See the examples section in +tree. +See the examples section in .Xr libavl 3LIB for more information on using this interface. diff --git a/usr/src/man/man3avl/avl_insert.3avl b/usr/src/man/man3avl/avl_insert.3avl index 4a942918fb..8d21f4d140 100644 --- a/usr/src/man/man3avl/avl_insert.3avl +++ b/usr/src/man/man3avl/avl_insert.3avl @@ -50,8 +50,8 @@ function uses the .Fa where value, obtained from a call to .Xr avl_find 3AVL , -to determine where to insert the new entry into the tree. The tree must -not have been modified in between the call to +to determine where to insert the new entry into the tree. +The tree must not have been modified in between the call to .Xr avl_find 3AVL and the call to .Fn avl_insert . @@ -72,8 +72,8 @@ The new entry, .Fa new , will be inserted starting at the node .Fa here , -which must already exist in the tree. To insert the node in the tree -before +which must already exist in the tree. +To insert the node in the tree before .Fa here , then the argument .Fa direction diff --git a/usr/src/man/man3avl/avl_is_empty.3avl b/usr/src/man/man3avl/avl_is_empty.3avl index f8d2c17ab2..693ec38b57 100644 --- a/usr/src/man/man3avl/avl_is_empty.3avl +++ b/usr/src/man/man3avl/avl_is_empty.3avl @@ -29,7 +29,8 @@ The .Fn avl_is_empty function is used to determine whether or not the AVL tree, .Fa tree , -is empty. If +is empty. +If .Fa tree has zero nodes in it, then .Sy B_TRUE diff --git a/usr/src/man/man3avl/avl_nearest.3avl b/usr/src/man/man3avl/avl_nearest.3avl index 669f78c61f..5da525c734 100644 --- a/usr/src/man/man3avl/avl_nearest.3avl +++ b/usr/src/man/man3avl/avl_nearest.3avl @@ -48,7 +48,8 @@ If .Fa direction is set to .Dv AVL_AFTER , -then the node that would logically have followed it will be returned. If +then the node that would logically have followed it will be returned. +If .Fa direction is instead set to .Dv AVL_BEFORE , diff --git a/usr/src/man/man3avl/avl_swap.3avl b/usr/src/man/man3avl/avl_swap.3avl index 0d4ec606fe..601607fb97 100644 --- a/usr/src/man/man3avl/avl_swap.3avl +++ b/usr/src/man/man3avl/avl_swap.3avl @@ -34,8 +34,9 @@ with those in .Fa tree2 . The two trees must have hold identical kinds of data, the arguments passed to -.Xr avl_create -must be identical. The behavior when they are not is undefined. +.Xr avl_create 3AVL +must be identical. +The behavior when they are not is undefined. .Sh EXAMPLES See the .Sy EXAMPLES diff --git a/usr/src/man/man3c/aligned_alloc.3c b/usr/src/man/man3c/aligned_alloc.3c index d3c6f43c32..ccfc200bcf 100644 --- a/usr/src/man/man3c/aligned_alloc.3c +++ b/usr/src/man/man3c/aligned_alloc.3c @@ -40,7 +40,8 @@ Upon successful completion, the .Fn aligned_alloc function returns a pointer to suitably aligned memory at least .Fa size -bytes large. Otherwise, a +bytes large. +Otherwise, a .Sy NULL pointer is returned and .Sy errno @@ -61,7 +62,8 @@ bytes of memory; but the application could try again later. .It Er EINVAL An invalid value for .Fa alignment -was passed in. It is not a power of two multiple of the word size. +was passed in. +It is not a power of two multiple of the word size. .El .Sh INTERFACE STABILITY .Sy STANDARD diff --git a/usr/src/man/man3c/call_once.3c b/usr/src/man/man3c/call_once.3c index 5cc1ba56a9..80cf0860e2 100644 --- a/usr/src/man/man3c/call_once.3c +++ b/usr/src/man/man3c/call_once.3c @@ -29,7 +29,8 @@ The .Fn call_once function is used to ensure that an operation occurs only once, even -across multiple threads. Each instance of a properly initialized +across multiple threads. +Each instance of a properly initialized .Ft once_flag can be pased to the .Ft call_once @@ -38,10 +39,11 @@ specified function, .Fa func . This ensures that the argument .Fa func -is called only once. Note, the argument +is called only once. +Note, the argument .Fa once -is the only thing used as a point of synchronization. If multiple -callers use the same pointer for +is the only thing used as a point of synchronization. +If multiple callers use the same pointer for .Fa once , but use different values for .Fa func , @@ -73,7 +75,8 @@ had not completed successfully. .Sh RETURN VALUES The .Fn call_once -function does not return any values. Upon its completion, it is guaranteed that +function does not return any values. +Upon its completion, it is guaranteed that .Fa func will have been called at most once across the liftime of the .Fa once diff --git a/usr/src/man/man3c/clearenv.3c b/usr/src/man/man3c/clearenv.3c index aa32c3f7a9..16bd532489 100644 --- a/usr/src/man/man3c/clearenv.3c +++ b/usr/src/man/man3c/clearenv.3c @@ -26,10 +26,12 @@ .Sh DESCRIPTION The .Fn clearenv -function clears the contents of the environment. All environment variables in -the calling process are removed as though the function +function clears the contents of the environment. +All environment variables in the calling process are removed as though the +function .Xr unsetenv 3C -had been called on every environment variable. Until subsequent calls to +had been called on every environment variable. +Until subsequent calls to .Xr putenv 3C or .Xr setenv 3C @@ -44,10 +46,11 @@ returns .Sy 0 . Otherwise, it returns a non-zero value and sets .Sy errno -to indicate the error. At this time, no errors are defined for +to indicate the error. +At this time, no errors are defined for .Fn clearenv , -it will always succeed. Portable applications should always check the return -value of +it will always succeed. +Portable applications should always check the return value of .Fn clearenv . .Sh ERRORS No errors are defined. diff --git a/usr/src/man/man3c/cnd.3c b/usr/src/man/man3c/cnd.3c index 7e2ce29d66..e2bd8041cc 100644 --- a/usr/src/man/man3c/cnd.3c +++ b/usr/src/man/man3c/cnd.3c @@ -15,7 +15,7 @@ .Dt CND 3C .Os .Sh NAME -.Nm cnd +.Nm cnd , .Nm cnd_broadcast , .Nm cnd_destroy , .Nm cnd_init , @@ -57,9 +57,10 @@ The .Sy cnd family of functions implement condition variables which allow threads within a process to wait until a condition occurs and be signaled when -it does. These functions behave similar to both the POSIX threads and -illumos threads; however, they have slightly different call signatures -and return values. For more information, see +it does. +These functions behave similar to both the POSIX threads and illumos threads; +however, they have slightly different call signatures and return values. +For more information, see .Xr threads 5 . Importantly, they do not allow for inter-process synchronization. .Ss Creating and Destroy Condition Variables @@ -67,8 +68,9 @@ The function .Fn cnd_init initializes the condition variable referred to by .Fa cnd . -The condition variable is suitable for intra-process use. Initializing -an already initialized condition variable results in undefined behavior. +The condition variable is suitable for intra-process use. +Initializing an already initialized condition variable results in undefined +behavior. .Pp The function .Fn cnd_destroy @@ -77,9 +79,9 @@ to use it, though it may be initialized again. .Ss Condition Waiting The function .Fn cond_wait -can be used to wait on a condition variable. A thread that waits on a -condition variable blocks until another thread signals that the -condition has changed, generally after making the condition that was +can be used to wait on a condition variable. +A thread that waits on a condition variable blocks until another thread signals +that the condition has changed, generally after making the condition that was false, true. .Pp The function @@ -90,10 +92,11 @@ and blocks on the condition variable .Fa cond . When the thread returns, it will once again be holding .Fa mtx -and must check the current state of the condition. There is no -guarantee that another thread has not gotten in and changed the value -before being woken. In addition, a thread blocking on a condition -variable, may be woken spuriously, such as when a signal is received or +and must check the current state of the condition. +There is no guarantee that another thread has not gotten in and changed the +value before being woken. +In addition, a thread blocking on a condition variable, may be woken spuriously, +such as when a signal is received or .Fn fork is called . .Pp @@ -104,8 +107,8 @@ allows a thread to block in a similar fashion to except that when the absolute time specified in seconds since the epoch (based on .Sy CLOCK_REALTIME ) -in UTC, expires, then the thread will be woken up. The timeout is -specified in +in UTC, expires, then the thread will be woken up. +The timeout is specified in .Fa abstime . .Ss Conditional Signaling The @@ -114,7 +117,8 @@ and .Fn cnd_broadcast functions can be used to signal threads waiting on the condition variable .Fa cnd -that they should be woken up and check the variable again. The +that they should be woken up and check the variable again. +The .Fn cnd_signal function will only wake a single thread that is blocked on the condition variable diff --git a/usr/src/man/man3c/endian.3c b/usr/src/man/man3c/endian.3c index 5161af8fbd..719dae8e28 100644 --- a/usr/src/man/man3c/endian.3c +++ b/usr/src/man/man3c/endian.3c @@ -113,10 +113,10 @@ The .Nm family of functions convert 16, 32, and 64-bit values between the host's -native byte order and big- or little-endian. All of the functions in -this family simply return their input when the host's native byte order -is the same as the desired order. For more information on -endianness, see +native byte order and big- or little-endian. +All of the functions in this family simply return their input when the host's +native byte order is the same as the desired order. +For more information on endianness, see .Xr byteorder 5 . .Pp The @@ -169,13 +169,14 @@ are the same as .Fn letoh32 , and .Fn letoh64 -respectively. Historically, different platforms have diverged on the -naming of these functions. To better support extant software, both are -provided. +respectively. +Historically, different platforms have diverged on the naming of these +functions. +To better support extant software, both are provided. .Pp While these functions are common across multiple platforms, they have -not been standardized. Portable applications should instead use the -functions defined in +not been standardized. +Portable applications should instead use the functions defined in .Xr byteorder 3C . .Sh RETURN VALUES The functions always succeed and return a value that has been properly diff --git a/usr/src/man/man3c/eventfd.3c b/usr/src/man/man3c/eventfd.3c index b0c74e1d51..a1b44439df 100644 --- a/usr/src/man/man3c/eventfd.3c +++ b/usr/src/man/man3c/eventfd.3c @@ -29,8 +29,8 @@ The .Fn eventfd function creates an .Xr eventfd 5 -instance that has an associated 64-bit unsigned counter. It returns a file -descriptor that can be operated upon via +instance that has an associated 64-bit unsigned counter. +It returns a file descriptor that can be operated upon via .Xr read 2 , .Xr write 2 and the facilities that notify of file descriptor activity (e.g., @@ -44,8 +44,9 @@ should be called on the file descriptor. The .Fa initval argument specifies the initial value of the 64-bit counter associated with the -instance. (Note that this limits the initial value to be a 32-bit quantity -despite the fact that the underlying counter is 64-bit.) +instance. +(Note that this limits the initial value to be a 32-bit quantity despite the +fact that the underlying counter is 64-bit.) .Pp The \fIflags\fR argument specifies additional parameters for the instance, and can have any of the following values: @@ -61,7 +62,8 @@ description of .Ed .It Sy EFD_NONBLOCK .Bd -filled -compact -Instance will be set to be non-blocking. A +Instance will be set to be non-blocking. +A .Xr read 2 on an .Sy eventfd @@ -76,7 +78,8 @@ in lieu of blocking if the count associated with the instance is zero. Provide counting semaphore semantics whereby a .Xr read 2 will atomically decrement rather than atomically clear the count when it -becomes non-zero. See below for details on +becomes non-zero. +See below for details on .Xr read 2 semantics. .Ed @@ -89,8 +92,8 @@ instance: .It Sy read(2) .Bd -filled -compact Atomically reads and modifies the value of the 64-bit counter associated -with the instance. The precise semantics -of +with the instance. +The precise semantics of .Xr read 2 depend on the disposition of .Sy EFD_SEMAPHORE @@ -110,7 +113,8 @@ will .Em atomically clear the counter if (and when) it is non-zero, copying the former value of the counter to the eight byte buffer passed to the -system call. In either case, +system call. +In either case, .Xr read 2 will block if the counter is zero (or return @@ -127,8 +131,8 @@ will be returned. .It Sy write(2) .Bd -filled -compact Atomically adds the 64-bit value pointed to by the buffer to the 64-bit -counter associated with the instance. If the resulting value would overflow, -the +counter associated with the instance. +If the resulting value would overflow, the .Xr write 2 will block until the value would not overflow (or return @@ -159,8 +163,10 @@ will be set. .El .Sh RETURN VALUES Upon successful completion, a file descriptor associated with the instance -is returned. Otherwise, -.Sy -1 is returned and +is returned. +Otherwise, +.Sy -1 +is returned and .Sy errno is set to indicate the error. .Sh ERRORS diff --git a/usr/src/man/man3c/fcloseall.3c b/usr/src/man/man3c/fcloseall.3c index c1a9f49847..4b47ca92e8 100644 --- a/usr/src/man/man3c/fcloseall.3c +++ b/usr/src/man/man3c/fcloseall.3c @@ -26,11 +26,13 @@ .Sh DESCRIPTION The .Fn fcloseall -function closes all open standard I/O streams. The equivalent of +function closes all open standard I/O streams. +The equivalent of .Xr fflush 3C is called on each stream before closing, thus any buffered or pending input is discarded while any buffered or pending output is written out -to the underlying file. This includes the standard streams, +to the underlying file. +This includes the standard streams, .Vt stdin , .Vt stdout , and diff --git a/usr/src/man/man3c/get_nprocs.3c b/usr/src/man/man3c/get_nprocs.3c index 4d73833b56..9b5df526df 100644 --- a/usr/src/man/man3c/get_nprocs.3c +++ b/usr/src/man/man3c/get_nprocs.3c @@ -42,7 +42,8 @@ respectively. .Sh RETURN VALUES The .Fn get_nprocs -function returns the number of processors that are currently online. The +function returns the number of processors that are currently online. +The .Fn get_nprocs_conf function returns the number of processors that the operating system has configured. diff --git a/usr/src/man/man3c/getprogname.3c b/usr/src/man/man3c/getprogname.3c index 5bc48e6d69..3825dd91d9 100644 --- a/usr/src/man/man3c/getprogname.3c +++ b/usr/src/man/man3c/getprogname.3c @@ -31,27 +31,27 @@ .Sh DESCRIPTION The .Fn getprogname -function is used to obtain the program name. The program name is set at -program start-up, before +function is used to obtain the program name. +The program name is set at program start-up, before .Fn main -is called. Note, other operating systems, do not guarantee that a -program name has been set at start up time and therefore may return a -null pointer if +is called. +Note, other operating systems, do not guarantee that a program name has been set +at start up time and therefore may return a null pointer if .Fn setprogname has not been called. .Lp The .Fn setprogname -function is used to change the program name to another value. The -argument +function is used to change the program name to another value. +The argument .Fa progname must contain a null terminatd character string, whose last component which will become the new program name. .Sh RETURN VALUES The .Fn getprogname -function always returns the current program name. The program name is -always set, it will not return a null pointer. +function always returns the current program name. +The program name is always set, it will not return a null pointer. .Sh INTERFACE STABILITY .Sy Committed .Sh MT-LEVEL diff --git a/usr/src/man/man3c/getwd.3c b/usr/src/man/man3c/getwd.3c index 2e936e1668..9eec7b54f5 100644 --- a/usr/src/man/man3c/getwd.3c +++ b/usr/src/man/man3c/getwd.3c @@ -33,7 +33,8 @@ including the null byte, fails and returns a null pointer. .Sh RETURN VALUES Upon successful completion, a pointer to the string containing the absolute -pathname of the current working directory is returned. Otherwise, +pathname of the current working directory is returned. +Otherwise, .Fn getwd returns a null pointer and the contents of the array pointed to by .Fa path_name @@ -43,7 +44,8 @@ No errors are defined. .Sh USAGE The .Fn getwd -function is supplied for backwards compatibility. The +function is supplied for backwards compatibility. +The .Xr getcwd 3C should be used instead. .Sh INTERFACE STABILITY @@ -54,7 +56,8 @@ should be used instead. .Sh STANDARDS The .Fn getwd -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3c/mtx.3c b/usr/src/man/man3c/mtx.3c index 8283161d61..677bee08e0 100644 --- a/usr/src/man/man3c/mtx.3c +++ b/usr/src/man/man3c/mtx.3c @@ -56,8 +56,8 @@ The .Sy mtx family of functions implement mutual exclusion locks (mutexes) and behave similarly to both POSIX threads and illumos threads; however, they have -slightly different call signatures and return values. For more -information, see +slightly different call signatures and return values. +For more information, see .Xr threads 5 . Importantly, they do not allow for inter-process synchronization. .Ss Creating and Destroying Mutexes @@ -75,11 +75,12 @@ A simple, intra-process mutex. A simple, intra-process mutex, which allows timed locking operations. .It Sy mtx_plain | mtx_recursive An intra-process mutex that may be acquired recursively by the same -thread. It must be unlocked an equal number of times that it is locked. +thread. +It must be unlocked an equal number of times that it is locked. .It Sy mtx_timed | mtx_recursive An intra-process mutex that supports timed locking operations and may be -acquired recursively by the same thread. It must be unlocked an equal -number of times that it is locked. +acquired recursively by the same thread. +It must be unlocked an equal number of times that it is locked. .El For more information on the different kind of mutexes, see .Xr mutex_init 3C . @@ -101,8 +102,8 @@ function attempts to lock the mutex When the function returns, it will be the sole owner of the mutex and must call .Fn mtx_unlock -when it is done, or risk inducing a deadlock in the process. Other -threads that make calls to +when it is done, or risk inducing a deadlock in the process. +Other threads that make calls to .Fn mtx_lock after another thread has successfully completed its call to .Fn mtx_lock @@ -116,8 +117,9 @@ was created, a thread calling .Fn mtx_lock when it already holds .Fa mtx -will cause the thread to deadlock. Othewrise, the lock will be -successfully taken again. However, a thread must call +will cause the thread to deadlock. +Othewrise, the lock will be successfully taken again. +However, a thread must call .Fn mtx_unlock for each time that it has acquried .Fa mtx . @@ -154,9 +156,10 @@ The .Fn mtx_unlock function unlocks the mutex pointed to by .Fa mtx , -which allows another thread the opportunity to obtain it. If any threads -are actively blocking on the mutex, one of them will obtain it and be -woken up. It is an error to call +which allows another thread the opportunity to obtain it. +If any threads are actively blocking on the mutex, one of them will obtain it +and be woken up. +It is an error to call .Fn mtx_unlock on a mutex which the calling thread does not currently own. .Sh RETURN VALUES diff --git a/usr/src/man/man3c/pthread_attr_get_np.3c b/usr/src/man/man3c/pthread_attr_get_np.3c index 8ffb28c0fc..d6f4571d0d 100644 --- a/usr/src/man/man3c/pthread_attr_get_np.3c +++ b/usr/src/man/man3c/pthread_attr_get_np.3c @@ -29,17 +29,19 @@ The .Fn pthread_attr_get_np function provides a way to get the attributes of the thread .Fa thread -after it has been created. This function is most commonly used to obtain -the actual location and size of a thread's stack. +after it has been created. +This function is most commonly used to obtain the actual location and size of a +thread's stack. .Pp The attributes pointer, .Fa attr , -will be filled in with the current attributes for the thread. The -attributes should be allocated by a call to +will be filled in with the current attributes for the thread. +The attributes should be allocated by a call to .Xr pthread_attr_init 3C prior to calling the .Fn pthrad_attr_get_np -function. When +function. +When .Fa attr is done being used, it should be destroyed through a call to .Xr pthread_attr_destroy 3C . @@ -82,7 +84,8 @@ and it is the preferred interface for obtaining that information. The scheduling policy attribute of .Fa attr will be updated with the current scheduling policy being applied to the -thread. This may have changed, for example, due to a call to +thread. +This may have changed, for example, due to a call to .Xr pthread_setschedparam 3C . As with the thread's scheduling parameter, the preferred interface for obtaining this information is by using diff --git a/usr/src/man/man3c/pthread_mutex_consistent.3c b/usr/src/man/man3c/pthread_mutex_consistent.3c index cb45730cc4..e9e4e33d59 100644 --- a/usr/src/man/man3c/pthread_mutex_consistent.3c +++ b/usr/src/man/man3c/pthread_mutex_consistent.3c @@ -34,13 +34,14 @@ holding a robust lock exits, such as by calling .Xr exit 2 or .Xr thr_exit 3C , -or crashes without unlocking the lock. At that point, if another process -or thread is currently in a call, or calls +or crashes without unlocking the lock. +At that point, if another process or thread is currently in a call, or calls .Xr pthread_mutex_lock 3C , it will obtain the lock; however, the error code .Er EOWNERDEAD -will be returned. In such cases, that thread will own the lock and must -check and clean up any inconsistent state that is protected by the lock. +will be returned. +In such cases, that thread will own the lock and must check and clean up any +inconsistent state that is protected by the lock. When finished, it must call .Fn pthread_mutex_consistent to indicate that it is in a consistent state again. @@ -55,13 +56,14 @@ Upon successful completion, the .Fn pthread_mutex_consistent returns zero and marks .Va mutex -as consistent. Callers of +as consistent. +Callers of .Fn pthread_mutex_lock will not have .Er EOWNERDEAD -returned until another process or thread exits without unlocking. Upon -failure, an error will be returned which corresponds to one of the -errors listed below. +returned until another process or thread exits without unlocking. +Upon failure, an error will be returned which corresponds to one of the errors +listed below. .Sh ERRORS The .Fn pthread_mutex_consistent diff --git a/usr/src/man/man3c/pthread_mutexattr_getrobust.3c b/usr/src/man/man3c/pthread_mutexattr_getrobust.3c index cefcc73042..85b2b335c9 100644 --- a/usr/src/man/man3c/pthread_mutexattr_getrobust.3c +++ b/usr/src/man/man3c/pthread_mutexattr_getrobust.3c @@ -46,23 +46,24 @@ include: .It Sy PTHREAD_MUTEX_STALLED The mutex referred to by .Va attr -is a traditional mutex. When a thread holding an intra-process lock or a -process holding an inter-process lock crashes or terminates without -unlocking the mutex, then the lock will be +is a traditional mutex. +When a thread holding an intra-process lock or a process holding an +inter-process lock crashes or terminates without unlocking the mutex, then the +lock will be .Sy stalled . For another thread or process to obtain the lock, something else must unlock it. .It Sy PTHREAD_MUTEX_ROBUST The mutex referred to by .Va attr -is considered a robust mutex. When a process holding an inter-process -lock crashes or terminates without unlocking the mutex, the attempt to -lock it will return +is considered a robust mutex. +When a process holding an inter-process lock crashes or terminates without +unlocking the mutex, the attempt to lock it will return .Er EOWNERDEAD . This allows the new owner the chance to fix the internal state and call .Xr pthread_mutex_consistent 3C -prior to unlocking the lock, allowing normal operation to proceed. Any -crashes while in this state cause the next owner to obtain +prior to unlocking the lock, allowing normal operation to proceed. +Any crashes while in this state cause the next owner to obtain .Er EOWNERDEAD . .El .Sh RETURN VALUES @@ -72,8 +73,8 @@ function will return .Sy 0 and update .Fa robust -with the current value of the robust attribute. Upon successful -completion, the +with the current value of the robust attribute. +Upon successful completion, the .Fn pthread_mutexattr_setrobust function will return .Sy 0 @@ -82,7 +83,8 @@ and update the robust property of the attributes pointed to by to .Va robust . If either function fails, an error code will be returned to indicate the -error. Valid errors are defined below. +error. +Valid errors are defined below. .Sh ERRORS The .Fn pthread_mutexattr_getrobust diff --git a/usr/src/man/man3c/quick_exit.3c b/usr/src/man/man3c/quick_exit.3c index e3e17603b4..bcdb855854 100644 --- a/usr/src/man/man3c/quick_exit.3c +++ b/usr/src/man/man3c/quick_exit.3c @@ -51,7 +51,8 @@ will be called in reverse order upon calling .Fn quick_exit . Functions registered with .Fn at_quick_exit -will not be called at any other time. Functions that are registered with +will not be called at any other time. +Functions that are registered with .Fn at_quick_exit should not make use of .Xr longjump 3C @@ -70,8 +71,8 @@ The .Fn at_quick_exit function returns .Sy 0 -on success. Otherwise, a non-zero error value is returned to indicate -failure. +on success. +Otherwise, a non-zero error value is returned to indicate failure. .Sh ERRORS The .Fn at_quick_exit diff --git a/usr/src/man/man3c/select.3c b/usr/src/man/man3c/select.3c index 2cf0538f82..1752625126 100644 --- a/usr/src/man/man3c/select.3c +++ b/usr/src/man/man3c/select.3c @@ -125,7 +125,8 @@ The .Fn select function has no .Fa sigmask -argument. It behaves as +argument. +It behaves as .Fn pselect does when .Fa sigmask @@ -142,9 +143,9 @@ The .Fn select and .Fn pselect -functions support regular files, -terminal and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and -sockets. The behavior of +functions support regular files, terminal and pseudo-terminal devices, +STREAMS-based files, FIFOs, pipes, and sockets. +The behavior of .Fn select and .Fn pselect @@ -192,13 +193,13 @@ Upon successful completion, the objects pointed to by the .Fa writefs , and .Fa errorfds -arguments are modified to indicate which file -descriptors are ready for reading, ready for writing, or have an error -condition pending, respectively, and return the total number of ready -descriptors in all the output sets. For each file descriptor less than +arguments are modified to indicate which file descriptors are ready for reading, +ready for writing, or have an error condition pending, respectively, and return +the total number of ready descriptors in all the output sets. +For each file descriptor less than .Fa nfds , -the corresponding bit will be set on successful completion if it -was set on input and the associated condition is true for that file descriptor. +the corresponding bit will be set on successful completion if it was set on +input and the associated condition is true for that file descriptor. .Pp If none of the selected descriptors are ready for the requested operation, the .Fn select @@ -206,24 +207,29 @@ or .Fn pselect function blocks until at least one of the requested operations becomes ready, until the timeout occurs, or until -interrupted by a signal. The +interrupted by a signal. +The .Fa timeout parameter controls how long the .Fn select or .Fn pselect -function takes before timing out. If the +function takes before timing out. +If the .Fa timeout parameter is not a null pointer, it specifies a maximum interval -to wait for the selection to complete. If the specified time interval expires -without any requested operation becoming ready, the function returns. If the +to wait for the selection to complete. +If the specified time interval expires without any requested operation becoming +ready, the function returns. +If the .Fa timeout parameter is a null pointer, then the call to .Fn select or .Fn pselect blocks indefinitely until at least one descriptor meets the -specified criteria. To effect a poll, the +specified criteria. +To effect a poll, the .Fa timeout parameter should not be a null pointer, and should point to a zero-valued .Vt timespec @@ -251,9 +257,10 @@ A descriptor is considered ready for reading when a call to an input function with .Dv O_NONBLOCK clear would not block, whether or not the function would -transfer data successfully. (The function might return data, an end-of-file -indication, or an error other than one indicating that it is blocked, and in -each of these cases the descriptor will be considered ready for reading.) +transfer data successfully. +(The function might return data, an end-of-file indication, or an error other +than one indicating that it is blocked, and in each of these cases the +descriptor will be considered ready for reading.) .Pp A descriptor is considered ready for writing when a call to an output function with @@ -262,10 +269,12 @@ clear would not block, whether or not the function would transfer data successfully. .Pp If a socket has a pending error, it is considered to have an exceptional -condition pending. Otherwise, what constitutes an exceptional condition is file -type-specific. For a file descriptor for use with a socket, it is -protocol-specific except as noted below. For other file types, if the operation -is meaningless for a particular file type, +condition pending. +Otherwise, what constitutes an exceptional condition is file type-specific. +For a file descriptor for use with a socket, it is protocol-specific except as +noted below. +For other file types, if the operation is meaningless for a particular file +type, .Fn select or .Fn pselect @@ -276,39 +285,41 @@ If a descriptor refers to a socket, the implied input function is the .Xr recvmsg 3XNET function with parameters requesting normal and ancillary data, such that the presence of either type causes the socket to be marked as -readable. The presence of out-of-band data is checked if the socket option +readable. +The presence of out-of-band data is checked if the socket option .Dv SO_OOBINLINE has been enabled, as out-of-band data is enqueued with -normal data. If the socket is currently listening, then it is marked as -readable if an incoming connection request has been received, and a call to the -accept function completes without blocking. +normal data. +If the socket is currently listening, then it is marked as readable if an +incoming connection request has been received, and a call to the accept function +completes without blocking. .Pp If a descriptor refers to a socket, the implied output function is the .Xr sendmsg 3XNET function supplying an amount of normal data equal to the current value of the .Dv SO_SNDLOWAT -option for the socket. If a non-blocking -call to the connect function has been made for a socket, and the connection -attempt has either succeeded or failed leaving a pending error, the socket is -marked as writable. +option for the socket. +If a non-blocking call to the connect function has been made for a socket, and +the connection attempt has either succeeded or failed leaving a pending error, +the socket is marked as writable. .Pp A socket is considered to have an exceptional condition pending if a receive operation with .Dv O_NONBLOCK clear for the open file description and with the .Dv MSG_OOB -flag set would return out-of-band data without blocking. (It -is protocol-specific whether the +flag set would return out-of-band data without blocking. +(It is protocol-specific whether the .Dv MSG_OOB -flag would be used to read out-of-band data.) A socket will also be considered -to have an exceptional condition pending if an out-of-band data mark is -present in the receive queue. +flag would be used to read out-of-band data.) +A socket will also be considered to have an exceptional condition pending if an +out-of-band data mark is present in the receive queue. .Pp A file descriptor for a socket that is listening for connections will indicate -that it is ready for reading, when connections are available. A file -descriptor for a socket that is connecting asynchronously will indicate that it -is ready for writing, when a connection has been established. +that it is ready for reading, when connections are available. +A file descriptor for a socket that is connecting asynchronously will indicate +that it is ready for writing, when a connection has been established. .Pp Selecting true for reading on a socket descriptor upon which a .Xr listen 3XNET @@ -321,8 +332,10 @@ If the argument is not a null pointer, it points to an object of type .Vt struct timeval that specifies a maximum interval to wait for the -selection to complete. If the \fItimeout\fR argument points to an object of -type +selection to complete. +If the +.Fa timeout +argument points to an object of type .Vt struct timeval whose members are 0, .Fn select @@ -332,8 +345,9 @@ If the argument is a null pointer, .Fn select blocks until an event causes one of the masks to be returned with a valid -(non-zero) value. If the time limit expires before any event occurs that -would cause one of the masks to be set to a non-zero value, +(non-zero) value. +If the time limit expires before any event occurs that would cause one of the +masks to be set to a non-zero value, .Fn select completes successfully and returns 0. .Pp @@ -349,7 +363,8 @@ argument is not a null pointer, or .Fn pselect blocks for the time specified, or until interrupted by a -signal. If the +signal. +If the .Fa readfds , .Fa writefds , and @@ -368,9 +383,9 @@ On failure, the objects pointed to by the .Fa writefds , and .Fa errorfds -arguments are not modified. If the timeout interval expires -without the specified condition being true for any of the specified file -descriptors, the objects pointed to by the +arguments are not modified. +If the timeout interval expires without the specified condition being true for +any of the specified file descriptors, the objects pointed to by the .Fa readfds , .Fa writefds , and @@ -422,7 +437,8 @@ On successful completion, and .Fn pselect return the total -number of bits set in the bit masks. Otherwise, +number of bits set in the bit masks. +Otherwise, .Sy 1 is returned and .Dv errno diff --git a/usr/src/man/man3c/signalfd.3c b/usr/src/man/man3c/signalfd.3c index fecd46e124..070bafc854 100644 --- a/usr/src/man/man3c/signalfd.3c +++ b/usr/src/man/man3c/signalfd.3c @@ -30,14 +30,15 @@ The .Fn signalfd function returns a file descriptor that can be used -for synchronous consumption of signals. The file descriptor can be operated -upon via +for synchronous consumption of signals. +The file descriptor can be operated upon via .Xr read 2 and the facilities that notify of file descriptor activity (e.g. .Xr poll 2 , .Xr port_get 3C , .Xr epoll_wait 3C -). To dispose of the instance +). +To dispose of the instance .Xr close 2 should be called on the file descriptor. .Pp @@ -72,7 +73,8 @@ see description for in .Xr open 2 . .It Sy SFD_NONBLOCK -Instance will be set to be non-blocking. A +Instance will be set to be non-blocking. +A .Xr read 2 on a signalfd instance that has been initialized with .Fa SFD_NONBLOCK , @@ -85,10 +87,10 @@ that are pending. .Pp As with .Xr sigwait 2 , -reading a signal from the file descriptor will consume the signal. The signals -used with signalfd file descriptors are normally first blocked so that their -handler does not run when a signal arrives. If the signal is not blocked the -behavior matches that of +reading a signal from the file descriptor will consume the signal. +The signals used with signalfd file descriptors are normally first blocked so +that their handler does not run when a signal arrives. +If the signal is not blocked the behavior matches that of .Xr sigwait 2 ; if a .Xr read 2 @@ -154,19 +156,21 @@ typedef struct signalfd_siginfo { File descriptor duplication during fork presents a challenge to the .Sy signalfd facility since signal data and events are dependent on the process from which -they are queried. Its use with caching event systems such as +they are queried. +Its use with caching event systems such as .Xr epoll 5 , -.Sy /dev/poll , +.Pa /dev/poll , or .Xr port_create 3C can result in undefined behavior if signalfd and polling descriptors are used -together after being shared across a fork. Such restrictions do not apply if -the child only calls +together after being shared across a fork. +Such restrictions do not apply if the child only calls .Xr close 2 on the descriptors. .Sh RETURN VALUES Upon successful completion, a file descriptor associated with the instance -is returned. Otherwise, -1 is returned and errno is set to indicate the error. +is returned. +Otherwise, -1 is returned and errno is set to indicate the error. When .Va fd is not -1 and there is no error, the value of diff --git a/usr/src/man/man3c/smt_pause.3c b/usr/src/man/man3c/smt_pause.3c index 495d3b78d1..815a21f40e 100644 --- a/usr/src/man/man3c/smt_pause.3c +++ b/usr/src/man/man3c/smt_pause.3c @@ -26,10 +26,10 @@ .Sh DESCRIPTION The .Fn smt_pause -function performs a busy-wait for an implementation defined period of -time. On hardware platforms that support it, it notifies the hardware -that this is occurring in an effort to minimize resource usage. This is -commonly used in the implementation of spin loops. +function performs a busy-wait for an implementation defined period of time. +On hardware platforms that support it, it notifies the hardware that this is +occurring in an effort to minimize resource usage. +This is commonly used in the implementation of spin loops. .Sh INTERFACE STABILITY .Sy Committed .Sh MT-LEVEL diff --git a/usr/src/man/man3c/thrd_create.3c b/usr/src/man/man3c/thrd_create.3c index ffaf9bf11c..fd31e740b7 100644 --- a/usr/src/man/man3c/thrd_create.3c +++ b/usr/src/man/man3c/thrd_create.3c @@ -39,11 +39,11 @@ When a thread is created, it begins its execution at the function with the argument .Fa arg . A created thread has access to all global data within a process; -however, it has its own private stack. Currently 32-bit processes have a -default stack of 1 megabyte, while 64-bit systems have a default stack -size of 2 megabytes. In addition, newly created threads inherit the -signal mask of the thread which created them; however, they do not -inherit any pending signals. +however, it has its own private stack. +Currently 32-bit processes have a default stack of 1 megabyte, while 64-bit +systems have a default stack size of 2 megabytes. +In addition, newly created threads inherit the signal mask of the thread which +created them; however, they do not inherit any pending signals. .Pp Once created, a thread will continue to execute until either, it returns from its initial function, the thread explicitly calls @@ -51,9 +51,9 @@ from its initial function, the thread explicitly calls or the process itself terminates, such as with a call to .Xr exit 2 . When the initial function returns, it behaves as though a call to -.Xr thrd_exit +.Xr thrd_exit 3C was made, and, if the thread has not been detached with a call to -.Xr thrd_detach, +.Xr thrd_detach 3C , the exit status remains available and the corresponding thread ID will not be reused until a process calls .Xr thrd_join 3C . @@ -74,7 +74,8 @@ function returns .Sy thrd_success . If insufficient memory was available, then .Sy thrd_nomem -is returned. Otherwise, +is returned. +Otherwise, .Sy thrd_error is returned, indicating that a non-memory related error. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3c/thrd_current.3c b/usr/src/man/man3c/thrd_current.3c index 9cc41795ab..6b4fc3e53d 100644 --- a/usr/src/man/man3c/thrd_current.3c +++ b/usr/src/man/man3c/thrd_current.3c @@ -26,8 +26,8 @@ .Sh DESCRIPTION The .Fn thrd_current -function returns the thread ID of the current calling thread. Note, this -ID may be different from the thread ID returned when using +function returns the thread ID of the current calling thread. +Note, this ID may be different from the thread ID returned when using .Xr thr_self 3C or .Xr pthread_self 3C ; diff --git a/usr/src/man/man3c/thrd_detach.3c b/usr/src/man/man3c/thrd_detach.3c index 8749b53c1b..4f19042c2c 100644 --- a/usr/src/man/man3c/thrd_detach.3c +++ b/usr/src/man/man3c/thrd_detach.3c @@ -28,17 +28,19 @@ The .Fn thrd_detach function causes a thread to be considered detached from the rest of the -execution environment. While detached threads are still fully -observable, they cannot be joined with, calls to +execution environment. +While detached threads are still fully observable, they cannot be joined with, +calls to .Fn thrd_join -will fail. In addition, if all non-detached -threads have terminated, the program will terminate; detached threads -cannot keep a program running. The act of calling +will fail. +In addition, if all non-detached threads have terminated, the program will +terminate; detached threads cannot keep a program running. +The act of calling .Fn thrd_detach on a thread does not cause it to terminate. .Sh RETURN VALUES Upon successful completion, the -.Xr thrd_detach +.Xr thrd_detach 3C function returns .Sy thrd_success . Otherwise, it returns diff --git a/usr/src/man/man3c/thrd_equal.3c b/usr/src/man/man3c/thrd_equal.3c index 86e5a22ef3..1712bbb6f9 100644 --- a/usr/src/man/man3c/thrd_equal.3c +++ b/usr/src/man/man3c/thrd_equal.3c @@ -41,9 +41,8 @@ if .Fa thrd0 and .Fa thrd1 -refer to the same thread. Otherwise, -.Sy 0 -is returned, indicating that +refer to the same thread. +Otherwise, a non-zero value is returned, indicating that .Fa thrd0 and .Fa thrd1 diff --git a/usr/src/man/man3c/thrd_exit.3c b/usr/src/man/man3c/thrd_exit.3c index 3dcf682cd9..58a91a6475 100644 --- a/usr/src/man/man3c/thrd_exit.3c +++ b/usr/src/man/man3c/thrd_exit.3c @@ -28,8 +28,9 @@ The .Fn thrd_exit function terminates the calling thread, in a similar way that .Xr exit 3C -terminates the calling process. If the calling thread has not been -detached, then the exit status information provided in +terminates the calling process. +If the calling thread has not been detached, then the exit status information +provided in .Fa res is saved and can be retrieved by the use of the .Xr thrd_join 3C diff --git a/usr/src/man/man3c/thrd_join.3c b/usr/src/man/man3c/thrd_join.3c index d2cb8c83ea..52a7d8bd33 100644 --- a/usr/src/man/man3c/thrd_join.3c +++ b/usr/src/man/man3c/thrd_join.3c @@ -36,10 +36,12 @@ for that thread in .Fa res , if .Fa res -is non-null. The +is non-null. +The .Fa thrd argument must be a member of the current process and it cannot be -detached. If +detached. +If .Fa thrd has already terminated and another caller has not called .Fn thrd_join @@ -65,7 +67,7 @@ function returns and if .Fa res is a non-null pointer, it will be filled in with the exit status of -.Xr thrd . +.Xr thrd 3C . If an error occurs, .Sy thrd_error will be returned. diff --git a/usr/src/man/man3c/timerfd_create.3c b/usr/src/man/man3c/timerfd_create.3c index 432717f6e9..5f2bdcd2c2 100644 --- a/usr/src/man/man3c/timerfd_create.3c +++ b/usr/src/man/man3c/timerfd_create.3c @@ -80,7 +80,8 @@ description of .Ed .It Sy TFD_NONBLOCK .Bd -filled -compact -Instance will be set to be non-blocking. A +Instance will be set to be non-blocking. +A .Xr read 2 on a .Sy timerfd @@ -109,8 +110,8 @@ or .Fn timerfd_settime . Upon success, the number of expirations will be copied into the eight byte buffer -passed to the system call. If there have been no expirations of the -timer since the last successful +passed to the system call. +If there have been no expirations of the timer since the last successful .Xr read 2 or .Fn timerfd_sttime , @@ -165,7 +166,8 @@ same functional signature and semantics as .El .Sh RETURN VALUES Upon successful completion, a file descriptor associated with the instance -is returned. Otherwise, +is returned. +Otherwise, .Sy -1 is returned and errno is set to indicate the error. .Sh ERRORS diff --git a/usr/src/man/man3c/timespec_get.3c b/usr/src/man/man3c/timespec_get.3c index 7ae55f7b55..532af5ce3c 100644 --- a/usr/src/man/man3c/timespec_get.3c +++ b/usr/src/man/man3c/timespec_get.3c @@ -27,15 +27,16 @@ .Sh DESCRIPTION The .Fn timespec_get -function provides access nanosecond resolution time. The -meaning and source of time is defined by the +function provides access nanosecond resolution time. +The meaning and source of time is defined by the .Fa base -argument. The following values are defined for +argument. +The following values are defined for .Fa base : .Bl -tag -width Ds .It Sy TIME_UTC -Obtain the current time of day from the realtime clock on the system. It -represents the amount of time in second and nanoseconds since the Epoch. +Obtain the current time of day from the realtime clock on the system. +It represents the amount of time in second and nanoseconds since the Epoch. This is logically equivalent to calling .Xr clock_gettime 3C with diff --git a/usr/src/man/man3c/tss.3c b/usr/src/man/man3c/tss.3c index 6e4b696339..9f8fde3912 100644 --- a/usr/src/man/man3c/tss.3c +++ b/usr/src/man/man3c/tss.3c @@ -50,20 +50,21 @@ storage. .Ss Creating and Destorying Thread-Specific Storage The .Fn tss_create -function creates a new thread-specific data key. The key space is opaque -and global to all threads in the process. Each thread has its own -value-space which can be manipulated with the +function creates a new thread-specific data key. +The key space is opaque and global to all threads in the process. +Each thread has its own value-space which can be manipulated with the .Fn tss_get and .Fn tss_set -functions. A given key persists until +functions. +A given key persists until .Fn tss_destroy is called. .Pp When a key is created, the value .Dv NULL -is associated with all current threads. When a thread is created, the -value +is associated with all current threads. +When a thread is created, the value .Dv NULL is assigned as the value for the entire key-space. .Pp @@ -75,20 +76,22 @@ will run when the thread exits (see .Xr thrd_exit 3C ) if the value for the key is not .Dv NULL . -The key space's destructors may be run in any order. When the destructor -is run due to a thread exiting, all signals will be blocked. +The key space's destructors may be run in any order. +When the destructor is run due to a thread exiting, all signals will be blocked. .Pp The .Fn tss_delete function deletes the key identify by .Fa key -from the global name-space. When a key is deleted, no registered -destructor is called, it is up to the calling program to free any -storage that was associated with +from the global name-space. +When a key is deleted, no registered destructor is called, it is up to the +calling program to free any storage that was associated with .Fa key -across all threads. Because of this propety, it is legal to call +across all threads. +Because of this propety, it is legal to call .Fn tss_delete -from inside a destructor. Any destructors that had been assocaited with +from inside a destructor. +Any destructors that had been assocaited with .Fa key will no longer be called when a thread terminates. .Ss Obtaining Values @@ -96,8 +99,9 @@ The .Fn tss_get function may be used to obtain the value associated with .Fa key -for the calling thread. Note that if the calling thread has never set a -value, then it will receive the default value, +for the calling thread. +Note that if the calling thread has never set a value, then it will receive the +default value, .Dv NULL . .Fn tss_get may be called from a tss destructor. @@ -116,7 +120,8 @@ in as .Fa value . Changing the value of a key with .Fn tss_set -does not cause any destructors to be invoked. This means that +does not cause any destructors to be invoked. +This means that .Fn tss_set may be used in the context of a destructor, but special care must be taken to avoid leaking storage or causing an infinite loop. diff --git a/usr/src/man/man3c/ualarm.3c b/usr/src/man/man3c/ualarm.3c index 269d5ebe8f..87273ae88a 100644 --- a/usr/src/man/man3c/ualarm.3c +++ b/usr/src/man/man3c/ualarm.3c @@ -23,11 +23,15 @@ function causes the signal to be generated for the calling process after the number of real-time microseconds specified by the .Fa useconds -argument has elapsed. When the +argument has elapsed. +When the .Fa interval argument is non-zero, repeated timeout notification occurs with a period in microseconds -specified by the \fIinterval\fR argument. If the notification signal, +specified by the +.Fa interval +argument. +If the notification signal, .Dv SIGALRM , is not caught or ignored, the calling process is terminated. .Lp @@ -47,7 +51,8 @@ The function returns the number of microseconds remaining from the previous .Fn ualarm -call. If no timeouts are pending or if +call. +If no timeouts are pending or if .Fn ualarm has not previously been called, .Fn ualarm @@ -61,7 +66,8 @@ function is a simplified interface to .Xr setitimer 2 , and uses the .Dv ITIMER_REAL -interval timer. It's use has been deprecated in favor of the +interval timer. +It's use has been deprecated in favor of the .Xr timer_create 3C family of functions. .Sh INTERFACE STABILITY @@ -79,7 +85,8 @@ family of functions. .Sh STANDARDS The .Fn ualarm -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3c/usleep.3c b/usr/src/man/man3c/usleep.3c index bde0508ec2..e26f1a534c 100644 --- a/usr/src/man/man3c/usleep.3c +++ b/usr/src/man/man3c/usleep.3c @@ -22,12 +22,13 @@ The function suspends the caller from execution for the number of microseconds specified by the .Fa useconds -argument. The actual suspension -time might be less than requested because any caught signal will terminate +argument. +The actual suspension time might be less than requested because any caught +signal will terminate .Fn usleep -following execution of that signal's catching routine. The -suspension time might be longer than requested by an arbitrary amount because -of the scheduling of other activity in the system. +following execution of that signal's catching routine. +The suspension time might be longer than requested by an arbitrary amount +because of the scheduling of other activity in the system. .Lp If the value of .Fa useconds @@ -36,18 +37,21 @@ is 0, then the call has no effect. The use of the usleep function has no effect on the action or blockage -of any signal. In a multithreaded process, only the invoking thread is -suspended from execution. +of any signal. +In a multithreaded process, only the invoking thread is suspended from +execution. .Sh RETURN VALUES On completion, .Fn usleep -returns 0. There are no error returns. +returns 0. +There are no error returns. .Sh ERRORS No errors are returned. .Sh USAGE The .Fn usleep -function is included for its historical usage and is Obsolete. The +function is included for its historical usage and is Obsolete. +The .Xr nanosleep 3C function is preferred over this function. .Sh INTERFACE STABILITY @@ -62,7 +66,8 @@ function is preferred over this function. .Sh STANDARDS The .Fn usleep -function is available in the following compilation environments. See +function is available in the following compilation environments. +See .Xr standards 5 . .Lp .Bl -bullet -compact diff --git a/usr/src/man/man3c/wcpcpy.3c b/usr/src/man/man3c/wcpcpy.3c index b4a5ecad8e..203164992f 100644 --- a/usr/src/man/man3c/wcpcpy.3c +++ b/usr/src/man/man3c/wcpcpy.3c @@ -48,7 +48,8 @@ of .Fn wcpncpy , after .Fa n -wide-characters have been copied. If +wide-characters have been copied. +If .Fa ws2 contains fewer than .Fa n @@ -89,8 +90,8 @@ The .Fn wcpcpy and .Fn wcpncpy -functions return a pointer to the last wide-character written. In the -case of +functions return a pointer to the last wide-character written. +In the case of .Fn wcpncpy this will always be equal to .Po Fa ws1 Li + Fa n Li \(mi 1 Pc . diff --git a/usr/src/man/man3c/wcscasecmp.3c b/usr/src/man/man3c/wcscasecmp.3c index d8af330cf7..f55d18dfd0 100644 --- a/usr/src/man/man3c/wcscasecmp.3c +++ b/usr/src/man/man3c/wcscasecmp.3c @@ -60,10 +60,10 @@ Pairs of wide-characters from each of .Fa ws1 and .Fa ws2 -are compared consecutively, ignoring differences in case (if the -.\"POSIX\." locale upper case characters are treated as lower case). If -the two values are different, the comparison stops and either -a negative value is returned if the character from +are compared consecutively, ignoring differences in case (if the "POSIX" locale +upper case characters are treated as lower case). +If the two values are different, the comparison stops and either a negative +value is returned if the character from .Fa ws1 is less than that from .Fa ws2 , @@ -78,8 +78,8 @@ and .Fn wcsncasecmp_l , after .Fa n -comparisons have been made without finding a difference. In either of -these two cases, 0 is returned. +comparisons have been made without finding a difference. +In either of these two cases, 0 is returned. .Lp The .Fn wcscasecmp @@ -87,7 +87,8 @@ and .Fn wcsncasecmp functions use the .Dv LC_CTYPE -category of the current locale to determine case. The +category of the current locale to determine case. +The .Fn wcscasecmp_l and .Fn wcsncasecmp_l diff --git a/usr/src/man/man3c/wcsdup.3c b/usr/src/man/man3c/wcsdup.3c index 80113744a9..f9692ca5b5 100644 --- a/usr/src/man/man3c/wcsdup.3c +++ b/usr/src/man/man3c/wcsdup.3c @@ -33,9 +33,11 @@ function duplicates a wide-character allocating sufficient memory to store the copy, and then copying from .Fa string . -The resulting copy is returned. It may be deallocated with +The resulting copy is returned. +It may be deallocated with .Xr free 3C -when it is no longer needed. The +when it is no longer needed. +The .Fn wcsdup function is the wide-character equivalent of .Xr strdup 3C . diff --git a/usr/src/man/man3head/endian.h.3head b/usr/src/man/man3head/endian.h.3head index 0fe5931751..b84a48b47f 100644 --- a/usr/src/man/man3head/endian.h.3head +++ b/usr/src/man/man3head/endian.h.3head @@ -37,22 +37,25 @@ The header defines the following macros: .Bl -tag -width Ds .It Sy LITTLE_ENDIAN -A constant used to indicate a little-endian integer. It is always -defined, regardless of the actual endianess of the underlying platform. +A constant used to indicate a little-endian integer. +It is always defined, regardless of the actual endianess of the underlying +platform. This macro should be used to compare against the .Sy BYTE_ORDER macro. .It Sy BIG_ENDIAN -A constant used to indicate a big-endian integer. It is always defined, -regardless of the actual endianess of the underlying platform. This -macro should be used to compare against the +A constant used to indicate a big-endian integer. +It is always defined, regardless of the actual endianess of the underlying +platform. +This macro should be used to compare against the .Sy BYTE_ORDER macro. .It Sy PDP_ENDIAN A constant used to indicate the endianness used for four byte values on -the PDP-11. It is always defined, regardless of the actual endianess of -the underlying platform. This macro should be used to compare against -the +the PDP-11. +It is always defined, regardless of the actual endianess of the underlying +platform. +This macro should be used to compare against the .Sy BYTE_ORDER macro. .It Sy BYTE_ORDER diff --git a/usr/src/man/man3lib/libavl.3lib b/usr/src/man/man3lib/libavl.3lib index 6b65f387fe..bcb9c2c50e 100644 --- a/usr/src/man/man3lib/libavl.3lib +++ b/usr/src/man/man3lib/libavl.3lib @@ -24,10 +24,10 @@ The .Nm library provides a generic implementation of AVL trees, a form of -self-balancing binary tree. The interfaces provided allow for an -efficient way of implementing an ordered set of data structures and, due -to its embeddable nature, allow for a single instance of a data -structure to belong to multiple AVL trees. +self-balancing binary tree. +The interfaces provided allow for an efficient way of implementing an ordered +set of data structures and, due to its embeddable nature, allow for a single +instance of a data structure to belong to multiple AVL trees. .Lp Each AVL tree contains entries of a single type of data structure. Rather than allocating memory for pointers for those data structures, @@ -38,17 +38,18 @@ When an AVL tree is created, through the use of .Fn avl_create , it encodes the size of the data structure, the offset of the data structure, and a comparator function which is used to compare two -instances of a data structure. A data structure may be a member of -multiple AVL trees by creating AVL trees which use different -offsets (different members) into the data structure. +instances of a data structure. +A data structure may be a member of multiple AVL trees by creating AVL trees +which use different offsets (different members) into the data structure. .Lp AVL trees support both look up of an arbitrary item and ordered -iteration over the contents of the entire tree. In addition, from any -node, you can find the previous and next entries in the tree, if they -exist. In addition, AVL trees support arbitrary insertion and deletion. +iteration over the contents of the entire tree. +In addition, from any node, you can find the previous and next entries in the +tree, if they exist. +In addition, AVL trees support arbitrary insertion and deletion. .Ss Performance -AVL trees are often used in place of linked lists. Compared to the -standard, intrusive, doubly linked list, it has the following +AVL trees are often used in place of linked lists. +Compared to the standard, intrusive, doubly linked list, it has the following performance characteristics: .Bl -hang -width Ds .It Sy Lookup One Node @@ -66,10 +67,10 @@ Inserting a single node into an AVL tree is .Sy O(log(n)) . .Pp Note, insertions into an AVL tree always result in an ordered tree. -Insertions into a linked list do not guarantee order. If order is -required, then the time to do the insertion into a linked list will -depend on the time of the search algorithm being employed to find the -place to insert at. +Insertions into a linked list do not guarantee order. +If order is required, then the time to do the insertion into a linked list will +depend on the time of the search algorithm being employed to find the place to +insert at. .Ed .It Sy Delete One Node .Bd -filled -compact @@ -114,10 +115,11 @@ present. .Sh INTERFACES The shared object .Sy libavl.so.1 -provides the public interfaces defined below. See -.Xr Intro(3) -for additional information on shared object interfaces. Individual -functions are documented in their own manual pages. +provides the public interfaces defined below. +See +.Xr Intro 3 +for additional information on shared object interfaces. +Individual functions are documented in their own manual pages. .Bl -column -offset indent ".Sy avl_is_empty" ".Sy avl_destroy_nodes" .It Sy avl_add Ta Sy avl_create .It Sy avl_destroy Ta Sy avl_destroy_nodes @@ -144,29 +146,34 @@ library defines the following types: .Lp .Sy avl_tree_t .Lp -Type used for the root of the AVL tree. Consumers define one of these -for each of the different trees that they want to have. +Type used for the root of the AVL tree. +Consumers define one of these for each of the different trees that they want to +have. .Lp .Sy avl_node_t .Lp -Type used as the data node for an AVL tree. One of these is embedded in -each data structure that is the member of an AVL tree. +Type used as the data node for an AVL tree. +One of these is embedded in each data structure that is the member of an AVL +tree. .Lp .Sy avl_index_t .Lp -Type used to locate a position in a tree. This is used with +Type used to locate a position in a tree. +This is used with .Xr avl_find 3AVL and .Xr avl_insert 3AVL . .Sh LOCKING The .Nm -library provides no locking. Callers that are using the same AVL tree -from multiple threads need to provide their own synchronization. If only -one thread is ever accessing or modifying the AVL tree, then there are -no synchronization concerns. If multiple AVL trees exist, then they may -all be used simultaneously; however, they are subject to the same rules -around simultaneous access from a single thread. +library provides no locking. +Callers that are using the same AVL tree from multiple threads need to provide +their own synchronization. +If only one thread is ever accessing or modifying the AVL tree, then there are +no synchronization concerns. +If multiple AVL trees exist, then they may all be used simultaneously; however, +they are subject to the same rules around simultaneous access from a single +thread. .Lp All routines are both .Sy Fork-safe diff --git a/usr/src/man/man3lib/libpkcs11.3lib b/usr/src/man/man3lib/libpkcs11.3lib index fb9581ee80..b065411f3c 100644 --- a/usr/src/man/man3lib/libpkcs11.3lib +++ b/usr/src/man/man3lib/libpkcs11.3lib @@ -26,20 +26,23 @@ slots. .Lp The .Nm -library provides a special slot called the meta slot. The -meta slot provides a virtual union of capabilities of all other slots. When -available, the meta slot is always the first slot provided by +library provides a special slot called the meta slot. +The meta slot provides a virtual union of capabilities of all other slots. +When available, the meta slot is always the first slot provided by .Nm . .Lp The meta slot feature can be configured either system-wide or by individual -users. System-wide configuration for meta slot features is done with the +users. +System-wide configuration for meta slot features is done with the .Xr cryptoadm 1M -utility. User configuration for meta slot features is -performed with environment variables. +utility. +User configuration for meta slot features is performed with environment +variables. .Lp -By default, the following is the system-wide configuration for meta slot. Meta -slot is enabled. Meta slot provides token-based object support with the -Software RSA PKCS#11 softtoken +By default, the following is the system-wide configuration for meta slot. +Meta slot is enabled. +Meta slot provides token-based object support with the Software RSA PKCS#11 +softtoken .Pf ( Xr pkcs11_softtoken 5 ) . Meta slot is allowed to move sensitive token objects to other slots if that is necessary to @@ -52,12 +55,13 @@ The .Ev ${METASLOT_OBJECTSTORE_SLOT} and .Ev ${METASLOT_OBJECTSTORE_TOKEN} -environment variables are used to specify an alternate token object store. A -user can specify either slot-description in +environment variables are used to specify an alternate token object store. +A user can specify either slot-description in .Ev ${METASLOT_OBJECTSTORE_SLOT} or token-label in -.Ev ${METASLOT_OBJECTSTORE_TOKEN} , or both. Valid values -for slot-description and token-label are available from output of the command: +.Ev ${METASLOT_OBJECTSTORE_TOKEN} , or both. +Valid values for slot-description and token-label are available from output of +the command: .Bd -literal -offset indent # cryptoadm list -v .Ed @@ -65,29 +69,32 @@ for slot-description and token-label are available from output of the command: The .Ev ${METASLOT_ENABLED} environment variable is used to specify whether -the user wants to turn the metaslot feature on or off. Only two values are -recognized. The value "true" means meta slot will be on. The value "false" -means meta slot will be off. +the user wants to turn the metaslot feature on or off. +Only two values are recognized. +The value "true" means meta slot will be on. +The value "false" means meta slot will be off. .Lp The .Ev ${METASLOT_AUTO_KEY_MIGRATE} environment variable is used to specify whether the user wants sensitive token objects to move to other slots for -cryptographic operations. Only two values are recognized. The value "true" -means meta slot will migrate sensitive token objects to other slots if -necessary. The value "false" means meta slot will not migrate sensitive token -objects to other slots even if it is necessary. +cryptographic operations. +Only two values are recognized. +The value "true" means meta slot will migrate sensitive token objects to other +slots if necessary. +The value "false" means meta slot will not migrate sensitive token objects to +other slots even if it is necessary. .Lp When the meta slot feature is enabled, the slot that provides token-based -object support is not shown as one of the available slots. All of its -functionality can be used with the meta slot. +object support is not shown as one of the available slots. +All of its functionality can be used with the meta slot. .Lp This library filters the list of mechanisms available from plug-ins based on the policy set by .Xr cryptoadm 1M . .Lp -This library provides entry points for all PKCS#11 v2.40 functions. See the -PKCS#11 v2.40 specifications at +This library provides entry points for all PKCS#11 v2.40 functions. +See the PKCS#11 v2.40 specifications at .Lk http://www.oasis-open.org. .Lp Plug-ins are added to @@ -123,16 +130,18 @@ utility. .Lp The .In security/pkcs11f.h -header contains function definitions. The +header contains function definitions. +The .In security/pkcs11t.h -header contains type definitions. Applications can -include either of these headers in place of +header contains type definitions. +Applications can include either of these headers in place of .In security/pkcs11.h , which contains both function and type definitions. .Sh INTERFACES The shared object .Lb libpkcs11.so.1 -provides the public interfaces defined below. See +provides the public interfaces defined below. +See .Xr Intro 3 for additional information on shared object interfaces. .Ss "PKCS#11 Standard" @@ -193,10 +202,10 @@ for descriptions of the following attributes: .Sh INTERFACE STABILITY .Sy Committed .Sh MT-LEVEL -The SUNW Extension functions are MT-Safe. The PKCS#11 Standard functions are -MT-Safe with exceptions. See Section 2.5.3 of PKCS#11 Cryptographic Token Usage -Guide v2.40 and Section 5.1.5 of PKCS#11 Cryptographic Token Interface Base -Standard v2.40 +The SUNW Extension functions are MT-Safe. +The PKCS#11 Standard functions are MT-Safe with exceptions. +See Section 2.5.3 of PKCS#11 Cryptographic Token Usage Guide v2.40 and +Section 5.1.5 of PKCS#11 Cryptographic Token Interface Base Standard v2.40 .Sh STANDARD The PKCS#11 Standard functions conform to PKCS#11 Cryptographic Token Interface Profiles v2.40 Extended Provider. @@ -228,7 +237,8 @@ without the .Dv CKF_DONT_BLOCK flag set, .Nm -must create threads internally. If, however, +must create threads internally. +If, however, .Dv CKF_LIBRARY_CANT_CREATE_OS_THREADS is set, .Fn C_WaitForSlotEvent diff --git a/usr/src/man/man3lib/libproc.3lib b/usr/src/man/man3lib/libproc.3lib index c45504a7e5..ba71e5f2b9 100644 --- a/usr/src/man/man3lib/libproc.3lib +++ b/usr/src/man/man3lib/libproc.3lib @@ -24,9 +24,9 @@ The .Nm library provides consumers a general series of interfaces to inspect -and control both live processes and core files. It is intended for -introspection tools such as debuggers by providing a high-level -interface to the /proc file system +and control both live processes and core files. +It is intended for introspection tools such as debuggers by providing a +high-level interface to the /proc file system .Pf ( Xr proc 4 ) . .Pp The @@ -54,17 +54,18 @@ Various utilities to support debugging tools. The .Nm library can be used to manipulate running processes and to create new -ones. To manipulate an existing process first +ones. +To manipulate an existing process first .Em grab it with the .Em Pgrab -function. A process is generally stopped as a side effect of grabbing -it. Callers must exercise caution, as if they do not use the library -correctly, or they terminate unexpectedly, a process may remain -stopped. +function. +A process is generally stopped as a side effect of grabbing it. +Callers must exercise caution, as if they do not use the library correctly, or +they terminate unexpectedly, a process may remain stopped. .Pp -Unprivileged users may only grab their own processes. Users with the -privilege +Unprivileged users may only grab their own processes. +Users with the privilege .Sy PRIV_PROC_OWNER may manipulate processes that they do not own; however, additional restrictions as described in @@ -81,37 +82,38 @@ the library. The .Nm library has the ability to open and interpret core files produced by -processes on the system. Process core dump generation is controlled by -the +processes on the system. +Process core dump generation is controlled by the .Xr coreadm 1M -command. In addition, the library has the ability to understand and -interpret core dumps generated by Linux kernel and can provide a subset -of its functionality on such core files, provided the original binary is -also present. +command. +In addition, the library has the ability to understand and interpret core dumps +generated by Linux kernel and can provide a subset of its functionality on such +core files, provided the original binary is also present. .Pp Not all functions in the .Nm -library are valid for core files. In general, none of the commands -which manipulate the current state of a process or thread or that try -to force system calls on a victim process will work. Furthermore -several of the information and iteration interfaces are limited based -on the data that is available in the core file. For example, if the -core file is of a process that omits the frame pointer, the ability to -iterate the stack will be limited. +library are valid for core files. +In general, none of the commands which manipulate the current state of a process +or thread or that try to force system calls on a victim process will work. +Furthermore several of the information and iteration interfaces are limited +based on the data that is available in the core file. +For example, if the core file is of a process that omits the frame pointer, the +ability to iterate the stack will be limited. .Pp Use the .Fn Pgrab_core or .Fn Pfgrab_core -function to open a core file. Use the +function to open a core file. +Use the .Fn Pgrab_file function to open an ELF object file. This is useful for obtaining information stored in ELF headers and sections. .Ss Debug Information Many of the operations in the library rely on debug information being -present in a process and its associated libraries. The library -leverages symbol table information, CTF data +present in a process and its associated libraries. +The library leverages symbol table information, CTF data .Pf ( Xr CTF 4 ) sections, and frame unwinding information based on the use of an ABI defined frame pointer, eg. @@ -122,11 +124,11 @@ on x86 systems. .Pp Some software providers strip programs of this information or build their executables such that the information will not be present in a -core dump. To deal with this fact, the library is able to consume -information that is not present in the core file or the running -process. It can both consume it from the underlying executable and it -also supports finding it from related ELF objects that are linked to -it via the +core dump. +To deal with this fact, the library is able to consume information that is not +present in the core file or the running process. +It can both consume it from the underlying executable and it also supports +finding it from related ELF objects that are linked to it via the .Sy .gnu_debuglink and the .Sy .note.gnu.build-id @@ -160,13 +162,15 @@ File Descriptors The .Nm library allows the caller to force system calls to be executed in the -context of the running process. This can be used both as a tool for -introspection, allowing one to get information outside its current -context as well as performing modifications to a process. +context of the running process. +This can be used both as a tool for introspection, allowing one to get +information outside its current context as well as performing modifications to a +process. .Pp -These functions run in the context of the calling process. This is -often an easier way of getting non-exported information about a -process from the system. For example, the +These functions run in the context of the calling process. +This is often an easier way of getting non-exported information about a +process from the system. +For example, the .Xr pfiles 1 command uses this interface to get more detailed information about a process's open file descriptors, which it would not have access to @@ -174,11 +178,12 @@ otherwise. .Sh INTERFACES The shared object .Sy libproc.so.1 -provides the public interfaces defined below. See +provides the public interfaces defined below. +See .Xr Intro 3 -for additional information on shared object interfaces. Functions are -organized into categories that describe their purpose. Individual -functions are documented in their own manual pages. +for additional information on shared object interfaces. +Functions are organized into categories that describe their purpose. +Individual functions are documented in their own manual pages. .Ss Creation, Grabbing, and Releasing The following routines are related to creating library handles, grabbing cores, processes, and threads, and releasing those resources. @@ -342,25 +347,26 @@ library. .Sh PROCESS STATES Every process handle that exists in .Nm -has a state. In some cases, such as for core files, these states are -static. In other cases, such as handles that correspond to a -running process or a created process, these states are dynamic and -change based on actions taken in the library. The state can be obtained -with the +has a state. +In some cases, such as for core files, these states are static. +In other cases, such as handles that correspond to a running process or a +created process, these states are dynamic and change based on actions taken in +the library. +The state can be obtained with the .Xr Pstate 3PROC function. .Pp The various states are: .Bl -tag -width Dv -offset indent .It Dv PS_RUN -An actively running process. This may be a process that was obtained -by creating it with functions such as +An actively running process. +This may be a process that was obtained by creating it with functions such as .Xr Pcreate 3PROC or by grabbing an existing process such as .Xr Pgrab 3PROC . .It Dv PS_STOP -An active process that is no longer executing. A process may stop for -many reasons such as an explicit stop request (through +An active process that is no longer executing. +A process may stop for many reasons such as an explicit stop request (through .Xr pstop 1 for example) or if a tracing event is hit. .Pp @@ -370,25 +376,28 @@ structure read directly from /proc or obtained through the .Xr Lstatus 3PROC function. .It Dv PS_LOST -Control over the process has been lost. This may happen when the -process executes a new image requiring a different set of privileges. +Control over the process has been lost. +This may happen when the process executes a new image requiring a different set +of privileges. To resume control call -.Xr Preopen 3PROC . For more information on losing control of a process, -see +.Xr Preopen 3PROC . +For more information on losing control of a process, see .Xr proc 4 . .It DV PS_UNDEAD -A zombie process. It has terminated, but it has not been cleaned up -yet by its parent. For more on the conditions of becoming a zombie, -see +A zombie process. +It has terminated, but it has not been cleaned up yet by its parent. +For more on the conditions of becoming a zombie, see .Xr exec 2 . .It DV_PS_DEAD -Processes in this state are always core files. See the earlier section +Processes in this state are always core files. +See the earlier section .Sx Core Files for more information on working with core files. .It Dv PS_IDLE -A process that has never been run. This is always the case for handles -that refer to files as the files cannot be executed. Those process -handles are obtained through calling +A process that has never been run. +This is always the case for handles that refer to files as the files cannot be +executed. +Those process handles are obtained through calling .Xr Pgrab_file 3PROC . .El .Pp @@ -422,11 +431,12 @@ However, it also defines the following types: The .Sy struct ps_prochandle is an opaque handle to the library and the core element of control for a -process. Consumers obtain pointers to a handle through the use of the +process. +Consumers obtain pointers to a handle through the use of the .Fn Pcreate , .Fn Pgrab , -and related functions. When a caller is done with a handle, then it -should call one of the +and related functions. +When a caller is done with a handle, then it should call one of the .Fn Pfree and .Fn Prelease @@ -440,7 +450,8 @@ The is analogous to the .Sy struct ps_prochandle , but it represents the control of an individual thread, rather than a -process. Consumers obtain pointers to a handle through the +process. +Consumers obtain pointers to a handle through the .Fn Lgrab function and relinquish it with the .Fn Lfree @@ -455,22 +466,24 @@ These are used in functions such as .Xr Pcontent 3PROC and .Xr Pgcore 3PROC -to describe and control the types of content that get included. Various -content types may be included together through a bitwise-inclusive-OR. +to describe and control the types of content that get included. +Various content types may be included together through a bitwise-inclusive-OR. The default system core contents are controlled with the .Xr coreadm 1M -tool. The following table lists the current set of core contents in the -system, though the set may increase over time. The string after the -macro is the human readable string that corresponds with the constant -and is used by +tool. +The following table lists the current set of core contents in the system, though +the set may increase over time. +The string after the macro is the human readable string that corresponds with +the constant and is used by .Xr coreadm 1M , .Xr proc_content2str 3PROC , and .Xr proc_str2content 3PROC . .Bl -tag -offset indent -width indent .It Dv CC_CONTENT_STACK ("stack") -The contents include the process stack. Note, this only covers the main -thread's stack. The stack of other threads is covered by +The contents include the process stack. +Note, this only covers the main thread's stack. +The stack of other threads is covered by .Dv CC_CONTENT_ANON . .It Dv CC_CONTENT_HEAP ("heap") The contents include the process heap. @@ -494,8 +507,8 @@ flags). The contents include private read-only file mappings, such as shared library text. .It Dv CC_CONTENT_ANON ("anon") -The contents include private anonymous mappings. This includes the -stacks of threads which are not the main thread. +The contents include private anonymous mappings. +This includes the stacks of threads which are not the main thread. .It Dv CC_CONTENT_SHM ("shm") The contents include system V shared memory. .It Dv CC_CONTENT_ISM ("ism") @@ -505,16 +518,16 @@ The contents include DISM (dynamic shared memory) mappings. .It Dv CC_CONTENT_CTF ("ctf") The contents include .Xr ctf 4 -(Compact C Type Format) information. Note, not all objects in the -process may have CTF information available. +(Compact C Type Format) information. +Note, not all objects in the process may have CTF information available. .It Dv CC_CONTENT_SYMTAB ("symtab") -The contents include the symbol table. Note, not all objects in the -process may have a symbol table available. +The contents include the symbol table. +Note, not all objects in the process may have a symbol table available. .It Dv CC_CONTENT_ALL ("all") This value indicates that all of the above content values are present. Note that additional values may be added in the future, in which case -the value of the symbol will be updated to include them. Comparisons -with +the value of the symbol will be updated to include them. +Comparisons with .Dv CC_CONTENT_ALL should validate all the expected bits are set by an expression such as .Li (c & CC_CONTENT_ALL) == CC_CONTENT_ALL . @@ -535,9 +548,9 @@ The content includes the following set of default values: .Dv CC_CONTENT_CTF , and .Dv CC_CONTENT_SYMTAB. -Note that the default may change. Comparisons with CC_CONTENT_DEFAULT -should validate that all of the expected bits are set with an expression -such as +Note that the default may change. +Comparisons with CC_CONTENT_DEFAULT should validate that all of the expected +bits are set with an expression such as .Li (c\ &\ CC_CONTENT_DEFAULT)\ ==\ CC_CONTENT_DEFAULT. .It Dv CC_CONTENT_INVALID This indicates that the contents are invalid. @@ -549,8 +562,8 @@ The .Sy prfdinfo_t structure is used with the .Fn Pfdinfo_iter -function which describes information about a file descriptor. The -structure is defined as follows: +function which describes information about a file descriptor. +The structure is defined as follows: .Bd -literal typedef struct prfdinfo { int pr_fd; @@ -577,7 +590,8 @@ defined in .Xr stat 2 . The member .Sy pr_fd -contains the number of the file descriptor of the file. The members +contains the number of the file descriptor of the file. +The members .Sy pr_mode , .Sy pr_uid , .Sy pr_gid , @@ -600,7 +614,8 @@ The and .Sy pr_minor members contain the major and minor numbers of the device containing the -directory for this file. This is similar to the +directory for this file. +This is similar to the .Sy st_dev member of the .Sy stat @@ -621,7 +636,8 @@ structure and thus have meaning for special character and block files. .Pp The .Sy pr_offset -member contains the current seek offset of the file descriptor. The +member contains the current seek offset of the file descriptor. +The .Sy pr_fileflags and .Sy pr_fdflags @@ -657,13 +673,15 @@ typedef struct prsyminfo { The member .Sy prs_object points to a string that contains the name of the object file, if known, -that the symbol comes from. The member +that the symbol comes from. +The member .Sy prs_name -points to the name of the symbol, if known. This may be unknown due to a -stripped binary that contains no symbol table. The member +points to the name of the symbol, if known. +This may be unknown due to a stripped binary that contains no symbol table. +The member .Sy prs_lmid -indicates the link map identifier that the symbol was found on. For more -information on link map identifiers refer to the +indicates the link map identifier that the symbol was found on. +For more information on link map identifiers refer to the .Em Linker and Libraries Guide and .Xr dlopen 3C . @@ -673,11 +691,13 @@ The members and .Sy prs_table can be used to determine both the symbol table that the entry came from -and which entry in the table it corresponds to. If the value of +and which entry in the table it corresponds to. +If the value of .Sy prs_table is .Dv PR_SYMTAB -then it came from the ELF standard symbol table. However, if it is instead +then it came from the ELF standard symbol table. +However, if it is instead .Dv PR_DYNSYM , then that indicates that it comes from the process's dynamic section. .Pp @@ -687,7 +707,8 @@ The .Sy proc_lwp_f is a function pointer type that is used with the .Fn Plwp_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_lwp_f @@ -706,7 +727,8 @@ The .Sy proc_lwp_all_f is a function pointer type that is used with the .Fn Plwp_iter_all -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_lwp_all_f @@ -718,7 +740,8 @@ The first argument is a pointer to an argument that the user specifies. The second and third arguments contain the thread's status and thread-specific .Xr ps 1 -information respectively. Both structures are defined in +information respectively. +Both structures are defined in .Xr proc 4 . For additional information on using this type, see .Xr Plwp_iter_all 3PROC . @@ -729,7 +752,8 @@ The .Sy proc_walk_f is a function pointer type that is used with the .Fn proc_walk -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_walk_f @@ -741,7 +765,8 @@ The first argument contains the process .Xr ps 1 information and the second argument contains the representative thread's .Xr ps 1 -information. Both structures are defined in +information. +Both structures are defined in .Xr proc 4 . The final argument is a pointer to an argument that the user specifies. For more information on using this, see @@ -757,7 +782,8 @@ is a function pointer type that is used with the .Fn Pobject_iter , and .Fn Pobject_iter_resolved -functions. It is defined as +functions. +It is defined as .Sy typedef .Ft int .Fo proc_map_f @@ -770,7 +796,8 @@ The second argument is describes the mapping information and is defined in .Xr proc 4 . The final argument contains the name of the mapping or object file in -question. For additional information on using this type, see +question. +For additional information on using this type, see .Xr Pmapping_iter 3PROC . .Pp .Sy proc_env_f @@ -779,7 +806,8 @@ The .Sy proc_env_f is a function pointer type that is used with the .Fn Penv_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_env_f @@ -791,10 +819,10 @@ function. It is defined as The first argument is a pointer to an argument that the user specifies. The second argument is a pointer to the .Sy struct ps_prochandle -that the callback was passed to. The third argument is the address of -the environment variable in the process. The fourth argument is the -environment variable. Values in the environment follow the convention of -the form +that the callback was passed to. +The third argument is the address of the environment variable in the process. +The fourth argument is the environment variable. +Values in the environment follow the convention of the form .Em variable=value . For more information on environment variables see .Xr exec 2 @@ -813,7 +841,8 @@ is a function pointer type that is used with the .Fn Psymbol_iter_by_name , and .Fn Psymbol_iter_by_lmid -functions. It is defined as +functions. +It is defined as .Sy typedef .Ft int .Fo proc_sym_f @@ -823,13 +852,14 @@ functions. It is defined as .Fc . The first argument is a pointer to an argument that the user supplies. The second argument is a pointer to the ELF symbol information in a -32-bit and 64-bit neutral form. See +32-bit and 64-bit neutral form. +See .Xr elf 3ELF and .Xr gelf 3ELF -for more information on it. The final argument points to a character -string that has the name of the symbol. For additional information on -using this type, see +for more information on it. +The final argument points to a character string that has the name of the symbol. +For additional information on using this type, see .Xr Psymbol_iter 3PROC , .Xr Psymbol_iter_by_addr 3PROC , .Xr Psymbol_iter_by_name 3PROC , @@ -842,7 +872,8 @@ The .Sy proc_xsym_f is a function pointer type that is used with the .Fn Pxsymbol_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_xsym_f @@ -854,10 +885,11 @@ function. It is defined as The first three arguments are identical to those of .Sy proc_sym_f . The final argument contains additional information about the symbol -itself. The members of the +itself. +The members of the .Sy prsyminfo_t -are defined earlier in this section. For additional information on using -this type, see +are defined earlier in this section. +For additional information on using this type, see .Xr Pxsymbol_iter 3PROC . .Pp .Sy proc_stack_f @@ -866,7 +898,8 @@ The .Sy proc_stack_f is a function pointer type that is used with the .Fn Pstack_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_stack_f @@ -876,17 +909,19 @@ function. It is defined as .Fa "const long *" .Fc . The first argument is a pointer to an argument that the user specifies. -The second argument's contents are platform specific. The registers that -contain stack information, usually the stack pointer and frame pointer, -will be filled in to point to an entry. The +The second argument's contents are platform specific. +The registers that contain stack information, usually the stack pointer and +frame pointer, will be filled in to point to an entry. +The .Sy prgregset_t is defined in .Xr proc 4 . .Pp The third argument contains the number of arguments to the current stack frame and the fourth argument contains an array of addresses that -correspond to the arguments to that stack function. The value of the -third argument dictates the number of entries in the fourth argument. +correspond to the arguments to that stack function. +The value of the third argument dictates the number of entries in the fourth +argument. For additional information on using this type, see .Xr Pstack_iter 3PROC . .Pp @@ -896,7 +931,8 @@ The .Sy proc_fdinfo_f is a function pointer type that is used with the .Fn Pfdinfo_iter -function. It is defined as +function. +It is defined as .Sy typedef .Ft int .Fo proc_fdinfo_f @@ -907,34 +943,37 @@ The first argument is a pointer to an argument that the user specifies. The second argument contains information about an open file descriptor. The members of the .Sy prfdinfo_t -are defined earlier in this section. For additional information on using -this type, see +are defined earlier in this section. +For additional information on using this type, see .Xr Pfdinfo_iter 3PROC . .Sh PROGRAMMING NOTES When working with live processes, whether from the -.Xr Pgrab +.Xr Pgrab 3PROC or -.Xr Pcreate +.Xr Pcreate 3PROC family of functions, there are some additional considerations. Importantly, if a process calls any of the .Xr exec 2 suite of functions, much of the state information that is obtained, -particularly that about mappings in the process will be invalid. Callers -must ensure that they call +particularly that about mappings in the process will be invalid. +Callers must ensure that they call .Xr Preset_maps 3PROC -when they hold a process handle across an exec. In addition, users of -the library should familiarize themselves with the +when they hold a process handle across an exec. +In addition, users of the library should familiarize themselves with the .Sy PROGRAMMING NOTES section of the .Xr proc 4 manual page, which discusses issues of privileges and security. .Sh DEBUGGING The library provides a means for obtaining additional debugging -information. The output itself is not part of the +information. +The output itself is not part of the .Nm -library's stable interface. Setting the environment variable +library's stable interface. +Setting the environment variable .Ev LIBPROC_DEBUG -to some value will print information to standard error. For example, +to some value will print information to standard error. +For example, .Ev LIBPROC_DEUBG Ns = Ns Em please . .Sh LOCKING Most functions operate on a handle to a process in the form of a @@ -943,27 +982,30 @@ Unless otherwise indicated, the library does not provide any synchronization for different routines that are operating on the .Sy same .Nm -library handle. It is up to the caller to ensure that only a single -thread is using a handle at any given time. Multiple threads may call +library handle. +It is up to the caller to ensure that only a single thread is using a handle at +any given time. +Multiple threads may call .Nm library routines at the same time as long as each thread is using a different handle. .Pp Each individual function notes its .Sy MT-Level -section. The MT-Level of a routine that matches the above description -will refer to this manual page. If it does not, then it refers to the -standard attributes in +section. +The MT-Level of a routine that matches the above description will refer to this +manual page. +If it does not, then it refers to the standard attributes in .Xr attributes 5 . .Sh INTERFACE STABILITY .Sy Uncommitted .Pp While the library is considered an uncommitted interface, and is still evolving, changes that break compatibility have been uncommon and this -trend is expected to continue. It is documented to allow consumers, -whether part of illumos or outside of it, to understand the libarary and -make use of it with the understanding that changes may occur which break -both source and binary compatibility. +trend is expected to continue. +It is documented to allow consumers, whether part of illumos or outside of it, +to understand the libarary and make use of it with the understanding that +changes may occur which break both source and binary compatibility. .Sh SEE ALSO .Xr gcore 1 , .Xr mdb 1 , diff --git a/usr/src/man/man3proc/Lfree.3proc b/usr/src/man/man3proc/Lfree.3proc index 07e0f3f6c5..b65a7bedae 100644 --- a/usr/src/man/man3proc/Lfree.3proc +++ b/usr/src/man/man3proc/Lfree.3proc @@ -42,7 +42,8 @@ The state of the thread controlled by is not affected by the call to .Fn Lfree . The thread's state will not transition from running to stopped or -vice-versa. It will retain its state prior to the call to +vice-versa. +It will retain its state prior to the call to .Fn Lfree . .Sh INTERFACE STABILITY .Sy Uncommitted diff --git a/usr/src/man/man3proc/Lgrab.3proc b/usr/src/man/man3proc/Lgrab.3proc index 24ad4a44b5..d5f840304d 100644 --- a/usr/src/man/man3proc/Lgrab.3proc +++ b/usr/src/man/man3proc/Lgrab.3proc @@ -35,7 +35,8 @@ residing under the process .Fa P . This handle is then passed as argument to other .Sy libproc -routines. The +routines. +The .Fa lwpid can be obtained from the .Sy pr_lwpid @@ -48,31 +49,33 @@ The argument must point to a valid pointer that will be used to store an error code in the event that .Fn Lgrab -is unable to successfully obtain a handle to the process. The possible -errors are defined below in the +is unable to successfully obtain a handle to the process. +The possible errors are defined below in the .Sx ERRORS -section. The code may be transformed into a human readable string -through the use of +section. +The code may be transformed into a human readable string through the use of .Xr Lgrab_error 3PROC . .Pp The handle to the thread is valid until the .Xr Lfree 3PROC -function is called, which also releases associated resources from the -handle. Only a single handle to a specific thread may exist at any -time. If the handle already exists and another caller attempts to grab -that thread, it will result in an error. The caller must call +function is called, which also releases associated resources from the handle. +Only a single handle to a specific thread may exist at any time. +If the handle already exists and another caller attempts to grab +that thread, it will result in an error. +The caller must call .Fn Lfree before releasing the handle associated with .Fa P . .Pp Unlike grabbing a process, grabbing a thread does not change the current -state of the thread. If it is running, it will remain running. If it is -stopped, it will remain stopped. +state of the thread. +If it is running, it will remain running. +If it is stopped, it will remain stopped. .Sh RETURN VALUES Upon successful completion, the .Fn Lgrab -function returns a pointer to the control handle for the specified -thread. Otherwise, the +function returns a pointer to the control handle for the specified thread. +Otherwise, the .Dv NULL pointer is returned and .Fa perr @@ -92,10 +95,11 @@ The thread identified by .Fa lwpid does not exist or has already become a zombie. .It Er G_STRANGE -An unanticipated system error occurred while trying to create the -handle. When this occurs, then the value of +An unanticipated system error occurred while trying to create the handle. +When this occurs, then the value of .Sy errno -is meaningful. See +is meaningful. +See .Xr errno 3C for more information and .Xr Intro 2 diff --git a/usr/src/man/man3proc/Lgrab_error.3proc b/usr/src/man/man3proc/Lgrab_error.3proc index cb544f9398..6606ac74c6 100644 --- a/usr/src/man/man3proc/Lgrab_error.3proc +++ b/usr/src/man/man3proc/Lgrab_error.3proc @@ -28,7 +28,8 @@ The .Fn Lgrab_error function returns a pointer to a human-readable character string -describing the error that occurred. The +describing the error that occurred. +The .Fn Lgrab_error function only knows how to translate error codes that were stored in the third argument diff --git a/usr/src/man/man3proc/Lprochandle.3proc b/usr/src/man/man3proc/Lprochandle.3proc index 7472c74b9c..72f1630450 100644 --- a/usr/src/man/man3proc/Lprochandle.3proc +++ b/usr/src/man/man3proc/Lprochandle.3proc @@ -29,10 +29,12 @@ The .Fn Lprochandle function returns the process handle to which the thread handle .Fa L -belongs. This proccess handle may be used with other +belongs. +This proccess handle may be used with other .Xr libproc 3PROC functions just as if -.Xr Pgrab 3PROC was called. The returned handle is valid even if +.Xr Pgrab 3PROC was called. +The returned handle is valid even if .Xr Lfree 3PROC is called on .Fa L . diff --git a/usr/src/man/man3proc/Lpsinfo.3proc b/usr/src/man/man3proc/Lpsinfo.3proc index d9ff12afb1..920c721112 100644 --- a/usr/src/man/man3proc/Lpsinfo.3proc +++ b/usr/src/man/man3proc/Lpsinfo.3proc @@ -30,7 +30,8 @@ The function returns the thread handle .Fa L Ns 's .Xr ps 1 -information. The +information. +The .Sy lwpsinfo_t structure that is returned is defined in .Xr proc 4 @@ -39,7 +40,8 @@ and is valid until a subsequent call to .Sh RETURN VALUES Upon successful completion, the .Fn Lpsinfo -function returns a pointer to the thread's ps information. Otherwise, +function returns a pointer to the thread's ps information. +Otherwise, .Dv NULL is returned to indicate that it could not be found. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Lstatus.3proc b/usr/src/man/man3proc/Lstatus.3proc index b02b63f6db..9efc793656 100644 --- a/usr/src/man/man3proc/Lstatus.3proc +++ b/usr/src/man/man3proc/Lstatus.3proc @@ -38,7 +38,8 @@ of its stack, its user and system time, and more. .Pp The returned pointer is only valid as long as the thread handle .Fa L -is valid. After a call to +is valid. +After a call to .Xr Ltree 3PROC , the returned data pointer is invalid. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Paddr_to_ctf.3proc b/usr/src/man/man3proc/Paddr_to_ctf.3proc index 9e46933478..5eb4183a23 100644 --- a/usr/src/man/man3proc/Paddr_to_ctf.3proc +++ b/usr/src/man/man3proc/Paddr_to_ctf.3proc @@ -53,9 +53,11 @@ shared libraries are searched. .Pp The CTF container returned is valid as long as the process handle .Fa P -is valid. That is, until a call to +is valid. +That is, until a call to .Xr Prelease 3PROC -is made. Further, consumers must not close the CTF container. +is made. +Further, consumers must not close the CTF container. .Pp The .Fn Paddr_to_ctf @@ -63,8 +65,8 @@ function attempts to find the CTF section, if any, that exists for the address .Fa addr . Note, not all addresses correspond to memory regions that have CTF -data. For example, if a user creates a region of anonymous memory -through the +data. +For example, if a user creates a region of anonymous memory through the .Xr mmap 2 function, then it will not have any corresponding CTF information. .Pp @@ -72,8 +74,9 @@ The .Fn Pname_to_ctf function looks up the object named .Fa name -and returns the corresponding CTF section, if any exists. Two special -values may be used for name. The macro +and returns the corresponding CTF section, if any exists. +Two special values may be used for name. +The macro .Dv PR_OBJ_EXEC refers to the executable object itself and the macro .Dv PR_OBJ_LDSO refers to the object ld.so.1 . @@ -86,7 +89,8 @@ It allows the passing of a link-map identifier, .Fa lmid , which constricts the search of the object named with .Fa name -to that link-map. The special value of +to that link-map. +The special value of .Dv PR_LMID_EVERY indicates that every link-map should be searched, which is equivalent in behavior to the diff --git a/usr/src/man/man3proc/Paddr_to_loadobj.3proc b/usr/src/man/man3proc/Paddr_to_loadobj.3proc index 220f17e47c..6430d8eae4 100644 --- a/usr/src/man/man3proc/Paddr_to_loadobj.3proc +++ b/usr/src/man/man3proc/Paddr_to_loadobj.3proc @@ -54,18 +54,19 @@ identifier, the TLS module ID, and the address of various sections. The pointer to the data returned by the library will only be valid for as long as the handle .Fa P -is valid. Any calls to +is valid. +Any calls to .Xr Prelease 3PROC will invalidate the data. .Pp The .Fn Paddr_to_loadobj -function attempts to find the loaded object information, if any, that exists for the -address +function attempts to find the loaded object information, if any, that exists for +the address .Fa addr . Not all address correspond to memory regions that were loaded by the -run-time link-editor. For example, if a user creates a region of -anonymous memory through the +run-time link-editor. +For example, if a user creates a region of anonymous memory through the .Xr mmap 2 function, then it will not have any corresponding loaded module. .Pp @@ -73,8 +74,9 @@ The .Fn Pname_to_loadobj function looks up the object named .Fa name -and returns the corresponding loaded object information. Two special -values may be used for name. The macro +and returns the corresponding loaded object information. +Two special values may be used for name. +The macro .Dv PR_OBJ_EXEC refers to the executable object itself and the macro .Dv PR_OBJ_LDSO refers to the object ld.so.1 . @@ -87,7 +89,8 @@ It allows the use of a link-map identifier, .Fa lmid , which constricts the search of the object named with .Fa name -to that link-map. The special value of +to that link-map. +The special value of .Dv PR_LMID_EVERY may be passed to indicate that every link-map should be searched, which is equivalent in behavior to the diff --git a/usr/src/man/man3proc/Paddr_to_map.3proc b/usr/src/man/man3proc/Paddr_to_map.3proc index eac5dc001d..d49067ee65 100644 --- a/usr/src/man/man3proc/Paddr_to_map.3proc +++ b/usr/src/man/man3proc/Paddr_to_map.3proc @@ -62,7 +62,8 @@ the mapping and is defined in The pointer to the data returned by the library will only be valid for as long as the handle .Fa P -is valid. Any calls to +is valid. +Any calls to .Xr Prelease 3PROC will invalidate the data. .Pp @@ -85,8 +86,9 @@ The .Fn Pname_to_map function looks up the object named .Fa name -and returns the corresponding mapping information. Two special -values may be used for name. The macro +and returns the corresponding mapping information. +Two special values may be used for name. +The macro .Dv PR_OBJ_EXEC refers to the executable object itself and the macro .Dv PR_OBJ_LDSO refers to the object ld.so.1 . @@ -99,7 +101,8 @@ It allows passing a link-map identifier, .Fa lmid , which constricts the search of the object named with .Fa name -to that link-map. The special value of +to that link-map. +The special value of .Dv PR_LMID_EVERY may be passed to indicate that every link-map should be searched, which is equivalent in behavior to the diff --git a/usr/src/man/man3proc/Pasfd.3proc b/usr/src/man/man3proc/Pasfd.3proc index 90c8865b66..a5ae8a9dc4 100644 --- a/usr/src/man/man3proc/Pasfd.3proc +++ b/usr/src/man/man3proc/Pasfd.3proc @@ -31,15 +31,17 @@ funtion returns a file descriptor that allows direct access to the address space of the process handle .Fa P . A defined file descriptor is provided when using the -.Xr Pcreate , +.Xr Pcreate 3PROC , .Xr Pgrab 3PROC , .Xr Pgrab_file 3PROC , and .Xr Pgrab_core 3PROC -functions. Note that the address space may be different in each of these -cases and doesn't necessarily correspond to the /proc +functions. +Note that the address space may be different in each of these cases and doesn't +necessarily correspond to the /proc .Sy as -file, except for live processes. Other means of obtaining a +file, except for live processes. +Other means of obtaining a .Sy libproc process handle may not define a file descriptor that contains the address space. @@ -47,14 +49,15 @@ address space. The returned file descriptor must not be closed and is only valid for as long as the corresponding process handle .Fa P -is valid. After a call to +is valid. +After a call to .Xr Prelease 3PROC the file descriptor is invalidated. .Sh RETURN VALUES Upon successful completion, the .Fn Pasfd -function returns a valid file descriptor. Otherwise, if none exists, -then +function returns a valid file descriptor. +Otherwise, if none exists, then .Sy -1 is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pclearfault.3proc b/usr/src/man/man3proc/Pclearfault.3proc index dba09993df..0c1f7ed862 100644 --- a/usr/src/man/man3proc/Pclearfault.3proc +++ b/usr/src/man/man3proc/Pclearfault.3proc @@ -32,9 +32,9 @@ .Sh DESCRIPTION During normal operation a process may encounter a .Sy fault , -due to a hardware exception, identifying a problem with the running -process. Hardware faults include things like executing illegal -instructions, encountering a breakpoint, and arithmetic exceptions. +due to a hardware exception, identifying a problem with the running process. +Hardware faults include things like executing illegal instructions, encountering +a breakpoint, and arithmetic exceptions. Faults are discussed further in .Xr proc 4 . .Pp @@ -58,8 +58,9 @@ The .Fn Pclearfault and .Fn Lclearfault -functions only have meaning for active processes. They will fail on process -handles corresponding to zombie processes, ELF objects, and cores. +functions only have meaning for active processes. +They will fail on process handles corresponding to zombie processes, ELF +objects, and cores. .Sh RETURN VALUES Upon successful completion, the .Fn Pclearfault diff --git a/usr/src/man/man3proc/Pclearsig.3proc b/usr/src/man/man3proc/Pclearsig.3proc index b96d78b697..577fcf9359 100644 --- a/usr/src/man/man3proc/Pclearsig.3proc +++ b/usr/src/man/man3proc/Pclearsig.3proc @@ -30,8 +30,8 @@ .Fa "struct ps_lwphandle *L" .Fc .Sh DESCRIPTION -During normal operation a process may receive a signal. Signals may -indicate an error, for example referencing unmapped memory, an alarm +During normal operation a process may receive a signal. +Signals may indicate an error, for example referencing unmapped memory, an alarm firing, requests for information, and users requesting an interruption. For more information on the generation and usage of signals, see .Xr signal.h 3HEAD . @@ -54,8 +54,9 @@ representive thread, it instead operates on the thread handle .Pp The .Fn Pclearsig -function only has meaning for active processes. It will fail on process -handles corresponding to core files, zombie processes and ELF objects. +function only has meaning for active processes. +It will fail on process handles corresponding to core files, zombie processes +and ELF objects. .Sh RETURN VALUES Upon successful completion, the .Fn Pclearsig diff --git a/usr/src/man/man3proc/Pcontent.3proc b/usr/src/man/man3proc/Pcontent.3proc index 0f31978cef..27d9d6742a 100644 --- a/usr/src/man/man3proc/Pcontent.3proc +++ b/usr/src/man/man3proc/Pcontent.3proc @@ -31,13 +31,14 @@ function describes information available from the process handle .Fa P . .Pp Different types of process handles have different kinds of content -available to them. For example, handles to active and running processes -have more information available than various core files, as the core -file retains a subset of information available in the running process. +available to them. +For example, handles to active and running processes have more information +available than various core files, as the core file retains a subset of +information available in the running process. Handles that refer to ELF objects, obtained through .Xr Pgrab_file 3PROC , -will not have information such as a stack available. The content of -core files is controlled by +will not have information such as a stack available. +The content of core files is controlled by .Xr coreadm 1M . .Pp The symbols that may be returned are listed in the @@ -49,7 +50,8 @@ section in .Sh RETURN VALUES Upon successful completion, the .Fn Pcontent -function returns the bitwise-inclusive-OR of content types. Otherwise, +function returns the bitwise-inclusive-OR of content types. +Otherwise, .Dv CC_CONTENT_INVALID is returned to indicate an error. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pcreate.3proc b/usr/src/man/man3proc/Pcreate.3proc index 23eb6f9e6a..6185e60d23 100644 --- a/usr/src/man/man3proc/Pcreate.3proc +++ b/usr/src/man/man3proc/Pcreate.3proc @@ -48,7 +48,8 @@ The .Fn Pcreate function creates a process controlled by the .Sy libproc -library. The +library. +The .Fn Pxcreate function does the same while also allowing the replacement of the environment via @@ -71,9 +72,10 @@ The process image will be invoked with the arguments specified by .Fa argv , which should be a .Dv NULL Ns -terminated -array of character strings. Each entry in the array is an individual -argument. The environment of the process image will be inherited from -the running process if the +array of character strings. +Each entry in the array is an individual argument. +The environment of the process image will be inherited from the running process +if the .Fn Pcreate function is called or if the .Fn Pxcreate @@ -97,9 +99,9 @@ process before the call to .Xr exec 2 . The symbol .Sy Pcreate_callback -is a symbol that may be interposed on by consumers. It allows the chance -for the modification of signal dispositions or any other changes that a -caller may wish to make. +is a symbol that may be interposed on by consumers. +It allows the chance for the modification of signal dispositions or any other +changes that a caller may wish to make. .Pp If the caller's real user or group ID is not their effective user or group ID, then the child process's user and group IDs will all be reset @@ -109,7 +111,8 @@ The .Fa perr argument must be a .Pf non- Dv NULL -pointer. If the +pointer. +If the .Fn Pcreate or .Fn Pxcreate @@ -125,7 +128,8 @@ may exist on the .Fa PATH . To determine the full path of the executable pass a non-NULL .Fa path -pointer. Upon successful completion of +pointer. +Upon successful completion of .Fn Pcreate or .Fn Pxcreate @@ -139,22 +143,24 @@ Upon successful completion of the .Fn Pcreate or .Fn Pxcreate -function, a handle to the process is returned. This handle is usable -with other +function, a handle to the process is returned. +This handle is usable with other .Sy libproc routines and will persist until either .Xr Pfree 3PROC or .Xr Prelease 3PROC -is called on the resulting handle. The process created is stopped just -after return from the +is called on the resulting handle. +The process created is stopped just after return from the .Xr exec 2 -family of system calls. The process will not run, unless the caller sets -it running or releases its handle to the process. +family of system calls. +The process will not run, unless the caller sets it running or releases its +handle to the process. .Pp A 32-bit process cannot use this interface to launch or control a -64-bit process. However, a 64-bit process can create and control both -32-bit and 64-bit processes. +64-bit process. +However, a 64-bit process can create and control both 32-bit and 64-bit +processes. .Sh RETURN VALUES Upon successful completion, both the .Fn Pcreate @@ -162,7 +168,8 @@ and .Fn Pxcreate functions create a new process and return a .Sy libproc -handle to it. Otherwise, +handle to it. +Otherwise, .Sy NULL is returned and .Fa perr @@ -202,9 +209,11 @@ or the one found by searching is set-id or unreadable. .It Er C_STRANGE An unanticipated system error occurred while trying to create the -process and its handle. When this occurs, then the value of +process and its handle. +When this occurs, then the value of .Sy errno -is meaningful. See +is meaningful. +See .Xr errno 3C for more information and .Xr Intro 2 diff --git a/usr/src/man/man3proc/Pcreate_agent.3proc b/usr/src/man/man3proc/Pcreate_agent.3proc index 8fcf3e35e4..a421938e06 100644 --- a/usr/src/man/man3proc/Pcreate_agent.3proc +++ b/usr/src/man/man3proc/Pcreate_agent.3proc @@ -30,7 +30,8 @@ The function creates the agent LWP in the process represented by the handle .Fa P . The agent LWP is used as a means to force system calls to be invoked on -the controlled process. For more information on the agent LWP, see +the controlled process. +For more information on the agent LWP, see .Xr proc 4 . .Pp The agent LWP cannot be created for process handles corresponding to @@ -39,8 +40,9 @@ objects. .Pp The .Fn Pcreate_agent -function is reentrant. It may be entered recursively. The act of -creating the agent LWP will cause the process to be stopped. +function is reentrant. +It may be entered recursively. +The act of creating the agent LWP will cause the process to be stopped. For every call to the .Fn Pcreate_agent function, a corresponding call to @@ -51,7 +53,8 @@ Upon successful completion, the .Fn Pcreate_agent function returns .Sy 0 -and creates the agent LWP. Otherwise, +and creates the agent LWP. +Otherwise, .Sy -1 is returned, .Sy errno @@ -67,8 +70,8 @@ The process referred to by is a core file, zombie, ELF object, or has not begun execution. .El .Pp -Note, it is possible for other error numbers to be returned. If they -are, they represent unanticipated failure. +Note, it is possible for other error numbers to be returned. +If they are, they represent unanticipated failure. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Pcreate_error.3proc b/usr/src/man/man3proc/Pcreate_error.3proc index 74d8331630..73a2538ec8 100644 --- a/usr/src/man/man3proc/Pcreate_error.3proc +++ b/usr/src/man/man3proc/Pcreate_error.3proc @@ -28,7 +28,8 @@ The .Fn Pcreate_error function returns a pointer to a human-readable character string -describing the error that occurred. The +describing the error that occurred. +The .Fn Pcreate_error function translates errors produced by the .Xr Pcreate 3PROC diff --git a/usr/src/man/man3proc/Pcred.3proc b/usr/src/man/man3proc/Pcred.3proc index f8376d45e2..bec0030fd4 100644 --- a/usr/src/man/man3proc/Pcred.3proc +++ b/usr/src/man/man3proc/Pcred.3proc @@ -39,8 +39,9 @@ The type is defined in .Xr proc 4 . It contains information about the current effective, saved, and real -user and group IDs. It also allows for supplemental groups to be -obtained. The +user and group IDs. +It also allows for supplemental groups to be obtained. +The .Fn Pcred function will read a number of supplemental groups based on the value of .Fa ngroups . @@ -54,7 +55,7 @@ groups that are desired. .Pp Not all process handles have credential information available to them. For example, the handles that come from -.Xr Pgrab_file +.Xr Pgrab_file 3PROC have no processes associated with them and thus have no credentials associated with them. .Sh RETURN VALUES @@ -64,7 +65,8 @@ function returns .Sy 0 and updates the memory at .Fa pcrp -with the credentials. Otherwise, +with the credentials. +Otherwise, .Sy -1 is returned to indicate an error. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pctlfd.3proc b/usr/src/man/man3proc/Pctlfd.3proc index cf331879ed..00e383c481 100644 --- a/usr/src/man/man3proc/Pctlfd.3proc +++ b/usr/src/man/man3proc/Pctlfd.3proc @@ -36,8 +36,8 @@ however, many interfaces for using it are provided by .Xr libproc 3LIB itself. .Pp -Only live processes have a control file descriptor. Process handles that -correspond to files and cores, created through +Only live processes have a control file descriptor. +Process handles that correspond to files and cores, created through .Xr Prab_file 3PROC and .Xr Pgrab_core 3PROC , @@ -50,8 +50,8 @@ or if control is lost and the handle is reopened. .Sh RETURN VALUES Upon successful completion, the .Fn Pctlfd -function returns a valid file descriptor. Otherwise, if none exists, -then +function returns a valid file descriptor. +Otherwise, if none exists, then .Sy -1 is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pdelbkpt.3proc b/usr/src/man/man3proc/Pdelbkpt.3proc index d999c38426..e00c5f7684 100644 --- a/usr/src/man/man3proc/Pdelbkpt.3proc +++ b/usr/src/man/man3proc/Pdelbkpt.3proc @@ -40,8 +40,8 @@ If the instruction at .Fa address is no longer the architecture-specific breakpoint instruction, then .Fa saved -is not restored, but the function still returns successfully. This -behavior is done due to the presence of setting breakpoints in +is not restored, but the function still returns successfully. +This behavior is done due to the presence of setting breakpoints in self-modifying code, e.g. procedure linkage tables. .Pp The diff --git a/usr/src/man/man3proc/Pdestroy_agent.3proc b/usr/src/man/man3proc/Pdestroy_agent.3proc index 9b379142cc..30c677204e 100644 --- a/usr/src/man/man3proc/Pdestroy_agent.3proc +++ b/usr/src/man/man3proc/Pdestroy_agent.3proc @@ -35,8 +35,8 @@ therefore if .Xr Pcreate_agent 3PROC has been called multiple times, the .Fn Pdestroy_agent -function must be called an equal number of times. Upon the last time, it -will destroy the agent LWP. +function must be called an equal number of times. +Upon the last time, it will destroy the agent LWP. .Pp Destroying the agent LWP does not change the state of the process represented by diff --git a/usr/src/man/man3proc/Penv_iter.3proc b/usr/src/man/man3proc/Penv_iter.3proc index 84fae69969..8dc616ee0f 100644 --- a/usr/src/man/man3proc/Penv_iter.3proc +++ b/usr/src/man/man3proc/Penv_iter.3proc @@ -35,18 +35,18 @@ For each environment variable, .Fa func is passed the caller argument .Fa data -along with the address of the environment variable and the key-value -pair. For the full signature of the +along with the address of the environment variable and the key-value pair. +For the full signature of the .Ft proc_env_f callback, see .Xr libproc 3LIB . .Pp -The callback's return value controls whether or not iteration -proceeds. If +The callback's return value controls whether or not iteration proceeds. +If .Fa func -returns zero, then iteration continues. Otherwise, iteration is -terminated and the value is returned. It is recommended that callback -functions do not return +returns zero, then iteration continues. +Otherwise, iteration is terminated and the value is returned. +It is recommended that callback functions do not return .Sy -1 so as to distinguish between the failure of the .Fn Penv_iter @@ -59,7 +59,8 @@ function returns Otherwise, if there was an internal error, for example due to a corrupted environment, then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Perror_printf.3proc b/usr/src/man/man3proc/Perror_printf.3proc index 4ad0b9de08..a71d6f3336 100644 --- a/usr/src/man/man3proc/Perror_printf.3proc +++ b/usr/src/man/man3proc/Perror_printf.3proc @@ -30,10 +30,12 @@ The function allows for consumers of the .Sy libproc library to obtain additional diagnostic information during various -operations. Consumers must explicitly +operations. +Consumers must explicitly .Em interpose -on this symbol and provide their own definition, if desired. There is no -requirement for such an interposition to be done. When called, +on this symbol and provide their own definition, if desired. +There is no requirement for such an interposition to be done. +When called, .Fa P will be the process handle that the additional diagnostics are being generated for and the diagnostics will be provided in a @@ -49,7 +51,7 @@ the provided diagnostics are and may change at any time. .Sh LOCKING Callers should presume that this function may be called from multiple -threads and always in a context in which taking locks is fine. Callers -should not expect to be called from a signal handler. +threads and always in a context in which taking locks is fine. +Callers should not expect to be called from a signal handler. .Sh SEE ALSO .Xr libproc 3LIB diff --git a/usr/src/man/man3proc/Pexecname.3proc b/usr/src/man/man3proc/Pexecname.3proc index d380333932..f7560c7396 100644 --- a/usr/src/man/man3proc/Pexecname.3proc +++ b/usr/src/man/man3proc/Pexecname.3proc @@ -41,9 +41,9 @@ bytes, including the null terminator. .Pp For a handle grabbed with .Xr Pgrab_file 3PROC , -the executable refers to the path of the file itself. For a core file, -the system attempts to determine the original path of the executable -and return that. +the executable refers to the path of the file itself. +For a core file, the system attempts to determine the original path of the +executable and return that. .Sh RETURN VALUES Upon successful completion, the .Fn Pexecname diff --git a/usr/src/man/man3proc/Pfault.3proc b/usr/src/man/man3proc/Pfault.3proc index 61c6454f02..7c1d8ed99e 100644 --- a/usr/src/man/man3proc/Pfault.3proc +++ b/usr/src/man/man3proc/Pfault.3proc @@ -34,34 +34,37 @@ function controls what the process should do on faults. .Pp A fault is a hardware event that occurs in the context of a running -process and thread. A hardware fault may occur because an illegal -instruction was executed, a breakpoint or watchpoint was encountered, or -an arithmetic exception occurred, among others. The full list of faults -is available in both +process and thread. +A hardware fault may occur because an illegal instruction was executed, +a breakpoint or watchpoint was encountered, or an arithmetic exception occurred, +among others. +The full list of faults is available in both .Xr proc 4 and .In sys/fault.h . .Pp For each hardware fault, a process may be configured to stop the thread -that encountered it when it occurs. The value of the +that encountered it when it occurs. +The value of the .Fa stop parameter controls whether or not the listed fault in .Fa which -will cause the thread to trap. A value of 1 indicates the thread -should stop; a value of 0 indicates it should not. +will cause the thread to trap. +A value of 1 indicates the thread should stop; a value of 0 indicates it should +not. .Pp The value of .Fa which -indicates which hardware fault the change applies to. However, if the -value of +indicates which hardware fault the change applies to. +However, if the value of .Fa which is zero, then it applies to all faults. .Pp The .Fn Pfault -function only applies to actively running processes. It does not -function on handles that refer to core files, zombie processes, or ELF -objects. +function only applies to actively running processes. +It does not function on handles that refer to core files, zombie processes, or +ELF objects. .Sh RETURN VALUES Upon successful completion, the .Fn Pfault @@ -70,7 +73,8 @@ function returns the old disposition of the fault -- if it was not set to stop and .Sy 1 if it was -- -and the fault state is updated. Otherwise, +and the fault state is updated. +Otherwise, .Sy -1 is returned, .Dv errno diff --git a/usr/src/man/man3proc/Pfdinfo_iter.3proc b/usr/src/man/man3proc/Pfdinfo_iter.3proc index 80408130a7..055355e00c 100644 --- a/usr/src/man/man3proc/Pfdinfo_iter.3proc +++ b/usr/src/man/man3proc/Pfdinfo_iter.3proc @@ -47,16 +47,19 @@ see .Pp The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 , -then iteration will continue. However, if +then iteration will continue. +However, if .Fa func instead returns a non-zero value, then iteration will halt and that value will be used as the return value of the .Fn Pfdinfo_iter -function. Because the +function. +Because the .Fn Pfdinfo_iter function returns .Sy -1 @@ -74,7 +77,8 @@ returns .Sy 0 . Otherwise, if there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pgcore.3proc b/usr/src/man/man3proc/Pgcore.3proc index 24f38c3f6d..732331b7ff 100644 --- a/usr/src/man/man3proc/Pgcore.3proc +++ b/usr/src/man/man3proc/Pgcore.3proc @@ -44,7 +44,8 @@ wide variety of tools and libraries including .Xr mdb 1 , .Xr pargs 1 , .Xr pstack 1 , -and more. For details on the core file format, see +and more. +For details on the core file format, see .Xr core 4 . .Pp .Fn Pfgcore @@ -57,8 +58,8 @@ writes the core to the file path .Pp The content of the core is controlled by the .Fa content -argument. It's the inclusive-bitwise-OR of the various content types -listed under the +argument. +It's the inclusive-bitwise-OR of the various content types listed under the .Sy core_content_t heading in the .Sy TYPES @@ -75,7 +76,8 @@ or functions stop the handle .Fa P . It is up to the caller to stop the process; which is recommended for -obtaining a consistent view of the process. See the +obtaining a consistent view of the process. +See the .Xr Pstop 3PROC function for a means to stop a handle. .Sh RETURN VALUES @@ -85,9 +87,11 @@ and .Fn Pgcore functions return .Sy 0 -and write out a core file to specified location. Otherwise, +and write out a core file to specified location. +Otherwise, .Sy -1 -is returned. The +is returned. +The .Fn Pfgcore function will truncate .Fa fd diff --git a/usr/src/man/man3proc/Pgetareg.3proc b/usr/src/man/man3proc/Pgetareg.3proc index 1d8a67ca75..254530b6d6 100644 --- a/usr/src/man/man3proc/Pgetareg.3proc +++ b/usr/src/man/man3proc/Pgetareg.3proc @@ -57,8 +57,8 @@ to by .Fa P . .Pp The getting and setting of registers of the process operates on the -representative thread (LWP). For more information on how the -representative is chosen, see +representative thread (LWP). +For more information on how the representative is chosen, see .Xr proc 4 . To change the registers of a specific thread, use the .Xr Lgetareg 3PROC @@ -66,17 +66,19 @@ and .Xr Lsetareg 3PROC functions. .Pp -The getting and setting of registers only applies to stopped -processes. In addition, one may obtain registers from core files, but -not set them. To stop a process, see the +The getting and setting of registers only applies to stopped processes. +In addition, one may obtain registers from core files, but not set them. +To stop a process, see the .Xr Pstop 3PROC function. .Pp The register to get or set is indicated by the .Fa regno -argument. For a list of registers, see +argument. +For a list of registers, see .In sys/regset.h . -The set of registers is specific to each architecture of the system. The +The set of registers is specific to each architecture of the system. +The .Fn Pgetareg function will fill in the value of .Fa preg @@ -123,7 +125,8 @@ functions will fail if: .It Er EINVAL The value of .Fa regno -is invalid. This means it is less than +is invalid. +This means it is less than .Sy 0 and greater than .Sy NPRGREG . @@ -150,7 +153,8 @@ functions will fail if: .It Er EINVAL The value of .Fa regno -is invalid. This means it is less than +is invalid. +This means it is less than .Sy 0 and greater than .Sy NPRGREG . diff --git a/usr/src/man/man3proc/Pgetauxval.3proc b/usr/src/man/man3proc/Pgetauxval.3proc index 034d68c7f3..2d6122bfe7 100644 --- a/usr/src/man/man3proc/Pgetauxval.3proc +++ b/usr/src/man/man3proc/Pgetauxval.3proc @@ -32,10 +32,11 @@ function looks up the entry .Fa type in the auxiliary vector of the process handle .Fa P -and returns its value. The +and returns its value. +The .Fa type -argument should be the entry of the auxiliary vector. The list of such -types may be found in +argument should be the entry of the auxiliary vector. +The list of such types may be found in .In sys/auxv.h . .Sh RETURN VALUES Upon successful completion, the diff --git a/usr/src/man/man3proc/Pgetauxvec.3proc b/usr/src/man/man3proc/Pgetauxvec.3proc index a940bdfdcf..348e01ea15 100644 --- a/usr/src/man/man3proc/Pgetauxvec.3proc +++ b/usr/src/man/man3proc/Pgetauxvec.3proc @@ -32,7 +32,8 @@ process handle .Fa P . If the process handle does not represent an actively running process or the auxiliary vector could not be found, then it instead returns an -empty auxiliary vector. The definitions of the +empty auxiliary vector. +The definitions of the .Sy auxv_t may be found in .In sys/auxv.h . diff --git a/usr/src/man/man3proc/Pgrab.3proc b/usr/src/man/man3proc/Pgrab.3proc index 3627d1712f..a6df2614e1 100644 --- a/usr/src/man/man3proc/Pgrab.3proc +++ b/usr/src/man/man3proc/Pgrab.3proc @@ -32,8 +32,9 @@ The function attempts to grab the process identified by .Fa pid and returns a handle to it that allows the process to be controlled, -interrogated, and manipulated. This interface only works with processes -that already exist. Use +interrogated, and manipulated. +This interface only works with processes that already exist. +Use .Xr Pgrab_core 3PROC for core files and .Xr Pcreate 3PROC @@ -48,38 +49,41 @@ The process is stopped .It All other tracing flags are cleared .It -The grab is exclusive. If any existing handles to this process exist -or anyone else is using the underlying facilities of the /proc file -system to control this process, it will fail. +The grab is exclusive. +If any existing handles to this process exist or anyone else is using the +underlying facilities of the /proc file system to control this process, +it will fail. .It Unless the process is already stopped, the .Dv PR_RLC -flag is set indicating the process should run-on-last-close. Allowing -the process to resume running if its controlling process dies. +flag is set indicating the process should run-on-last-close. +Allowing the process to resume running if its controlling process dies. .El .Pp Grabbing a process is a .Em destructive -action. Stopping a process stops execution of all its threads. The -impact of stopping a process depends on the purpose of that process. +action. +Stopping a process stops execution of all its threads. +The impact of stopping a process depends on the purpose of that process. For example, if one stops a process that's primarily doing computation, then its computation is delayed the entire time that it -is stopped. However, if instead this is an active TCP server, then the -accept backlog may fill causing connection errors and potentially -connection time out errors. +is stopped. +However, if instead this is an active TCP server, then the accept backlog may +fill causing connection errors and potentially connection time out errors. .Pp Special care must be taken to ensure that a stopped process continues, -even if the controlling process terminates. If the controlling process -disables the +even if the controlling process terminates. +If the controlling process disables the .Dv PR_RLC flag or the process was already stopped, then the process remains -stopped after the controlling process terminates. Exercise caution -when changing this behavior. +stopped after the controlling process terminates. +Exercise caution when changing this behavior. .Pp Many of these default behaviors can be controlled by passing values to the .Fa flags -argument. Values for +argument. +Values for .Fa flags are constructed by a bitwise-inclusive-OR of flags from the following list: @@ -87,17 +91,18 @@ list: .It Dv PGRAB_RETAIN Indicates that any existing tracing flags on .Fa pid -should be retained. If this flag is not specified, they will be cleared -as part of creating the +should be retained. +If this flag is not specified, they will be cleared as part of creating the .Sy libproc handle for this process. .Pp Normally extant tracing flags are cleared when a process is grabbed. .It Dv PGRAB_FORCE -Indicates that the process should not be grabbed exclusively. Care -should be taken with this option. If other consumers are manipulating -the process, then this may result in surprising behavior as the process -is being manipulated from multiple points of control at the same time. +Indicates that the process should not be grabbed exclusively. +Care should be taken with this option. +If other consumers are manipulating the process, then this may result in +surprising behavior as the process is being manipulated from multiple points of +control at the same time. .Pp Normally an attempt will be made to grab the process exclusively and fail if it is already in use. @@ -107,15 +112,15 @@ This implies that both the .Dv PGRAB_RETAIN and .Dv PGRAB_NOSTOP -flags should be set. If a process is opened read-only, then a caller can -only read information about a process and cannot manipulate it, change -its current state, or inject systems calls into it. +flags should be set. +If a process is opened read-only, then a caller can only read information about +a process and cannot manipulate it, change its current state, or inject systems +calls into it. .Pp -Normally when a process is grabbed, it does so for both reading and -writing. +Normally when a process is grabbed, it does so for both reading and writing. .It Dv PGRAB_NOSTOP -Do not stop a process as it is grabbed. Note, any extant tracing flags -on the process will still be cleared unless the +Do not stop a process as it is grabbed. +Note, any extant tracing flags on the process will still be cleared unless the .Dv PGRAB_RETAIN flag has been set. .Pp @@ -128,31 +133,34 @@ argument must be a .Pf non- Dv NULL pointer which will store a more detailed error in the event that the .Fn Pgrab -function fails. A human-readable form of the error can be obtained -with +function fails. +A human-readable form of the error can be obtained with .Xr Pgrab_error 3PROC . .Pp Once a caller is done with the library handle it should call .Xr Prelease 3PROC -to release the grabbed process. Failure to properly release the handle -may leave a process stopped and interfere with the ability of other -software to obtain a handle. +to release the grabbed process. +Failure to properly release the handle may leave a process stopped and interfere +with the ability of other software to obtain a handle. .Ss Permissions Unprivileged users may grab and control their own processes only if both the user and group IDs of the target process match those of the calling -process. In addition, the caller must have a super set of the target's -privileges. Processes with the +process. +In addition, the caller must have a super set of the target's privileges. +Processes with the .Sy PRIV_PROC_OWNER privilege may manipulate any process on the system, as long as it has an -equal privilege set. For more details on the security and programming -considerations, please see the section +equal privilege set. +For more details on the security and programming considerations, please see the +section .Sy PROGRAMMING NOTES in .Xr proc 4 . .Sh RETURN VALUES Upon successful completion, the .Fn Pgrab -function returns a control handle to the process. Otherwise, +function returns a control handle to the process. +Otherwise, .Dv NULL is returned with .Fa perr @@ -174,7 +182,8 @@ The calling process is a 32-bit process and process .Fa pid is 64-bit. .It Er G_NOFD -Too many files are open. This is logically equivalent to receiving +Too many files are open. +This is logically equivalent to receiving .Er EMFILE . .It Er G_NOPROC The process referred to by @@ -182,7 +191,8 @@ The process referred to by does not exist. .It Er G_PERM The calling process has insufficient permissions or privileges to open -the specified process. See +the specified process. +See .Sx Permissions for more information. .It Er G_SYS @@ -194,7 +204,8 @@ The process referred to by .Fa pid is the process ID of the caller and the .Dv PGRAB_RDONLY -was not passed. A process may only grab itself if it's read-only. +was not passed. +A process may only grab itself if it's read-only. .It Er G_STRANGE An unanticipated system error occurred while trying to grab the process file and create the handle. diff --git a/usr/src/man/man3proc/Pgrab_core.3proc b/usr/src/man/man3proc/Pgrab_core.3proc index cf28387c03..2b864bd563 100644 --- a/usr/src/man/man3proc/Pgrab_core.3proc +++ b/usr/src/man/man3proc/Pgrab_core.3proc @@ -39,11 +39,12 @@ The .Fn Pgrab_core and .Fn Pfgrab_core -functions open a core file for introspection. Unlike live processes, -core files cannot have their state modified; however, all of the -functions that iterate or query state will work. These functions work -on all illumos core files and the core files of some other operating -systems. See both +functions open a core file for introspection. +Unlike live processes, core files cannot have their state modified; +however, all of the functions that iterate or query state will work. +These functions work on all illumos core files and the core files of some other +operating systems. +See both .Xr core 4 and the .Em Core Files @@ -58,17 +59,18 @@ function attempts to open the core file specified by The system attempts to determine the path of the original executable. The argument .Fa aout -may either be the path to that file, a path to a directory to -search, or the +may either be the path to that file, a path to a directory to search, or the .Dv NULL -pointer, if neither is known. The system will search for it and will -supplement information in the core file with that. +pointer, if neither is known. +The system will search for it and will supplement information in the core file +with that. .Pp The .Fa gflag argument to the .Fn Pgrab_core -function controls how the file is opened. If the +function controls how the file is opened. +If the .Dv PGRAB_RDONLY flag is specified, then the core file will be opened with the .Xr open 2 @@ -83,16 +85,17 @@ argument must be a .Pf non- Dv NULL pointer which will store a more detailed error in the event that the .Fn Pgrab_core -function fails. A human-readable form of the error can be obtained -through the routine +function fails. +A human-readable form of the error can be obtained through the routine .Xr Pgrab_error 3PROC . .Pp The .Fn Pfgrab_core is similar to the .Fn Pgrab_core -function. Except, instead of operating on a path, it opens a handle to -the core file referenced by +function. +Except, instead of operating on a path, it opens a handle to the core file +referenced by .Fa core_fd . The .Fa aout @@ -114,7 +117,8 @@ and .Fn Pfgrab_core functions return a .Sy libproc -handle to the core file. Otherwise, +handle to the core file. +Otherwise, .Dv NULL is returned and .Fa perr diff --git a/usr/src/man/man3proc/Pgrab_error.3proc b/usr/src/man/man3proc/Pgrab_error.3proc index 30bfa23f32..01be5d1ccf 100644 --- a/usr/src/man/man3proc/Pgrab_error.3proc +++ b/usr/src/man/man3proc/Pgrab_error.3proc @@ -28,8 +28,8 @@ The .Fn Pgrab_error function returns a pointer to a human-readable character string -describing the error that occurred. This function only knows how to -translate errors that are stored in +describing the error that occurred. +This function only knows how to translate errors that are stored in .Fa perr during a failed call to .Xr Pgrab 3PROC , diff --git a/usr/src/man/man3proc/Pgrab_file.3proc b/usr/src/man/man3proc/Pgrab_file.3proc index d12e052697..8c883d9677 100644 --- a/usr/src/man/man3proc/Pgrab_file.3proc +++ b/usr/src/man/man3proc/Pgrab_file.3proc @@ -36,13 +36,13 @@ handle, it allows one to inspect aspects of the ELF contents present in the handle, for example obtaining CTF information and looking up symbols. .Pp -There is no running state associated with this handle nor can -there be. If one intends to control a running process or create a -process, see +There is no running state associated with this handle nor can there be. +If one intends to control a running process or create a process, see .Xr Pgrab 3PROC and .Xr Pcreate 3PROC -respectively. To inspect a core file use +respectively. +To inspect a core file use .Xr Pgrab_core 3PROC . .Pp The @@ -51,7 +51,8 @@ argument must be a .Pf non- Dv NULL pointer which will store a more detailed error in the event that .Fn Pgrab_file -fails. A human-readable form of the error can be obtained with +fails. +A human-readable form of the error can be obtained with .Xr Pgrab_error 3PROC . .Pp When finished with the returned handle, @@ -60,7 +61,8 @@ must be called to clean up resources associated with it. .Sh RETURN VALUES Upon successful completion, the .Fn Pgrab_file -function returns a control handle to the process. Otherwise, +function returns a control handle to the process. +Otherwise, .Dv NULL is returned and .Fa perr diff --git a/usr/src/man/man3proc/Pisprocdir.3proc b/usr/src/man/man3proc/Pisprocdir.3proc index daa3569c8f..18aef39e5a 100644 --- a/usr/src/man/man3proc/Pisprocdir.3proc +++ b/usr/src/man/man3proc/Pisprocdir.3proc @@ -30,8 +30,8 @@ The .Fn Pisprocdir function determines whether or not the directory .Fa dir -is the root of the /proc file-system. This works across loopback file -system (lofs) mounts and chroots. +is the root of the /proc file-system. +This works across loopback file system (lofs) mounts and chroots. .Sh RETURN VALUES Upon successful completion, the .Fn Pisprocdir diff --git a/usr/src/man/man3proc/Pissyscall.3proc b/usr/src/man/man3proc/Pissyscall.3proc index 9ec1ba29d3..58b4d36950 100644 --- a/usr/src/man/man3proc/Pissyscall.3proc +++ b/usr/src/man/man3proc/Pissyscall.3proc @@ -16,7 +16,7 @@ .Os .Sh NAME .Nm Pissyscall , -.Nm Pissyscall_prev , +.Nm Pissyscall_prev .Nd determine if instructions are system call instructions .Sh SYNOPSIS .Lb libproc @@ -47,8 +47,8 @@ function determines whether or not the instruction before .Fa addr in the process handle .Fa P -corresponds to one of the architecture's system call instructions. If it -does, and +corresponds to one of the architecture's system call instructions. +If it does, and .Fa dst is a .Pf non- Dv NULL @@ -62,7 +62,8 @@ function returns .Sy non-zero if .Fa addr -corresponds to a system call instruction. Otherwise, +corresponds to a system call instruction. +Otherwise, .Sy 0 is returned. .Pp @@ -77,7 +78,8 @@ corresponds to a system call instruction and if is .Pf non- Dv NULL , .Fa dst -is updated. Otherwise, +is updated. +Otherwise, .Sy 0 is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pldt.3proc b/usr/src/man/man3proc/Pldt.3proc index f492497ba3..c39a0b6371 100644 --- a/usr/src/man/man3proc/Pldt.3proc +++ b/usr/src/man/man3proc/Pldt.3proc @@ -60,7 +60,8 @@ The buffer .Fa pldt should contain sufficient space for .Fa nldt -entries. For example, callers could allocate space as: +entries. +For example, callers could allocate space as: .Pp .Dl pldt = malloc(sizeof (struct ssd) * nldt); .Pp @@ -91,9 +92,11 @@ is .Dv NULL or .Fa nldt -is zero, then no data will be written. Otherwise, +is zero, then no data will be written. +Otherwise, .Sy -1 -is returned. The +is returned. +The .Fn Pldt function sets .Sy errno diff --git a/usr/src/man/man3proc/Plookup_by_addr.3proc b/usr/src/man/man3proc/Plookup_by_addr.3proc index 6502956de4..5c0d2355c7 100644 --- a/usr/src/man/man3proc/Plookup_by_addr.3proc +++ b/usr/src/man/man3proc/Plookup_by_addr.3proc @@ -78,8 +78,8 @@ functions look up symbol information in the process handle .Fa P and fill in the ELF symbol information in .Fa symp -with the found symbol. Symbols may be looked up both by address and -name. +with the found symbol. +Symbols may be looked up both by address and name. .Pp The .Fn Plookup_by_addr @@ -97,7 +97,8 @@ function is identical to the .Fn Plookup_by_addr function, except that it also fills in the structure .Fa sip -with additional information. The definition of the +with additional information. +The definition of the .Sy prsyminfo_t is found in .Xr libproc 3PROC . @@ -112,16 +113,19 @@ to an absolute path on the file system. .Pp The .Fn Plookup_by_name -function attempts to look up a symbol based on its name. The +function attempts to look up a symbol based on its name. +The .Fa object argument allows the caller to specify a specific object that was mapped in by the run-time link-editor to search for .Fa symbol -in. The system provides three special values which may be passed in for +in. +The system provides three special values which may be passed in for .Fa object . The value .Dv PR_OBJ_EXEC -refers to the executable's object (a.out). The value +refers to the executable's object (a.out). +The value .Dv PR_OBJ_LDSO refers to the object .Sy ld.so.1 . @@ -147,16 +151,18 @@ and symbol named .Fa symbol to the specified link-map. .Pp -There are three special link-map identifiers -that may be passed in. The symbol +There are three special link-map identifiers that may be passed in. +The symbol .Dv PR_LMID_EVERY -indicates that every link-map should be searched. The symbol +indicates that every link-map should be searched. +The symbol .Dv LM_ID_BASE indicates that the base link-map, the one that is used for the -executable should be searched. Finally, the symbol +executable should be searched. +Finally, the symbol .Dv LM_ID_LDSO -refers to the link-map that is used by the run-time link editor, -ld.so.1. The +refers to the link-map that is used by the run-time link editor, ld.so.1. +The .Fn Plookup_by_name function behaves like .Fn Pxlookup_by_name @@ -175,7 +181,8 @@ and .Fn Pxlookup_by_name functions return .Sy 0 -and fill in the symbol information. Otherwise, +and fill in the symbol information. +Otherwise, .Sy -1 is returned to indicate that the symbol could not be found. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Plwp_getasrs.3proc b/usr/src/man/man3proc/Plwp_getasrs.3proc index 7630857461..85fa41e910 100644 --- a/usr/src/man/man3proc/Plwp_getasrs.3proc +++ b/usr/src/man/man3proc/Plwp_getasrs.3proc @@ -46,14 +46,16 @@ in the process handle .Pp The ancillary state registers are only present on 64-bit .Sy SPARCv9 -processes. They contain information that is specific to the platform and -are not included in the information obtained through functions such as +processes. +They contain information that is specific to the platform and are not included +in the information obtained through functions such as .Xr Plwp_getregs 3PROC , .Xr Plwp_getfpregs 3PROC , and .Xr Plwp_getxregs 3PROC . .Pp -The Plwp_getasrs +The +.Fn Plwp_getasrs function reads the ancillary registers into .Fa asrs , while the @@ -62,7 +64,8 @@ sets the thread's ancillary registers to the values provided by .Fa asrs . .Pp Processes should be stopped prior to obtaining the register state of -individual threads. Processes may be stopped with +individual threads. +Processes may be stopped with .Xr Pstop 3PROC . .Pp The @@ -79,7 +82,8 @@ and .Fn Plwp_setasrs functions return .Sy 0 -and get or set the register state. Otherwise, +and get or set the register state. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getgwindows.3proc b/usr/src/man/man3proc/Plwp_getgwindows.3proc index f6a4234d84..173406352b 100644 --- a/usr/src/man/man3proc/Plwp_getgwindows.3proc +++ b/usr/src/man/man3proc/Plwp_getgwindows.3proc @@ -42,7 +42,8 @@ function returns .Sy 0 and .Fa gwins -is filled in with information about the windows. Otherwise, +is filled in with information about the windows. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getpsinfo.3proc b/usr/src/man/man3proc/Plwp_getpsinfo.3proc index c798a1dd91..4d7d64fca7 100644 --- a/usr/src/man/man3proc/Plwp_getpsinfo.3proc +++ b/usr/src/man/man3proc/Plwp_getpsinfo.3proc @@ -60,7 +60,8 @@ and is filled in with the thread-specific .Xr ps 1 -information. Otherwise, +information. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getregs.3proc b/usr/src/man/man3proc/Plwp_getregs.3proc index 70115f4b4b..5d4e7766f7 100644 --- a/usr/src/man/man3proc/Plwp_getregs.3proc +++ b/usr/src/man/man3proc/Plwp_getregs.3proc @@ -92,7 +92,8 @@ to the register state contained in .Fa gregs . .Pp Processes must be stopped before obtaining the register state of -individual threads. Processes may be stopped with +individual threads. +Processes may be stopped with .Xr Pstop 3PROC . The structures used for registers are described in .Xr proc 4 @@ -112,7 +113,8 @@ and .Fn Plwp_setfpregs functions return .Sy 0 -and obtain or set the register state. Otherwise, +and obtain or set the register state. +Otherwise, .Sy -1 is returned, .Sy errno diff --git a/usr/src/man/man3proc/Plwp_getspymaster.3proc b/usr/src/man/man3proc/Plwp_getspymaster.3proc index 67244077d1..7810b402b0 100644 --- a/usr/src/man/man3proc/Plwp_getspymaster.3proc +++ b/usr/src/man/man3proc/Plwp_getspymaster.3proc @@ -35,11 +35,11 @@ the agent LWP for the thread in the process handle .Fa P . .Pp -The agent LWP allows another process to inject actions into the target -process. When an agent LWP is created, it leverages an existing thread -in the process and it also creates a record of whom created the agent, -which is called the spy master. For more information on the agent LWP -and the spy master, see +The agent LWP allows another process to inject actions into the target process. +When an agent LWP is created, it leverages an existing thread in the process and +it also creates a record of whom created the agent, which is called the spy +master. +For more information on the agent LWP and the spy master, see .Xr proc 4 . .Pp If the thread identified @@ -54,8 +54,9 @@ will be filled into Note, process handles that correspond to a file, created by .Xr Pgrab_file 3PROC , cannot have an agent LWP created for them and thus cannot have any spy -master information. In addition, core files from older releases may not -have any data on the spy master. +master information. +In addition, core files from older releases may not have any data on the spy +master. .Sh RETURN VALUES Upon successful completion, the .Fn Plwp_getspymaster diff --git a/usr/src/man/man3proc/Plwp_getxregs.3proc b/usr/src/man/man3proc/Plwp_getxregs.3proc index 0445251578..e1801eedda 100644 --- a/usr/src/man/man3proc/Plwp_getxregs.3proc +++ b/usr/src/man/man3proc/Plwp_getxregs.3proc @@ -43,8 +43,8 @@ functions get and set the extended register state of the thread in the process handle .Fa P . .Pp -The extended register state is defined by the architecture. These -registers may refer to optional registers that have become common on the +The extended register state is defined by the architecture. +These registers may refer to optional registers that have become common on the platform, but are not part of the standard ABI and thus not covered by functions such as .Xr Plwp_getregs 3PROC @@ -63,7 +63,8 @@ for the process handle .Fa P . .Pp Processes must be stopped prior to obtaining the register state of -individual threads. Processes may be stopped with +individual threads. +Processes may be stopped with .Xr Pstop 3PROC . .Pp The @@ -80,7 +81,8 @@ and .Fn Plwp_setxregs functions return .Sy 0 -and get or set the register state. Otherwise, +and get or set the register state. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Plwp_iter.3proc b/usr/src/man/man3proc/Plwp_iter.3proc index 3ad0f1219b..15de2f12ea 100644 --- a/usr/src/man/man3proc/Plwp_iter.3proc +++ b/usr/src/man/man3proc/Plwp_iter.3proc @@ -53,7 +53,8 @@ is called with the pointer to the private data argument, .Fa data , and the thread's .Sy lwpstatus_t -structure. In the case of the +structure. +In the case of the .Fn Plwp_iter_all function, the thread's .Sy lwpsinfo_t @@ -61,18 +62,21 @@ is also included. .Pp The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 , -then both functions will continue iteration. However, if +then both functions will continue iteration. +However, if .Fa func returns non-zero, then iteration will halt and that value will be used as the return value of the .Fn Plwp_iter and .Fn Plwp_iter_all -functions. Because both functions return +functions. +Because both functions return .Sy -1 on internal failure, it is recommended that the callback function does not return @@ -92,7 +96,8 @@ functions return .Sy 0 . Otherwise, if there was an internal error or there is no thread data, then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Plwp_stack.3proc b/usr/src/man/man3proc/Plwp_stack.3proc index 1e8c189a9f..2cf3303ed2 100644 --- a/usr/src/man/man3proc/Plwp_stack.3proc +++ b/usr/src/man/man3proc/Plwp_stack.3proc @@ -73,7 +73,8 @@ in the process handle Each thread in a process has its own stack which is used both for maintaining function call sequences and the storing of local variables. A thread may also configure a different stack to handle specific -signals. This stack is often called the +signals. +This stack is often called the .Em alternate stack . Whether or not the alternate stack is used may be controlled through the .Xr sigaction 2 @@ -134,7 +135,8 @@ functions return .Sy 0 and fills in .Fa stkp -with information about the appropriate stack. Otherwise, +with information about the appropriate stack. +Otherwise, .Sy -1 is returned, .Sy errno diff --git a/usr/src/man/man3proc/Pmapping_iter.3proc b/usr/src/man/man3proc/Pmapping_iter.3proc index b60d06ad50..7f2fb46124 100644 --- a/usr/src/man/man3proc/Pmapping_iter.3proc +++ b/usr/src/man/man3proc/Pmapping_iter.3proc @@ -64,16 +64,17 @@ the .Sy prmap_t structure defined from .Xr proc 4 , -and a name of the mapping. The way that the name is obtained varies -based on whether one calls +and a name of the mapping. +The way that the name is obtained varies based on whether one calls .Fn Pmapping_iter or .Fn Pmapping_iter_resolved . In both cases, the dynamic linker is consulted to determine the file -name for the mapping, if it's known. If the name is unknown, for example -an anonymous mapping, then the +name for the mapping, if it's known. +If the name is unknown, for example an anonymous mapping, then the .Dv NULL -pointer is passed in for the name. In the case of the +pointer is passed in for the name. +In the case of the .Fn Pmapping_iter_resolved function the system tries to resolve it to a complete file system path. If that fails, it falls back to the information from the dynamic linker, @@ -88,20 +89,24 @@ see .Pp The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 -then iteration continues. If +then iteration continues. +If .Fa func returns non-zero then iteration will halt and the value will be -returned to the caller. Because +returned to the caller. +Because .Sy -1 -indicates internal failure, it is recommended that the callback -function not return +indicates internal failure, it is recommended that the callback function not +return .Sy -1 -to indicate an error itself. This allows the caller to distinguish -between failure of the callback function versus failure of the +to indicate an error itself. +This allows the caller to distinguish between failure of the callback function +versus failure of the .Fn Pmapping_iter and .Fn Pmapping_iter_resolved @@ -115,13 +120,13 @@ functions are similar to the .Fn Pmapping_iter and .Fn Pmapping_iter_resolved -functions. Except, rather than iterating over every mapping, they -iterate over the objects that the process has loaded by the dynamic -linker. For example, an anonymous mapping will show up when iterating -mappings, but will not show up when iterating objects. Further, while -most dynamic shared objects have multiple mappings for the text and -data sections, there will only be a single object that is iterated -over. +functions. +Except, rather than iterating over every mapping, they iterate over the objects +that the process has loaded by the dynamic linker. +For example, an anonymous mapping will show up when iterating mappings, but will +not show up when iterating objects. +Further, while most dynamic shared objects have multiple mappings for the text +and data sections, there will only be a single object that is iterated over. .Pp The distinction between the .Fn Pobject_iter @@ -143,7 +148,8 @@ functions return .Sy 0. Otherwise, if there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pobjname.3proc b/usr/src/man/man3proc/Pobjname.3proc index cd97e41ce7..4b75abb31a 100644 --- a/usr/src/man/man3proc/Pobjname.3proc +++ b/usr/src/man/man3proc/Pobjname.3proc @@ -16,7 +16,7 @@ .Os .Sh NAME .Nm Pobjname , -.Nm Pobjname_resolved , +.Nm Pobjname_resolved .Nd turn a virtual address into its mapped object .Sh SYNOPSIS .Lb libproc @@ -46,9 +46,9 @@ contains the virtual address in the process handle .Fa P . .Pp -A program consists of multiple memory mappings. Some are provided by the -system, such as the stack and the heap. While others are created through -explicit calls to +A program consists of multiple memory mappings. +Some are provided by the system, such as the stack and the heap. +While others are created through explicit calls to .Xr mmap 2 or brought in by the run-time link-editor due to dependencies specified in binaries and libraries. @@ -62,8 +62,8 @@ of the name of the corresponding object will be written into .Fa buffer . The .Fn Pobjname_resolved -function attempts to resolve the object to a full file system path. If -the full file-system path cannot be determined, then it will fall back +function attempts to resolve the object to a full file system path. +If the full file-system path cannot be determined, then it will fall back to the name that the run-time link-editor has for that mapping, which is the behavior of .Fn Pobjname . diff --git a/usr/src/man/man3proc/Ppltdest.3proc b/usr/src/man/man3proc/Ppltdest.3proc index efdca692dc..56eea82f85 100644 --- a/usr/src/man/man3proc/Ppltdest.3proc +++ b/usr/src/man/man3proc/Ppltdest.3proc @@ -34,8 +34,8 @@ in the process handle .Fa P corresponds to an entry in the procedure linkage table (PLT) and if so, returns a pointer to a null-terminated character string that contains -the symbol's name. The returned pointer is not valid after any other -calls to function in +the symbol's name. +The returned pointer is not valid after any other calls to function in .Xr libproc 3LIB . The .Fn Ppltdest @@ -45,7 +45,8 @@ corresponds to an address in the PLT. .Sh RETURN VALUES Upon successful completion, the .Fn Ppltdest -returns a pointer to a character string with the name. Otherwise, +returns a pointer to a character string with the name. +Otherwise, .Dv NULL is returned. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Ppriv.3proc b/usr/src/man/man3proc/Ppriv.3proc index ae238eae67..f7adf48756 100644 --- a/usr/src/man/man3proc/Ppriv.3proc +++ b/usr/src/man/man3proc/Ppriv.3proc @@ -59,7 +59,8 @@ function returns .Sy 0 and .Fa pprv -is updated with a pointer to the allocated privilege set. Otherwise, +is updated with a pointer to the allocated privilege set. +Otherwise, .Sy -1 is returned and .Fa pprv diff --git a/usr/src/man/man3proc/Ppsinfo.3proc b/usr/src/man/man3proc/Ppsinfo.3proc index f86572f9f6..7032494b06 100644 --- a/usr/src/man/man3proc/Ppsinfo.3proc +++ b/usr/src/man/man3proc/Ppsinfo.3proc @@ -30,7 +30,8 @@ The function returns the process handle .Fa P Ns 's .Xr ps 1 -information. The +information. +The .Sy psinfo_t structure that is returned is defined in .Xr proc 4 @@ -39,7 +40,8 @@ and is valid until a subsequent call to .Sh RETURN VALUES Upon successful completion, the .Fn Ppsinfo -function returns a pointer to the process ps information. Otherwise, +function returns a pointer to the process ps information. +Otherwise, .Dv NULL is returned to indicate that it could not be found. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Prd_agent.3proc b/usr/src/man/man3proc/Prd_agent.3proc index 78438621c5..412ef9b04a 100644 --- a/usr/src/man/man3proc/Prd_agent.3proc +++ b/usr/src/man/man3proc/Prd_agent.3proc @@ -43,8 +43,8 @@ is released through a call to .Sh RETURN VALUES Upon successful completion, the .Fn Prd_agent -function returns a pointer to the librtld_db agent. Otherwise, it -returns +function returns a pointer to the librtld_db agent. +Otherwise, it returns .Dv NULL to indicate failure. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pread.3proc b/usr/src/man/man3proc/Pread.3proc index 8b4eb52da8..5a1e449c31 100644 --- a/usr/src/man/man3proc/Pread.3proc +++ b/usr/src/man/man3proc/Pread.3proc @@ -50,14 +50,15 @@ and is logically analogous to the .Xr pread 2 function. .Pp -For live processes, this function is equivalent to reading from the -/proc file system +For live processes, this function is equivalent to reading from the /proc file +system .Sy as -file for the process. For core files and file handles, it reads and -writes from the logical address space and not the corresponding offset -of the file itself. For example, a core file contains a sparse -representation of the address space of a crashed process and unmapped -regions are not present in the file. However, +file for the process. +For core files and file handles, it reads and writes from the logical address +space and not the corresponding offset of the file itself. +For example, a core file contains a sparse representation of the address space +of a crashed process and unmapped regions are not present in the file. +However, .Fa address still refers to the virtual addresses that were present at run-time and not those in the core file. @@ -73,7 +74,8 @@ into .Fa buf if either .Fa nbytes -has been read or a null terminator is encountered. The resulting data in +has been read or a null terminator is encountered. +The resulting data in .Fa buf will always be null terminated, even if no null terminator was found in the first @@ -85,7 +87,8 @@ Upon successful completion, the and .Fn Pread_string functions return a non-negative integer indicating the number of bytes -actually read. Otherwise, the functions return +actually read. +Otherwise, the functions return .Sy -1 and set .Sy errno diff --git a/usr/src/man/man3proc/Prelease.3proc b/usr/src/man/man3proc/Prelease.3proc index d201d198ac..3d66a0d560 100644 --- a/usr/src/man/man3proc/Prelease.3proc +++ b/usr/src/man/man3proc/Prelease.3proc @@ -35,8 +35,9 @@ The .Fn Prelease function is used to release all of the resources associated with a .Nm libproc -handle. It is suitable for handles to core files, created processes, and -grabbed processes from the +handle. +It is suitable for handles to core files, created processes, and grabbed +processes from the .Xr Pgrab_core 3PROC , .Xr Pcreate 3PROC , .Xr Pgrab 3PROC , @@ -47,7 +48,8 @@ functions. After calling the .Fn Prelease function, all data that was returned via the handle will no longer be -valid. For example, the data from calls to +valid. +For example, the data from calls to .Xr Pctlfd 3PROC , .Xr Pgetauxvec 3PROC , .Xr Pstatus 3PROC , @@ -55,16 +57,16 @@ and others. .Pp The behavior of the released process is controlled by the .Fa flags -argument. By default, if no flags are passed, then the process -represented by +argument. +By default, if no flags are passed, then the process represented by .Fa P will be set running if it was created by -.Xr Pcreate -or if it was not originally stopped or set to stop in /proc. The -following values may be passed in to the +.Xr Pcreate 3PROC +or if it was not originally stopped or set to stop in /proc. +The following values may be passed in to the .Fa flags -argument. Multiple flags should be be combined with a -bitwise-inclusive-OR. +argument. +Multiple flags should be be combined with a bitwise-inclusive-OR. .Bl -tag -width Er -offset indent .It Dv PRELEASE_CLEAR When releasing the process, clear all tracing flags that are set on the @@ -73,14 +75,14 @@ process. When releasing the process, retain all tracing flags that are currently active on the process. .It Dv PRELEASE_HANG -Leave the process stopped. It will not resume execution unless it is -explicitly enabled with +Leave the process stopped. +It will not resume execution unless it is explicitly enabled with .Xr prun 1 or another process explicitly enables it. .It Dv PRELEASE_KILL Release the process and terminate it with -.Dv SIGKILL . This option takes precedence over all other values that may -be passed in to +.Dv SIGKILL . +This option takes precedence over all other values that may be passed in to .Fa flags . .El .Pp @@ -94,7 +96,8 @@ handle however, unlike the .Fn Prelease function, it does not handle any logic to change or set the grabbed processes -state. In general, prefer +state. +In general, prefer .Fn Prelease to .Fn Pfree . diff --git a/usr/src/man/man3proc/Preopen.3proc b/usr/src/man/man3proc/Preopen.3proc index 6343a56f12..088480ab57 100644 --- a/usr/src/man/man3proc/Preopen.3proc +++ b/usr/src/man/man3proc/Preopen.3proc @@ -37,7 +37,8 @@ function returning the value This may occur when the controlled process performs an .Xr exec 2 of a setuid or setgid binary or one where the controlling process cannot -read the object file. For more information on this, see the +read the object file. +For more information on this, see the .Sy PROGRAMMING NOTES section of .Xr proc 4 . diff --git a/usr/src/man/man3proc/Psecflags.3proc b/usr/src/man/man3proc/Psecflags.3proc index 7cedb0f78e..4f4b342146 100644 --- a/usr/src/man/man3proc/Psecflags.3proc +++ b/usr/src/man/man3proc/Psecflags.3proc @@ -59,7 +59,8 @@ function returns .Sy 0 and .Fa psf -is updated with a pointer to the allocated security flags. Otherwise, +is updated with a pointer to the allocated security flags. +Otherwise, .Sy -1 is returned and .Fa psf diff --git a/usr/src/man/man3proc/Psetbkpt.3proc b/usr/src/man/man3proc/Psetbkpt.3proc index 1d0992d298..430063ef1e 100644 --- a/usr/src/man/man3proc/Psetbkpt.3proc +++ b/usr/src/man/man3proc/Psetbkpt.3proc @@ -50,9 +50,9 @@ breakpoint it generates a trap causing the thread to stop. .Pp -Note, breakpoints may only be set in active processes. They may not be -set in process handles that refer to core files, zombie processes, or -files. +Note, breakpoints may only be set in active processes. +They may not be set in process handles that refer to core files, zombie +processes, or files. .Sh RETURN VALUES Upon successful completion, the .Fn Psetbkpt diff --git a/usr/src/man/man3proc/Psetcred.3proc b/usr/src/man/man3proc/Psetcred.3proc index 4cd9e214b5..afc0ce65d6 100644 --- a/usr/src/man/man3proc/Psetcred.3proc +++ b/usr/src/man/man3proc/Psetcred.3proc @@ -33,13 +33,14 @@ function updates the credentials of the process handle to the values set in .Fa credp . .Fa credp -must be fully initialized. The definition of the +must be fully initialized. +The definition of the .Sy prcred_t structure may be found in .Xr proc 4 . .Pp -Note, the credentials may only be updated for an active process. If the -process handle refers to a zombie process, core file, or a file, then +Note, the credentials may only be updated for an active process. +If the process handle refers to a zombie process, core file, or a file, then .Fn Psetcred will fail. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Psetfault.3proc b/usr/src/man/man3proc/Psetfault.3proc index 4a3200762b..7cb467c402 100644 --- a/usr/src/man/man3proc/Psetfault.3proc +++ b/usr/src/man/man3proc/Psetfault.3proc @@ -32,8 +32,8 @@ function sets the fault tracing flags on the process handle .Fa P to .Fa set . -It replaces any existing fault tracing flags on the process. These -flags indicate which faults cause execution of the thread to stop. +It replaces any existing fault tracing flags on the process. +These flags indicate which faults cause execution of the thread to stop. Allowing another tool, such as a debugger, to act upon the process. For more information on faults and the .Sy fltset_t @@ -45,8 +45,8 @@ The current fault set for the process may be obtained through the .Xr Pfault 3PROC function. .Pp -Note, only active processes may have their fault set updated. Process -handles that refer to core files, zombie processes, and files do not +Note, only active processes may have their fault set updated. +Process handles that refer to core files, zombie processes, and files do not have fault tracing flags and this function is a no-op on them. .Sh INTERFACE STABILITY .Sy Uncommitted diff --git a/usr/src/man/man3proc/Psetflags.3proc b/usr/src/man/man3proc/Psetflags.3proc index 8a1783b738..a91126442b 100644 --- a/usr/src/man/man3proc/Psetflags.3proc +++ b/usr/src/man/man3proc/Psetflags.3proc @@ -15,7 +15,7 @@ .Dt PSETFLAGS 3PROC .Os .Sh NAME -.Nm Psetflags +.Nm Psetflags , .Nm Punsetflags .Nd set and unset process flags .Sh SYNOPSIS @@ -39,11 +39,12 @@ and functions manipulate the process flags for the process handle .Fa P . The process flags determine how the process behaves in the face of -various actions. For example, setting the +various actions. +For example, setting the .Sy PR_FORK flag indicates that the tracing flags of the process and the -inherit-on-fork mode should be set on children. A full list of the -process flags is available in the +inherit-on-fork mode should be set on children. +A full list of the process flags is available in the .Sy PCSET section in .Xr proc 4 . @@ -58,7 +59,8 @@ The .Fn Punsetflags function removes the flags specified in .Fa flags -from the tracing flags of the process. Items not listed in +from the tracing flags of the process. +Items not listed in .Fa flags will remain. .Pp @@ -66,14 +68,15 @@ To see the current set of flags active on the process, check the .Sy pr_flags member of the .Sy pstatus_t -for the process. It can be obtained through the +for the process. +It can be obtained through the .Xr Pstatus 3PROC function. .Pp Note, attempting to modify the process flags only works on active -processes. Attempting to call these functions of process handles -corresponding to core files, zombie processes, or files, will result in -an error. +processes. +Attempting to call these functions of process handles corresponding to core +files, zombie processes, or files, will result in an error. .Sh RETURN VALUES Upon successful completion, the .Fn Psetflags diff --git a/usr/src/man/man3proc/Psetpriv.3proc b/usr/src/man/man3proc/Psetpriv.3proc index d2a0dbc08c..4d327280e4 100644 --- a/usr/src/man/man3proc/Psetpriv.3proc +++ b/usr/src/man/man3proc/Psetpriv.3proc @@ -54,7 +54,8 @@ Upon successful completion, the .Fn Psetpriv function returns .Sy 0 -and updates the privilege sets of the process. Otherwise, +and updates the privilege sets of the process. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Psetrun.3proc b/usr/src/man/man3proc/Psetrun.3proc index 6a063d6dd9..68b6f92ebd 100644 --- a/usr/src/man/man3proc/Psetrun.3proc +++ b/usr/src/man/man3proc/Psetrun.3proc @@ -43,14 +43,15 @@ If .Fa sig is non-zero, then the .Fn Psetrun -function causes the signal to be delivered. See +function causes the signal to be delivered. +See .Xr signal.h 3HEAD for a list of valid signal identifiers. .Pp The .Fa flags -member modifies the behavior of the resumed handle. The following values -may be combined by a bitwise-inclusive-OR: +member modifies the behavior of the resumed handle. +The following values may be combined by a bitwise-inclusive-OR: .Bl -tag -width Dv -offset indent .It Dv PRCSIG Clears the current signal, if any. @@ -58,17 +59,18 @@ Clears the current signal, if any. Clears the current fault, if any. .It Dv PRSTEP Indicates that the thread should single-step over the next machine -instruction and upon completion, inject a trap. For the specific -mechanics of single-stepping and what traps or signals will be injected, -see the +instruction and upon completion, inject a trap. +For the specific mechanics of single-stepping and what traps or signals will be +injected, see the .Sy PRSTEP section of .Xr proc 4 . .It Dv PRSABORT Indicates that the thread should abort the system call that it is -currently executing. This is only valid if the thread is stopped because -it is asleep or right before a system call. This will cause the system -call to return +currently executing. +This is only valid if the thread is stopped because it is asleep or right before +a system call. +This will cause the system call to return .Er EINTR . .El .Pp @@ -85,16 +87,17 @@ was passed the argument .Sy 0 . .Pp When the process is resumed all extent tracing flags and register -changes will be synchronized with the process. For more information on -resuming a thread see the +changes will be synchronized with the process. +For more information on resuming a thread see the .Sy PCRUN section in .Xr proc 4 . .Pp Note, the .Fn Psetrun -function is only valid for active processes. It will fail on process -handles that refer to core files, zombie processes, and ELF objects. +function is only valid for active processes. +It will fail on process handles that refer to core files, zombie processes, and +ELF objects. .Pp The .Fn Lsetrun @@ -105,7 +108,8 @@ thread. .Fn Lsetrun causes the specified thread, .Fa L , -to resume execution. Whereas +to resume execution. +Whereas .Fn Psetrun causes all threads in the process to resume. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Psetsignal.3proc b/usr/src/man/man3proc/Psetsignal.3proc index c861788570..58745ffaa7 100644 --- a/usr/src/man/man3proc/Psetsignal.3proc +++ b/usr/src/man/man3proc/Psetsignal.3proc @@ -37,9 +37,9 @@ The call to replaces any existing signal tracing flags entirely with .Fa set . The signal tracing flags determine which signals, when received by a -thread in the process, will cause that thread to stop. For more -information on the behavior of the signal tracing flags, including which -signals may be traced this way, see the +thread in the process, will cause that thread to stop. +For more information on the behavior of the signal tracing flags, including +which signals may be traced this way, see the .Sy PCSTRACE section in .Xr proc 4 . diff --git a/usr/src/man/man3proc/Psetsysentry.3proc b/usr/src/man/man3proc/Psetsysentry.3proc index f8759937d3..4c7cce76f4 100644 --- a/usr/src/man/man3proc/Psetsysentry.3proc +++ b/usr/src/man/man3proc/Psetsysentry.3proc @@ -46,19 +46,20 @@ The call to or .Fn Psetsysexit replaces the corresponding set of system call tracing flags entirely -with the new set. The system call entry tracing flags cause a thread to -stop on entry to the system call and the exit tracing flags cause a -thread to stop on return from the system call, before control returns -back to the user land process. For more information on the state of the -thread and for information on manipulating the +with the new set. +The system call entry tracing flags cause a thread to stop on entry to the +system call and the exit tracing flags cause a thread to stop on return from the +system call, before control returns back to the user land process. +For more information on the state of the thread and for information on +manipulating the .Sy sysset_t , see .Xr proc 4 . .Pp Note that only active processes may have their system call tracing flags -updated. Process handles that refer to core files, zombie processes, -and files do not have fault tracing flags and this function is a no-op -on them. +updated. +Process handles that refer to core files, zombie processes, and files do not +have fault tracing flags and this function is a no-op on them. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Psetwapt.3proc b/usr/src/man/man3proc/Psetwapt.3proc index 1751f04fb9..4ef992cb77 100644 --- a/usr/src/man/man3proc/Psetwapt.3proc +++ b/usr/src/man/man3proc/Psetwapt.3proc @@ -31,7 +31,8 @@ The function adds a watchpoint to the process handle .Fa P . Allowing the hardware to generate a trap when the specified area is -accessed. The watchpoint's parameters are described in +accessed. +The watchpoint's parameters are described in .Fa wp . For more information on watchpoints and the .Sy prwatch_t @@ -42,9 +43,9 @@ section in The watched area will persist until a subsequent call to .Xr Pdelwapt 3PROC . .Pp -Note, only active processes support watchpoints. It is an error to call -this function on process handles that correspond to core files, zombie -processes, or files. +Note, only active processes support watchpoints. +It is an error to call this function on process handles that correspond to core +files, zombie processes, or files. .Sh RETURN VALUES Upon successful completion, the .Fn Psetwapt diff --git a/usr/src/man/man3proc/Psetzoneid.3proc b/usr/src/man/man3proc/Psetzoneid.3proc index 4d163c8b17..7a83fc54fa 100644 --- a/usr/src/man/man3proc/Psetzoneid.3proc +++ b/usr/src/man/man3proc/Psetzoneid.3proc @@ -33,32 +33,34 @@ function moves the process handle into the zone specified by .Fa zoneid . A process that is in the non-global zone may only move between the -global zone and its original zone. A process that is in the global zone -may not use this interface to enter a non-global zone. This function -will fail if called from a non-global zone. This function only -manipulates the processes credentials. +global zone and its original zone. +A process that is in the global zone may not use this interface to enter a +non-global zone. +This function will fail if called from a non-global zone. +This function only manipulates the processes credentials. .Pp Care should be taken when moving a process around temporarily, such that if the process that is manipulating .Fa P dies, it does not cause .Fa P -to resume running while still in the global zone. It is suggested that -the +to resume running while still in the global zone. +It is suggested that the .Sy PR_KLC flag is set with .Xr Psetflags 3PROC which will cause the process to terminate if the process that holds .Fa P -unexpectedly terminates. See +unexpectedly terminates. +See .Xr proc 4 for more information on the .Sy PR_KLC flag. .Pp -Note, only active processes may change their zone. It is an error to -call this function on process handles that correspond to core files, -zombie processes, or files. +Note, only active processes may change their zone. +It is an error to call this function on process handles that correspond to core +files, zombie processes, or files. .Sh RETURN VALUES Upon successful completion, the .Fn Psetzoneid diff --git a/usr/src/man/man3proc/Psignal.3proc b/usr/src/man/man3proc/Psignal.3proc index 1930c1583e..1ff90096f6 100644 --- a/usr/src/man/man3proc/Psignal.3proc +++ b/usr/src/man/man3proc/Psignal.3proc @@ -54,7 +54,8 @@ may not be stopped. .Pp Note, only active processes may have their signal tracing flags updated. Process handles that refer to core files, zombie processes, and files do -not have signal tracing flags. Calling this function on them is an error. +not have signal tracing flags. +Calling this function on them is an error. .Sh RETURN VALUES Upon successful completion, the .Fn Psignal @@ -64,7 +65,8 @@ It returns .Sy 1 if it was set and .Sy 0 -if not. Otherwise, +if not. +Otherwise, .Sy -1 is returned and .Sy errno diff --git a/usr/src/man/man3proc/Pstack_iter.3proc b/usr/src/man/man3proc/Pstack_iter.3proc index 75ffdba1f3..bd3da0d7cd 100644 --- a/usr/src/man/man3proc/Pstack_iter.3proc +++ b/usr/src/man/man3proc/Pstack_iter.3proc @@ -39,20 +39,23 @@ For each valid stack frame encountered, the callback function .Fa func is invoked with .Fa data -passed as argument. The full signature of +passed as argument. +The full signature of .Ft proc_stack_f is defined in .Xr libproc 3LIB . With each callback, a register set, argument set, and argument count -will be provided. In that register set, only a subset of the registers -will be valid, which include the frame pointer, program counter, and on -SPARC systems, the next program counter. These registers can be accessed -with the constants +will be provided. +In that register set, only a subset of the registers will be valid, which +include the frame pointer, program counter, and on SPARC systems, the next +program counter. +These registers can be accessed with the constants .Sy R_FP , .Sy R_PC , and .Sy R_nPC -respectively. These correspond to the registers +respectively. +These correspond to the registers .Em %ebp and .Em %eip @@ -70,36 +73,40 @@ on both SPARC and SPARCv9. Callers will receive a callback for the first stack frame indicated by .Fa regs and then will receive a subsequent callback for each caller of that -frame until no such frame can be found. Stack frames that logically come -after the frame indicated by +frame until no such frame can be found. +Stack frames that logically come after the frame indicated by .Fa regs will not receive callbacks. .Pp -The compiler can either facilitate or stymie the iteration of the -stack. Programs that have been compiled in such a way as to omit the -frame pointer will result in truncated stacks. Similarly, if the initial -set of registers passed in via +The compiler can either facilitate or stymie the iteration of the stack. +Programs that have been compiled in such a way as to omit the frame pointer will +result in truncated stacks. +Similarly, if the initial set of registers passed in via .Fa regs is invalid, then the ability to iterate the stack will be limited. The return value of .Fa func -controls whether or not iteration continues. If +controls whether or not iteration continues. +If .Fa func returns .Sy 0 -then iteration continues. However, if +then iteration continues. +However, if .Fa func returns non-zero, then iteration will halt and that value will be used as the return value of the .Fn Pstack_iter -function. Because +function. +Because .Fn Pstack_iter returns .Sy -1 on internal failure it is recommended the callback function not return .Sy -1 -to indicate an error. Thus the caller may distinguish between the -failure of the callback function and the failure of the +to indicate an error. +Thus the caller may distinguish between the failure of the callback function and +the failure of the .Fn Pstack_iter function. .Sh RETURN VALUES @@ -109,7 +116,8 @@ function returns .Sy 0. If there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Pstatus.3proc b/usr/src/man/man3proc/Pstatus.3proc index 6079c01b05..7a917ee5a0 100644 --- a/usr/src/man/man3proc/Pstatus.3proc +++ b/usr/src/man/man3proc/Pstatus.3proc @@ -38,7 +38,8 @@ number of threads, the size of the stack, and more. .Pp The returned pointer is only valid as long as the process handle .Fa P -is valid. After a call to +is valid. +After a call to .Xr Prelease 3PROC , the returned data pointer is invalid. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/Pstopstatus.3proc b/usr/src/man/man3proc/Pstopstatus.3proc index 12eeb3366f..8ce88fb7a4 100644 --- a/usr/src/man/man3proc/Pstopstatus.3proc +++ b/usr/src/man/man3proc/Pstopstatus.3proc @@ -19,7 +19,7 @@ .Nm Pstopstatus , .Nm Pstop , .Nm Pwait , -.Nm Ldstop +.Nm Ldstop , .Nm Lstop , .Nm Lwait .Nd process and thread stop operations @@ -62,9 +62,10 @@ The function allows the caller to stop and optionally wait for the process handle referred to by .Fa P -to be stopped. Stopping a process causes all of its threads to stop -execution. Where in their execution the threads will halt is not -defined. Threads may be resumed with +to be stopped. +Stopping a process causes all of its threads to stop execution. +Where in their execution the threads will halt is not defined. +Threads may be resumed with .Xr Psetrun 3PROC and .Xr prun 1 . @@ -76,8 +77,8 @@ argument should be one of the following symbols: .It Dv PCSTOP Stop the process; wait for completion before returning. .It Dv PCDSTOP -Stop the process; do not wait for completion before returning. That -is, the stopping of the process is performed asynchronously in +Stop the process; do not wait for completion before returning. +That is, the stopping of the process is performed asynchronously in relation to the caller. .It Dv PCWSTOP Do not direct the process to stop; simply wait for it to stop. @@ -91,14 +92,17 @@ Both the and .Dv PCWSTOP requests allow an upper bound on the amount of time to wait for the -process to stop. The +process to stop. +The .Fa msec argument indicates the number of milliseconds to wait for the stop to -complete. If the value of +complete. +If the value of .Fa msec is .Sy 0 , -then it will wait forever. Callers should pass +then it will wait forever. +Callers should pass .Sy 0 for .Fa msec @@ -108,15 +112,17 @@ or .Dv PCNULL . .Pp When a non-zero timeout is specified, the process may or may not be -stopped upon return. The return value does not reflect the current -state of the process. For example, if the timeout expires during a +stopped upon return. +The return value does not reflect the current state of the process. +For example, if the timeout expires during a .Fa PCWSTOP request, the return value will be .Sy 0 regardless of the actual state of the process. .Pp -Only active processes may be stopped. Handles that refer to core -files, zombie processes, or files cannot be used; unless the value of +Only active processes may be stopped. +Handles that refer to core files, zombie processes, or files cannot be used; +unless the value of .Fa request is set to .Dv PCNULL . @@ -154,8 +160,8 @@ functions are equivalent to the .Fn Pstop , and .Fn Pwait -functions, respectively. Except, rather than operating on a process, -they operate on the thread handle +functions, respectively. +Except, rather than operating on a process, they operate on the thread handle .Fa L . A call to .Fn Lstop @@ -199,7 +205,8 @@ functions will fail if: .It Er EAGAIN Control over the handle .Fa P -was lost. Callers should call +was lost. +Callers should call .Xr Preopen 3PROC . For more information on losing control, see .Sy PROGRAMMING NOTES diff --git a/usr/src/man/man3proc/Psymbol_iter.3proc b/usr/src/man/man3proc/Psymbol_iter.3proc index 37b14ce822..2378a19b9b 100644 --- a/usr/src/man/man3proc/Psymbol_iter.3proc +++ b/usr/src/man/man3proc/Psymbol_iter.3proc @@ -93,7 +93,8 @@ In the case of the .Fn Pxsymbol_iter function an additional .Sy prsyminfo_t -argument will be provided to the callback. The definitions of +argument will be provided to the callback. +The definitions of .Sy proc_sym_f , .Sy proc_xsym_f , and @@ -104,14 +105,16 @@ are found in The .Fa object_name argument names the object that is a part of the controlled process which -will be searched for symbols. Only one object may be searched at any -given time. Valid object names may be obtained through the +will be searched for symbols. +Only one object may be searched at any given time. +Valid object names may be obtained through the .Xr Pobjname 3PROC and .Xr Pobject_iter 3PROC -functions, among others. The system also has two special object names -that may be passed in to refer to the objects of the executable file and -for ld.so.1. The symbol +functions, among others. +The system also has two special object names that may be passed in to refer to +the objects of the executable file and for ld.so.1. +The symbol .Dv PR_OBJ_EXEC refers to the executables object and the symbol .Dv PR_OBJ_LDSO @@ -122,33 +125,38 @@ The argument controls which of two possible symbol tables will be searched. If the argument is .Dv PR_SYMTAB -then the ELF symbol table will be searched. Otherwise, if it is +then the ELF symbol table will be searched. +Otherwise, if it is .Dv PR_DYNSYM then the symbol table associated with the dynamic section will be -searched instead. If any other value is specified for +searched instead. +If any other value is specified for .Fa which , then an error will be returned. .Pp The .Fa mask -argument controls which symbols will be included. The +argument controls which symbols will be included. +The .Fa mask argument allows for control over both the symbol's binding and the -symbol's type. These flags logically correspond to the various ELF -symbol bindings and types. The following values may be passed as a -bitwise-inclusive-OR into the +symbol's type. +These flags logically correspond to the various ELF symbol bindings and types. +The following values may be passed as a bitwise-inclusive-OR into the .Fa flags argument: .Bl -tag -width Dv -offset indent .It Dv BIND_LOCAL -The symbol is a local symbol. Local symbols are not visible outside of -their object file. +The symbol is a local symbol. +Local symbols are not visible outside of their object file. .It Dv BIND_GLOBAL -The symbol is a global symbol. Global symbols are visible outside of -their object file and may be referred to by other ELF objects. +The symbol is a global symbol. +Global symbols are visible outside of their object file and may be referred to +by other ELF objects. .It Dv BIND_WEAK -The symbol is a weak symbol. Weak symbols are visible outside of their -object file, but another definition of the symbol may be used instead. +The symbol is a weak symbol. +Weak symbols are visible outside of their object file, but another definition of +the symbol may be used instead. .It Dv BIND_ANY This is a combination of .Dv BIND_LOCAL , @@ -159,7 +167,8 @@ Every symbol's binding will match this value. .It Dv TYPE_NOTYPE The symbol's type is not specified. .It Dv TYPE_OBJECT -The symbol refers to a data object. For example, variables. +The symbol refers to a data object. +For example, variables. .It Dv TYPE_FUNC The symbol refers to a function. .It Dv TYPE_SECTION @@ -191,28 +200,35 @@ and .Fn Pxsymbol_iter functions allow for a link-map identifier to be specified in the .Fa lmid -argument. This will restrict the search for the object specified in +argument. +This will restrict the search for the object specified in .Fa object_name -to the specified link-map. There are three special link-map identifiers -that may be passed in. The symbol +to the specified link-map. +There are three special link-map identifiers that may be passed in. +The symbol .Dv PR_LMID_EVERY -indicates that every link-map should be searched. The symbol +indicates that every link-map should be searched. +The symbol .Dv LM_ID_BASE indicates that the base link-map, the one that is used for the -executable should be searched. Finally, the symbol +executable should be searched. +Finally, the symbol .Dv LM_ID_LDSO -refers to the link-map that is used by the run-time link editor, -ld.so.1. The functions which do not allow a link-map identifier to be -specified always search every link-map. +refers to the link-map that is used by the run-time link editor, ld.so.1. +The functions which do not allow a link-map identifier to be specified always +search every link-map. .Pp By default, symbols are iterated based on the order of the symbol -table being searched. However, it is also possible to iterate based on -the name of the symbol and based on the address of the symbol. To -iterate by name use the +table being searched. +However, it is also possible to iterate based on the name of the symbol and +based on the address of the symbol. +To iterate by name use the .Fn Psymbol_iter_by_name -function. To iterate by address use the +function. +To iterate by address use the .Fn Psymbol_iter_by_addr -function. The +function. +The .Fn Psymbol_iter , .Fn Psymbol_iter_by_lmid , and @@ -221,11 +237,13 @@ functions all sort based on the order of the symbol table. .Pp The return value of the callback function .Fa func -determines whether or not iteration continues. If +determines whether or not iteration continues. +If .Fa func returns .Sy 0, -then iteration will continue. However, if +then iteration will continue. +However, if .Fa func returns non-zero, then iteration will halt and that value will be used as the return value of the @@ -235,7 +253,8 @@ as the return value of the .Fn Psymbol_iter_by_name , and .Fn Pxsymbol_iter -functions. Because these functions return +functions. +Because these functions return .Sy -1 on internal failure, it is recommended that the callback function not return .Sy -1 @@ -253,7 +272,8 @@ functions return .Sy 0 . If there was an internal error then .Sy -1 -is returned. Otherwise, if the callback function +is returned. +Otherwise, if the callback function .Fa func returns non-zero, then its return value will be returned instead. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/Psync.3proc b/usr/src/man/man3proc/Psync.3proc index 48c7ad5f96..cc5637eedc 100644 --- a/usr/src/man/man3proc/Psync.3proc +++ b/usr/src/man/man3proc/Psync.3proc @@ -34,7 +34,8 @@ The .Fn Psync function synchronizes modifications to the process handle .Fa P -back to the underlying active process. The +back to the underlying active process. +The .Fn Psync function ensures that any outstanding process holds, register modifications, signal injections, and modifications to the various fault @@ -47,9 +48,9 @@ library, calling this function may be required. .Pp The .Fn Psync -function is only meaningful for active processes. It will do nothing on -process handles that refer to core files, zombie processes, and ELF -objects. +function is only meaningful for active processes. +It will do nothing on process handles that refer to core files, zombie +processes, and ELF objects. .Pp The .Fn Lsync diff --git a/usr/src/man/man3proc/Psysentry.3proc b/usr/src/man/man3proc/Psysentry.3proc index 1647b00a83..6190890410 100644 --- a/usr/src/man/man3proc/Psysentry.3proc +++ b/usr/src/man/man3proc/Psysentry.3proc @@ -43,8 +43,9 @@ functions controls what actions the process handle should take upon executing a system call. .Pp The system allows a process to be stopped on both entry and exit of a -system call. For information on the state of the process when it is -stopped due to system call tracing, see the +system call. +For information on the state of the process when it is stopped due to system +call tracing, see the .Sy PCSENTRY and .Sy PCSEXIT @@ -55,18 +56,20 @@ The value of the .Fa stop parameter controls whether or not the system call listed in .Fa which -causes the process to stop. A value of non-zero indicates the process -should stop; a value of 0 indicates it should not. +causes the process to stop. +A value of non-zero indicates the process should stop; +a value of 0 indicates it should not. .Pp The value of .Fa which -indicates which system call the change applies to. A value of 0 -applies to all system calls. Note, the system does not supply a stable -mapping from system call names to identifiers. +indicates which system call the change applies to. +A value of 0 applies to all system calls. +Note, the system does not supply a stable mapping from system call names to +identifiers. .Pp -These functions only apply to actively running processes. They do not -function on handles that refer to core files, zombie processes, or ELF -objects. +These functions only apply to actively running processes. +They do not function on handles that refer to core files, zombie processes, +or ELF objects. .Sh RETURN VALUES Upon successful completion, the .Fn Psetentry @@ -77,7 +80,8 @@ functions return the previous disposition of the system call -- if it was not set to stop and .Sy 1 if it was -- -and the system call state is updated. Otherwise, +and the system call state is updated. +Otherwise, .Sy -1 is returned, .Dv errno diff --git a/usr/src/man/man3proc/Pupdate_maps.3proc b/usr/src/man/man3proc/Pupdate_maps.3proc index bb5dedfb30..7fb482eae2 100644 --- a/usr/src/man/man3proc/Pupdate_maps.3proc +++ b/usr/src/man/man3proc/Pupdate_maps.3proc @@ -32,16 +32,17 @@ process .Fa P are still valid and update the cached data with any new information. This is generally called in response to activity by the run-time -link-editor. In general, the +link-editor. +In general, the .Sy libproc library takes care of managing the need to call this function; however, debuggers, introspection tools, and others that are interposing on rtld activity or other actions, may need to call this function. Note that the .Fn Pupdate_maps -function is only meaningful for active processes. It will do nothing on -process handles that refer to core files, zombie processes, and ELF -objects. +function is only meaningful for active processes. +It will do nothing on process handles that refer to core files, zombie +processes, and ELF objects. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Pupdate_syms.3proc b/usr/src/man/man3proc/Pupdate_syms.3proc index f2305cebd1..9e6e819aa5 100644 --- a/usr/src/man/man3proc/Pupdate_syms.3proc +++ b/usr/src/man/man3proc/Pupdate_syms.3proc @@ -34,16 +34,17 @@ updating, invalidating, and caching new symbol tables as appropriate for functions such as .Xr Psymbol_iter 3PROC . This is generally called in response to activity by the run-time -link-editor. In general, the +link-editor. +In general, the .Sy libproc library takes care of managing the need to call this function; however, debuggers, introspection tools, and others that are -interposing on rtld activity may need to call this function. Note that -the +interposing on rtld activity may need to call this function. +Note that the .Fn Pupdate_syms -function is only meaningful for active processes. It will do nothing on -process handles that refer to core files, zombie processes, and ELF -objects. +function is only meaningful for active processes. +It will do nothing on process handles that refer to core files, zombie +processes, and ELF objects. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/Pwrite.3proc b/usr/src/man/man3proc/Pwrite.3proc index 575cea4a88..411dbb8aae 100644 --- a/usr/src/man/man3proc/Pwrite.3proc +++ b/usr/src/man/man3proc/Pwrite.3proc @@ -38,7 +38,8 @@ starting at the address .Fa address . It writes at most .Fa nbyte -of data. The +of data. +The .Fn Pwrite function is logically analogous to the .Xr pwrite 2 @@ -47,9 +48,10 @@ function. For live processes, this function is equivalent to writing to the /proc file system .Sy as -file for the process. For core files, it writes to the logical address -space of what was once the process and not the corresponding offset in -the on-disk file. ELF objects grabbed through +file for the process. +For core files, it writes to the logical address space of what was once the +process and not the corresponding offset in the on-disk file. +ELF objects grabbed through .Xr Pgrab_file 3PROC do not support being written to. .Pp @@ -70,7 +72,8 @@ Otherwise, it returns .Sy -1 and .Sy errno -is set to indicate an error. For the full list of errors see the +is set to indicate an error. +For the full list of errors see the .Sy DIAGNOSTICS section in .Xr proc 4 diff --git a/usr/src/man/man3proc/Pzonename.3proc b/usr/src/man/man3proc/Pzonename.3proc index 3b2cb8e64e..0dc78d5959 100644 --- a/usr/src/man/man3proc/Pzonename.3proc +++ b/usr/src/man/man3proc/Pzonename.3proc @@ -108,7 +108,7 @@ refers to a core file and zone information was not available in the core dump or .Fa P refers to an ELF object grabbed through -.Xr Pgrab_file . +.Xr Pgrab_file 3PROC . .It Er EFAULT .Fa P refers to an active process and diff --git a/usr/src/man/man3proc/pr_access.3proc b/usr/src/man/man3proc/pr_access.3proc index cc949a7e01..3b4bc1d92c 100644 --- a/usr/src/man/man3proc/pr_access.3proc +++ b/usr/src/man/man3proc/pr_access.3proc @@ -33,7 +33,8 @@ function injects the .Xr access 2 system call into the target process .Fa P -by means of the agent lwp. If the process handle +by means of the agent lwp. +If the process handle .Fa P is .Dv NULL @@ -55,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_access -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_access diff --git a/usr/src/man/man3proc/pr_close.3proc b/usr/src/man/man3proc/pr_close.3proc index af4185fb8d..40d03db923 100644 --- a/usr/src/man/man3proc/pr_close.3proc +++ b/usr/src/man/man3proc/pr_close.3proc @@ -53,9 +53,9 @@ system call and its arguments. .Pp The .Fn pr_close -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_close diff --git a/usr/src/man/man3proc/pr_creat.3proc b/usr/src/man/man3proc/pr_creat.3proc index 9434508002..ee68431f47 100644 --- a/usr/src/man/man3proc/pr_creat.3proc +++ b/usr/src/man/man3proc/pr_creat.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_creat -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_creat diff --git a/usr/src/man/man3proc/pr_door_info.3proc b/usr/src/man/man3proc/pr_door_info.3proc index d1de2ea0c2..7c813827fd 100644 --- a/usr/src/man/man3proc/pr_door_info.3proc +++ b/usr/src/man/man3proc/pr_door_info.3proc @@ -56,9 +56,9 @@ library call and its arguments. .Pp The .Fn pr_door_info -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_door_info diff --git a/usr/src/man/man3proc/pr_exit.3proc b/usr/src/man/man3proc/pr_exit.3proc index 1d156fef5d..30fee8c0ef 100644 --- a/usr/src/man/man3proc/pr_exit.3proc +++ b/usr/src/man/man3proc/pr_exit.3proc @@ -53,9 +53,9 @@ system call and its arguments. .Pp The .Fn pr_exit -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_exit diff --git a/usr/src/man/man3proc/pr_fcntl.3proc b/usr/src/man/man3proc/pr_fcntl.3proc index e6bd11db46..5d081c48ce 100644 --- a/usr/src/man/man3proc/pr_fcntl.3proc +++ b/usr/src/man/man3proc/pr_fcntl.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_fcntl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_fcntl diff --git a/usr/src/man/man3proc/pr_fstatvfs.3proc b/usr/src/man/man3proc/pr_fstatvfs.3proc index b08d834c6c..6e627c5cc4 100644 --- a/usr/src/man/man3proc/pr_fstatvfs.3proc +++ b/usr/src/man/man3proc/pr_fstatvfs.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_fstatvfs -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_fstatvfs diff --git a/usr/src/man/man3proc/pr_getitimer.3proc b/usr/src/man/man3proc/pr_getitimer.3proc index 0f3c5d32d0..43a242c081 100644 --- a/usr/src/man/man3proc/pr_getitimer.3proc +++ b/usr/src/man/man3proc/pr_getitimer.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_getitimer -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getitimer diff --git a/usr/src/man/man3proc/pr_getpeername.3proc b/usr/src/man/man3proc/pr_getpeername.3proc index bf0306c068..228ee7e22b 100644 --- a/usr/src/man/man3proc/pr_getpeername.3proc +++ b/usr/src/man/man3proc/pr_getpeername.3proc @@ -58,9 +58,9 @@ library call and its arguments. .Pp The .Fn pr_getpeername -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getpeername diff --git a/usr/src/man/man3proc/pr_getpeerucred.3proc b/usr/src/man/man3proc/pr_getpeerucred.3proc index 03d8023287..58ef001da1 100644 --- a/usr/src/man/man3proc/pr_getpeerucred.3proc +++ b/usr/src/man/man3proc/pr_getpeerucred.3proc @@ -56,9 +56,9 @@ library call and its arguments. .Pp The .Fn pr_getpeerucred -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getpeerucred diff --git a/usr/src/man/man3proc/pr_getprojid.3proc b/usr/src/man/man3proc/pr_getprojid.3proc index bc209e4eb2..88426b99c4 100644 --- a/usr/src/man/man3proc/pr_getprojid.3proc +++ b/usr/src/man/man3proc/pr_getprojid.3proc @@ -42,9 +42,9 @@ on the currently running process. .Pp The .Fn pr_getprojid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getprojid diff --git a/usr/src/man/man3proc/pr_getrctl.3proc b/usr/src/man/man3proc/pr_getrctl.3proc index 7f46a0ad48..5725417a6b 100644 --- a/usr/src/man/man3proc/pr_getrctl.3proc +++ b/usr/src/man/man3proc/pr_getrctl.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_getrctl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getrctl diff --git a/usr/src/man/man3proc/pr_getrlimit.3proc b/usr/src/man/man3proc/pr_getrlimit.3proc index c1f17bfa8a..adcb0480f8 100644 --- a/usr/src/man/man3proc/pr_getrlimit.3proc +++ b/usr/src/man/man3proc/pr_getrlimit.3proc @@ -63,17 +63,17 @@ system call and its arguments. .Pp The .Fn pr_getrlimit -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Pp The .Fn pr_getrlimit64 function is equivalent to .Fn pr_getrlimit ; -however, rather than having the rlimit information be subject to the -data model of the target process, they always provide 64-bit rlimit -information. See +however, rather than having the rlimit information be subject to the data model +of the target process, they always provide 64-bit rlimit information. +See .Xr lf64 5 for more information. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/pr_getsockname.3proc b/usr/src/man/man3proc/pr_getsockname.3proc index 125378d2ab..9ec6eca88e 100644 --- a/usr/src/man/man3proc/pr_getsockname.3proc +++ b/usr/src/man/man3proc/pr_getsockname.3proc @@ -58,9 +58,9 @@ library call and its arguments. .Pp The .Fn pr_getsockname -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support library -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support library call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getsockname diff --git a/usr/src/man/man3proc/pr_getsockopt.3proc b/usr/src/man/man3proc/pr_getsockopt.3proc index 6edb92fe08..1bd5dae0b9 100644 --- a/usr/src/man/man3proc/pr_getsockopt.3proc +++ b/usr/src/man/man3proc/pr_getsockopt.3proc @@ -62,9 +62,9 @@ system call and its arguments. .Pp The .Fn pr_getsockopt -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getsockopt diff --git a/usr/src/man/man3proc/pr_gettaskid.3proc b/usr/src/man/man3proc/pr_gettaskid.3proc index 0c52d800d4..783a5560bb 100644 --- a/usr/src/man/man3proc/pr_gettaskid.3proc +++ b/usr/src/man/man3proc/pr_gettaskid.3proc @@ -42,9 +42,9 @@ on the currently running process. .Pp The .Fn pr_gettaskid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_gettaskid diff --git a/usr/src/man/man3proc/pr_getzoneid.3proc b/usr/src/man/man3proc/pr_getzoneid.3proc index 8cd2e29c5c..8304eb232d 100644 --- a/usr/src/man/man3proc/pr_getzoneid.3proc +++ b/usr/src/man/man3proc/pr_getzoneid.3proc @@ -42,9 +42,9 @@ on the currently running process. .Pp The .Fn pr_getzoneid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_getzoneid diff --git a/usr/src/man/man3proc/pr_ioctl.3proc b/usr/src/man/man3proc/pr_ioctl.3proc index 24b47be548..dbe1d52a49 100644 --- a/usr/src/man/man3proc/pr_ioctl.3proc +++ b/usr/src/man/man3proc/pr_ioctl.3proc @@ -68,9 +68,9 @@ target process. .Pp The .Fn pr_ioctl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_ioctl diff --git a/usr/src/man/man3proc/pr_link.3proc b/usr/src/man/man3proc/pr_link.3proc index a80012df77..b981405f39 100644 --- a/usr/src/man/man3proc/pr_link.3proc +++ b/usr/src/man/man3proc/pr_link.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_link -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_link diff --git a/usr/src/man/man3proc/pr_llseek.3proc b/usr/src/man/man3proc/pr_llseek.3proc index 28fa432dba..2d88e53ba6 100644 --- a/usr/src/man/man3proc/pr_llseek.3proc +++ b/usr/src/man/man3proc/pr_llseek.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_llseek -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_llseek diff --git a/usr/src/man/man3proc/pr_lseek.3proc b/usr/src/man/man3proc/pr_lseek.3proc index 8e96274898..bea7e7bb3a 100644 --- a/usr/src/man/man3proc/pr_lseek.3proc +++ b/usr/src/man/man3proc/pr_lseek.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_lseek -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_lseek diff --git a/usr/src/man/man3proc/pr_memcntl.3proc b/usr/src/man/man3proc/pr_memcntl.3proc index dba3f05a12..e77e7debd7 100644 --- a/usr/src/man/man3proc/pr_memcntl.3proc +++ b/usr/src/man/man3proc/pr_memcntl.3proc @@ -64,9 +64,9 @@ system call and its arguments. .Pp The .Fn pr_memcntl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_memcntl diff --git a/usr/src/man/man3proc/pr_meminfo.3proc b/usr/src/man/man3proc/pr_meminfo.3proc index 3da4983f91..7e6dfae222 100644 --- a/usr/src/man/man3proc/pr_meminfo.3proc +++ b/usr/src/man/man3proc/pr_meminfo.3proc @@ -64,9 +64,9 @@ system call and its arguments. .Pp The .Fn pr_meminfo -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_meminfo diff --git a/usr/src/man/man3proc/pr_mmap.3proc b/usr/src/man/man3proc/pr_mmap.3proc index 966979337f..988f79dede 100644 --- a/usr/src/man/man3proc/pr_mmap.3proc +++ b/usr/src/man/man3proc/pr_mmap.3proc @@ -64,9 +64,9 @@ system call and its arguments. .Pp The .Fn pr_mmap -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_mmap diff --git a/usr/src/man/man3proc/pr_munmap.3proc b/usr/src/man/man3proc/pr_munmap.3proc index ede8fcd12c..0573cc4a2a 100644 --- a/usr/src/man/man3proc/pr_munmap.3proc +++ b/usr/src/man/man3proc/pr_munmap.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_munmap -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_munmap diff --git a/usr/src/man/man3proc/pr_open.3proc b/usr/src/man/man3proc/pr_open.3proc index d462520976..9a15a11428 100644 --- a/usr/src/man/man3proc/pr_open.3proc +++ b/usr/src/man/man3proc/pr_open.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_open -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_open diff --git a/usr/src/man/man3proc/pr_processor_bind.3proc b/usr/src/man/man3proc/pr_processor_bind.3proc index 4890b051e7..f30d6095d5 100644 --- a/usr/src/man/man3proc/pr_processor_bind.3proc +++ b/usr/src/man/man3proc/pr_processor_bind.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_processor_bind -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_processor_bind diff --git a/usr/src/man/man3proc/pr_rename.3proc b/usr/src/man/man3proc/pr_rename.3proc index f7306778c5..a7b9a33762 100644 --- a/usr/src/man/man3proc/pr_rename.3proc +++ b/usr/src/man/man3proc/pr_rename.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_rename -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_rename diff --git a/usr/src/man/man3proc/pr_setitimer.3proc b/usr/src/man/man3proc/pr_setitimer.3proc index 8226390331..dc777fdd1d 100644 --- a/usr/src/man/man3proc/pr_setitimer.3proc +++ b/usr/src/man/man3proc/pr_setitimer.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_setitimer -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_setitimer diff --git a/usr/src/man/man3proc/pr_setrctl.3proc b/usr/src/man/man3proc/pr_setrctl.3proc index 186b1843cc..75ed161f20 100644 --- a/usr/src/man/man3proc/pr_setrctl.3proc +++ b/usr/src/man/man3proc/pr_setrctl.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_setrctl -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_setrctl diff --git a/usr/src/man/man3proc/pr_setrlimit.3proc b/usr/src/man/man3proc/pr_setrlimit.3proc index 1282c86f1b..b7658278d2 100644 --- a/usr/src/man/man3proc/pr_setrlimit.3proc +++ b/usr/src/man/man3proc/pr_setrlimit.3proc @@ -63,17 +63,17 @@ system call and its arguments. .Pp The .Fn pr_setrlimit -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Pp The .Fn pr_setrlimit64 function is equivalent to .Fn pr_setrlimit ; -however, rather than having the rlimit information be subject to the -data model of the target process, they always provide 64-bit rlimit -information. See +however, rather than having the rlimit information be subject to the data model +of the target process, they always provide 64-bit rlimit information. +See .Xr lf64 5 for more information. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/pr_settaskid.3proc b/usr/src/man/man3proc/pr_settaskid.3proc index 663bb6ed83..368cc4243a 100644 --- a/usr/src/man/man3proc/pr_settaskid.3proc +++ b/usr/src/man/man3proc/pr_settaskid.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_settaskid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_settaskid diff --git a/usr/src/man/man3proc/pr_sigaction.3proc b/usr/src/man/man3proc/pr_sigaction.3proc index 937f2c1f18..4103a0e203 100644 --- a/usr/src/man/man3proc/pr_sigaction.3proc +++ b/usr/src/man/man3proc/pr_sigaction.3proc @@ -58,9 +58,9 @@ system call and its arguments. .Pp The .Fn pr_sigaction -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_sigaction diff --git a/usr/src/man/man3proc/pr_stat.3proc b/usr/src/man/man3proc/pr_stat.3proc index 7c6f26ff4a..f9095db692 100644 --- a/usr/src/man/man3proc/pr_stat.3proc +++ b/usr/src/man/man3proc/pr_stat.3proc @@ -16,7 +16,7 @@ .Os .Sh NAME .Nm pr_fstat , -.Nm pr_fstat64 +.Nm pr_fstat64 , .Nm pr_lstat , .Nm pr_lstat64 , .Nm pr_stat , @@ -133,9 +133,9 @@ The .Fn pr_lstat , and .Fn pr_fstat -functions only work on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +functions only work on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Pp The .Fn pr_stat64 , @@ -147,9 +147,9 @@ functions are equivalent to .Fn pr_fstat , and .Fn pr_lstat -respectively; however, rather than having the stat information be -subject to the data model of the target process, they always provide -64-bit stat information. See +respectively; however, rather than having the stat information be subject to the +data model of the target process, they always provide 64-bit stat information. +See .Xr lf64 5 for more information. .Sh RETURN VALUES diff --git a/usr/src/man/man3proc/pr_statvfs.3proc b/usr/src/man/man3proc/pr_statvfs.3proc index 05dc23cf00..30a8a4c90b 100644 --- a/usr/src/man/man3proc/pr_statvfs.3proc +++ b/usr/src/man/man3proc/pr_statvfs.3proc @@ -56,9 +56,9 @@ system call and its arguments. .Pp The .Fn pr_statvfs -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_statvfs diff --git a/usr/src/man/man3proc/pr_unlink.3proc b/usr/src/man/man3proc/pr_unlink.3proc index b1f96a2384..0dbf9702ef 100644 --- a/usr/src/man/man3proc/pr_unlink.3proc +++ b/usr/src/man/man3proc/pr_unlink.3proc @@ -53,9 +53,9 @@ system call and its arguments. .Pp The .Fn pr_unlink -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_unlink diff --git a/usr/src/man/man3proc/pr_waitid.3proc b/usr/src/man/man3proc/pr_waitid.3proc index 0efd563722..9eceeb7eab 100644 --- a/usr/src/man/man3proc/pr_waitid.3proc +++ b/usr/src/man/man3proc/pr_waitid.3proc @@ -60,9 +60,9 @@ system call and its arguments. .Pp The .Fn pr_waitid -function only works on active processes. Process handles that correspond -to core files, zombie processes, or ELF objects do not support system -call injection. +function only works on active processes. +Process handles that correspond to core files, zombie processes, or ELF objects +do not support system call injection. .Sh RETURN VALUES Upon successful completion, the .Fn pr_waitid diff --git a/usr/src/man/man3proc/proc_arg_grab.3proc b/usr/src/man/man3proc/proc_arg_grab.3proc index be9c7c1b02..375ba4d67e 100644 --- a/usr/src/man/man3proc/proc_arg_grab.3proc +++ b/usr/src/man/man3proc/proc_arg_grab.3proc @@ -48,8 +48,8 @@ it. .Pp The string .Fa arg -contains the name of something to try and open. How it is interpreted -depends on the value of +contains the name of something to try and open. +How it is interpreted depends on the value of .Fa oflag . The following values may be passed in as a bitwise-exclusive-OR for .Fa oflag : @@ -69,8 +69,8 @@ Encompasses all of the previous opens. The argument .Fa gflag controls the behavior when the corresponding process grabbing function -is called by the underlying system. For a list of flags that may be -passed in here, see +is called by the underlying system. +For a list of flags that may be passed in here, see .Xr Pgrab 3PROC and .Xr Pgrab_core 3PROC . diff --git a/usr/src/man/man3proc/proc_arg_psinfo.3proc b/usr/src/man/man3proc/proc_arg_psinfo.3proc index 40af3572a3..2ebab46fc7 100644 --- a/usr/src/man/man3proc/proc_arg_psinfo.3proc +++ b/usr/src/man/man3proc/proc_arg_psinfo.3proc @@ -49,8 +49,8 @@ information from the process or core and fills it into .Pp The string .Fa arg -contains the name of something to try and open. How it is interpreted -depends on the value of +contains the name of something to try and open. +How it is interpreted depends on the value of .Fa oflag . The following values may be passed in as a bitwise-exclusive-OR for .Fa oflag : @@ -98,7 +98,8 @@ and .Fn proc_arg_xpsinfo functions return the process identifier and fill in .Fa psp -with the ps information of the process. Otherwise, +with the ps information of the process. +Otherwise, .Sy -1 is returned and .Fa perr diff --git a/usr/src/man/man3proc/proc_content2str.3proc b/usr/src/man/man3proc/proc_content2str.3proc index 01f3b6a979..4b01158d95 100644 --- a/usr/src/man/man3proc/proc_content2str.3proc +++ b/usr/src/man/man3proc/proc_content2str.3proc @@ -49,8 +49,8 @@ together with the or .Sy - characters, indicating that the subsequent token should be added or -subtracted from the previous ones. The full list of tokens and constants -is available in the +subtracted from the previous ones. +The full list of tokens and constants is available in the .Sy core_content_t portion of the .Sy TYPES diff --git a/usr/src/man/man3proc/proc_fltset2str.3proc b/usr/src/man/man3proc/proc_fltset2str.3proc index 08e43c531f..96c40eeab2 100644 --- a/usr/src/man/man3proc/proc_fltset2str.3proc +++ b/usr/src/man/man3proc/proc_fltset2str.3proc @@ -64,14 +64,16 @@ Up to .Fa buflen characters will be placed in .Fa buf , -including the null terminator. If +including the null terminator. +If .Fa buf is not large enough to hold the entire string, then an error will be returned. .Pp The .Fa members -argument controls which members of the set are written out. If +argument controls which members of the set are written out. +If .Fa members is .Sy 1 , @@ -86,8 +88,8 @@ then the members which are not in the set are placed in .Pp The string .Fa delim -will be placed in-between every member of the set. It will not come after -the last entry in the set. +will be placed in-between every member of the set. +It will not come after the last entry in the set. .Sh RETURN VALUES Upon successful completion, the .Fn proc_fltset2str , diff --git a/usr/src/man/man3proc/proc_get_cred.3proc b/usr/src/man/man3proc/proc_get_cred.3proc index dbdb08c379..ddff00283b 100644 --- a/usr/src/man/man3proc/proc_get_cred.3proc +++ b/usr/src/man/man3proc/proc_get_cred.3proc @@ -36,7 +36,8 @@ Up to .Fa ngroups supplemental groups will be read and written into .Fa credp -in addition to the normal information. If +in addition to the normal information. +If .Fa ngroups is more than one, than it is up to the caller to have allocated enough space for diff --git a/usr/src/man/man3proc/proc_get_priv.3proc b/usr/src/man/man3proc/proc_get_priv.3proc index bc83a7d604..d70c293cec 100644 --- a/usr/src/man/man3proc/proc_get_priv.3proc +++ b/usr/src/man/man3proc/proc_get_priv.3proc @@ -38,8 +38,8 @@ process The .Fn proc_get_priv function takes care of allocating memory for the privilege set and -ensures that it is large enough to hold all of the privilege sets. The -definition of the +ensures that it is large enough to hold all of the privilege sets. +The definition of the .Sy prpriv_t structure may be found in .Xr proc 4 . diff --git a/usr/src/man/man3proc/proc_initstdio.3proc b/usr/src/man/man3proc/proc_initstdio.3proc index 315f717f81..5576c33dfa 100644 --- a/usr/src/man/man3proc/proc_initstdio.3proc +++ b/usr/src/man/man3proc/proc_initstdio.3proc @@ -41,17 +41,19 @@ The and .Fn proc_finistdio functions are utilities provided to aid with the possibility of deadlock -while doing I/O operations. If a process is trying to do I/O, but -holding the process handle that would consume that I/O, then eventually -the program holding the process handle will block as none of its I/O has -been drained. However, because it is holding a process handle to that -process, it will never be drained. +while doing I/O operations. +If a process is trying to do I/O, but holding the process handle that would +consume that I/O, then eventually the program holding the process handle will +block as none of its I/O has been drained. +However, because it is holding a process handle to that process, it will never +be drained. .Pp Consider, for example, the following invocation: .Li pfiles `pgrep xterm` -where the command was launched from a shell on an xterm. Because the -xterm is stopped, it will not be able to write out any of the standard -out that gets passed to it, leading to a deadlock. The +where the command was launched from a shell on an xterm. +Because the xterm is stopped, it will not be able to write out any of the +standard out that gets passed to it, leading to a deadlock. +The .Li pfiles program cannot release the .Li xterm @@ -60,9 +62,9 @@ due to the same hold. .Pp To address this, these functions duplicate the standard output and standard error of the process to temporary files and then flushes it out -to the original file descriptors and streams later. When finished, the -original file descriptors are restored as standard out and standard -error. +to the original file descriptors and streams later. +When finished, the original file descriptors are restored as standard out and +standard error. .Pp The .Fn proc_initstdio @@ -72,9 +74,10 @@ descriptors and retains the originals. The .Fn proc_flushstdio functions flushes all of the cached data from the temporary standard out -and standard error back to the underlying ones. This function should -only be called after all process handles have been released. For -example, if iterating on multiple processes, calling this after handling +and standard error back to the underlying ones. +This function should only be called after all process handles have been +released. +For example, if iterating on multiple processes, calling this after handling each one is safe. .Pp The diff --git a/usr/src/man/man3proc/proc_lwp_in_set.3proc b/usr/src/man/man3proc/proc_lwp_in_set.3proc index 62f3596d6e..bea97c1a71 100644 --- a/usr/src/man/man3proc/proc_lwp_in_set.3proc +++ b/usr/src/man/man3proc/proc_lwp_in_set.3proc @@ -38,8 +38,8 @@ functions provide means for testing the validity of thread ranges and whether a thread is in a range. .Pp A thread range is a series of one or more series of range identifiers -which describe a collection of threads. These are often used by programs -such as +which describe a collection of threads. +These are often used by programs such as .Xr pbind 1M , .Xr pstack 1 , .Xr prun 1 , @@ -52,8 +52,8 @@ More formally, the thread range may be described as: lwp_range[,lwp_range]* .Ed .Pp -An LWP range may be specified as one of the following four strings. The -following table shows the string formats and the corresponding set of +An LWP range may be specified as one of the following four strings. +The following table shows the string formats and the corresponding set of valid threads that match it: .Bl -column -offset indent ".Sy n-m" "n <= lwpid <= m" .It Sy -n Ta lwpid <= n @@ -70,8 +70,8 @@ The .Fn proc_lwp_range_valid function determines whether or not the character string .Fa set -is a valid thread range based on the rules above. Note, the empty -string, the +is a valid thread range based on the rules above. +Note, the empty string, the .Dv NULL pointer, or otherwise are not valid. .Pp @@ -108,7 +108,8 @@ function returns .Sy 0 to indicate .Fa set -is valid. Otherwise, +is valid. +Otherwise, .Sy -1 is returned to indicate that the set is invalid. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/proc_str2flt.3proc b/usr/src/man/man3proc/proc_str2flt.3proc index 672fbf98bb..2b7ef2edff 100644 --- a/usr/src/man/man3proc/proc_str2flt.3proc +++ b/usr/src/man/man3proc/proc_str2flt.3proc @@ -63,7 +63,8 @@ and update .Fa signum , and .Fa sysnum -respectively. Otherwise, +respectively. +Otherwise, .Sy -1 is returned to indicate that a conversion could not take place. .Sh INTERFACE STABILITY diff --git a/usr/src/man/man3proc/proc_str2fltset.3proc b/usr/src/man/man3proc/proc_str2fltset.3proc index ebc8e60be5..e1fd1f5359 100644 --- a/usr/src/man/man3proc/proc_str2fltset.3proc +++ b/usr/src/man/man3proc/proc_str2fltset.3proc @@ -91,8 +91,8 @@ Upon successful completion, .Dv NULL is returned and .Fa set -is filled in. Otherwise, a pointer to the first unknown character is -returned and +is filled in. +Otherwise, a pointer to the first unknown character is returned and .Sy errno is set to indicate the error. .Sh ERRORS diff --git a/usr/src/man/man3proc/proc_unctrl_psinfo.3proc b/usr/src/man/man3proc/proc_unctrl_psinfo.3proc index f5bff350a6..0ad264a4e8 100644 --- a/usr/src/man/man3proc/proc_unctrl_psinfo.3proc +++ b/usr/src/man/man3proc/proc_unctrl_psinfo.3proc @@ -31,10 +31,10 @@ function walks the process arguments of the .Fa psp structure (the .Sy pr_psargs -member) converting unprintable characters into spaces. The conversion -continues until a null character is encountered. Note, this routine only -will correctly handle 7-bit ASCII characters. Characters in other -encodings, e.g. UTF-8, may be misinterpreted as unprintable. +member) converting unprintable characters into spaces. +The conversion continues until a null character is encountered. +Note, this routine only will correctly handle 7-bit ASCII characters. +Characters in other encodings, e.g. UTF-8, may be misinterpreted as unprintable. .Sh INTERFACE STABILITY .Sy Uncommitted .Sh MT-LEVEL diff --git a/usr/src/man/man3proc/proc_walk.3proc b/usr/src/man/man3proc/proc_walk.3proc index cc9a831bec..c1d1158d77 100644 --- a/usr/src/man/man3proc/proc_walk.3proc +++ b/usr/src/man/man3proc/proc_walk.3proc @@ -49,13 +49,15 @@ The value of controls whether or not information about the threads in the process are included and how many times the callback function .Fa func -is called. The following values may be passed in for +is called. +The following values may be passed in for .Fa flag : .Bl -tag -width Dv -offset indent .It Dv PR_WALK_PROC Indicates that the walker is only concerned with the process. .Fa func -will be called once for each process in the system. Only the +will be called once for each process in the system. +Only the .Sy psinfo will be read for the process and passed to .Fa func . @@ -66,8 +68,8 @@ will be passed as .It Dv PR_WALK_LWP The caller wants both process and thread information. .Fa func -will be called once for each thread in the system. In addition to the -process +will be called once for each thread in the system. +In addition to the process .Sy psinfo information, the ps specific information for a given thread will be included in the @@ -77,12 +79,13 @@ argument. .Pp The return value of the caller's .Fa func -function determines whether or not iteration will continue. If +function determines whether or not iteration will continue. +If .Fa func returns a non-zero value, then iteration will terminate and that -return value will be returned to the caller. To distinguish between -system errors and caller errors, it is recommended that the function -only return positive integers in the event of an error. +return value will be returned to the caller. +To distinguish between system errors and caller errors, it is recommended that +the function only return positive integers in the event of an error. .Sh RETURN VALUES Upon successful completion, the .Fn proc_walk diff --git a/usr/src/man/man3socket/sockaddr.3socket b/usr/src/man/man3socket/sockaddr.3socket index cd578e9bcd..992601ba01 100644 --- a/usr/src/man/man3socket/sockaddr.3socket +++ b/usr/src/man/man3socket/sockaddr.3socket @@ -65,7 +65,8 @@ The .Nm family of structures are designed to represent network addresses for -different networking protocols. The structure +different networking protocols. +The structure .Sy struct sockaddr is a generic structure that is used across calls to various socket library routines @@ -98,13 +99,15 @@ char sa_data[] /* socket address (variable-length data) */ .Lp The member .Em sa_family -corresponds to the socket family that's actually in use. The following -table describes the mapping between the address family and the -corresponding socket structure that's used. Note that both the generic +corresponds to the socket family that's actually in use. +The following table describes the mapping between the address family and the +corresponding socket structure that's used. +Note that both the generic .Sy struct sockaddr and the .Sy struct sockaddr_storage -are not included, because these are both generic structures. More on the +are not included, because these are both generic structures. +More on the .Sy struct sockaddr_storage can be found in the next section. .Bl -column -offset indent ".Sy Socket Structure" ".Sy Address Family" @@ -120,18 +123,19 @@ The .Sy sockaddr_storage structure is a .Nm -that is not associated with an address family. Instead, it is large -enough to hold the contents of any of the other +that is not associated with an address family. +Instead, it is large enough to hold the contents of any of the other .Nm -structures. It can be used to embed sufficient storage for a +structures. +It can be used to embed sufficient storage for a .Sy sockaddr of any type within a larger structure. .Lp -The structure only has a single member defined. While there are other -members that are used to pad out the size of the +The structure only has a single member defined. +While there are other members that are used to pad out the size of the .Sy struct sockaddr_storage , -they are not defined and must not be consumed. The only valid -member is: +they are not defined and must not be consumed. +The only valid member is: .Bd -literal -offset indent sa_family_t ss_family /* address family */ .Ed @@ -142,8 +146,8 @@ is useful when running a service that accepts traffic over both .Sy IPv4 and .Sy IPv6 -where it is common to use a single socket for both address families. In that -case, rather than guessing whether a +where it is common to use a single socket for both address families. +In that case, rather than guessing whether a .Sy struct sockaddr_in or a .Sy struct sockaddr_in6 @@ -156,7 +160,8 @@ value of the member The .Sy sockaddr_in is the socket type which is used for for the Internet Protocol version -four (IPv4). It has the following members defined: +four (IPv4). +It has the following members defined: .Bd -literal -offset indent sa_family_t sin_family /* address family */ in_port_t sin_port /* IP port */ @@ -173,13 +178,16 @@ The members .Em sin_port and .Em sin_addr -describe the IP address and IP port to use. In the case of a call to +describe the IP address and IP port to use. +In the case of a call to .Xr connect 3SOCKET these represent the remote IP address and port to which the connection -is being made. In the case of +is being made. +In the case of .Xr bind 3SOCKET these represent the IP address and port on the local host to which the socket -is to be bound. In the case of +is to be bound. +In the case of .Xr accept 3SOCKET these represent the remote IP address and port of the machine whose connection was accepted. @@ -195,14 +203,16 @@ and write to the member with the function .Xr htons 3SOCKET . The member .Em sin_addr -is the four byte IPv4 address. It is also stored in network byte order. +is the four byte IPv4 address. +It is also stored in network byte order. The common way to write out the address is to use the function .Xr inet_pton 3SOCKET which converts between a human readable IP address such as "10.1.2.3" and the corresponding representation. .Lp Example 1 shows how to prepare an IPv4 socket and deal with -network byte-order. See +network byte-order. +See .Xr inet 7P and .Xr ip 7P @@ -212,7 +222,8 @@ The .Sy sockaddr_in6 structure is the .Nm -for the Internet Protocol version six (IPv6). Unlike the +for the Internet Protocol version six (IPv6). +Unlike the .Sy struct sockaddr_in , the .Sy struct sockaddr_in6 @@ -223,7 +234,8 @@ or .Xr memset 3C . If the entire .Sy struct sockaddr_in6 -is not zeroed before use, applications will experience undefined behavior. The +is not zeroed before use, applications will experience undefined behavior. +The .Sy struct sockaddr_in6 has the following public members: .Bd -literal -offset indent @@ -248,7 +260,8 @@ are the IPv6 equivalents of the and .Em sin_addr . Like their IPv4 counterparts, both of these members must be in network -byte order. The member +byte order. +The member .Em sin6_port describes the IPv6 port and should be manipulated with the functions .Xr ntohs 3SOCKET @@ -256,7 +269,8 @@ and .Xr htons 3SOCKET . The member .Em sin6_addr -describes the 16-byte IPv6 address. In addition to the function +describes the 16-byte IPv6 address. +In addition to the function .Xr inet_pton 3SOCKET , the header file .In netinet/in.h @@ -265,7 +279,8 @@ defines many macros for manipulating and testing IPv6 addresses. The member .Em sin6_flowinfo contains the traffic class and flow label associated with the IPv6 -header. The member +header. +The member .Em sin6_scope_id may contain an identifier which varies based on the scope of the address in @@ -275,7 +290,8 @@ Applications do not need to initialize it will be populated by the operating system as a result of various library calls. .Lp -Example 2 shows how to prepare an IPv6 socket. For more information on +Example 2 shows how to prepare an IPv6 socket. +For more information on IPv6, please see .Xr inet6 7P and @@ -286,7 +302,8 @@ The structure specifies the address of a socket used to communicate between processes running on a single system, commonly known as a .Em UNIX domain socket . -Sockets of this type are identified by a path in the file system. The +Sockets of this type are identified by a path in the file system. +The .Sy struct sockaddr_un has the following members: .Bd -literal -offset indent @@ -302,15 +319,15 @@ The member .Em sun_path is populated with a .Sy NUL -terminated array of characters that specify a file system path. The maximum -length of any such path, including the +terminated array of characters that specify a file system path. +The maximum length of any such path, including the .Sy NUL terminator, is 108 bytes. .Ss struct sockaddr_dl The .Sy sockaddr_dl -structure is used to describe a layer 2 link-level address. This is used -as part of various socket ioctls, such as those for +structure is used to describe a layer 2 link-level address. +This is used as part of various socket ioctls, such as those for .Xr arp 7P . The structure has the following members: .Bd -literal -offset indent @@ -334,17 +351,20 @@ the .Sy struct sockaddr_dl . This identifier is the same identifier that's shown by tools like .Xr ifconfig 1M -and used in the SIOC* set of socket ioctls. The member +and used in the SIOC* set of socket ioctls. +The member .Em sdl_type -refers to the media that is used for the socket. The most common case is -that the medium for the interface is Ethernet which has the value +refers to the media that is used for the socket. +The most common case is that the medium for the interface is Ethernet which has +the value .Sy IFT_ETHER . The full set of types is derived from RFC1573 and recorded in the file .In net/if_types.h . The member .Em sdl_slen describes the length of a selector, if it exists, for the specified -medium. This is used in protocols such as Trill. +medium. +This is used in protocols such as Trill. .Lp The .Em sdl_data , @@ -352,7 +372,8 @@ The and .Em sdl_alen members together describe a character string containing the interface name and -the link-layer network address. The name starts at the beginning of +the link-layer network address. +The name starts at the beginning of .Em sdl_data , i.e. at .Em sdl_data[0] . @@ -360,10 +381,12 @@ The name of the interface occupies the next .Em sdl_nlen bytes and is not .Sy NUL -terminated. The link-layer network address begins immediately after the -interface name, and is +terminated. +The link-layer network address begins immediately after the interface name, +and is .Em sdl_alen -bytes long. The macro +bytes long. +The macro .Sy LLADDR(struct sockaddr_dl *) returns the start of the link-layer network address. The interpretation of the link-layer address depends on the value of @@ -377,8 +400,9 @@ The is used as part of a socket type which is responsible for packet capture: .Sy AF_PACKET -sockets. It is generally designed for use with Ethernet networks. The members -of the +sockets. +It is generally designed for use with Ethernet networks. +The members of the .Sy struct sockaddr_ll are: .Bd -literal -offset indent @@ -397,11 +421,11 @@ must be .Sy AF_PACKET . The member .Em sll_protocol -refers to a link-layer protocol. For example, when capturing Ethernet frames -the value of +refers to a link-layer protocol. +For example, when capturing Ethernet frames the value of .Em sll_protocol -is the Ethertype. This member is written in network byte order and -applications should use +is the Ethertype. +This member is written in network byte order and applications should use .Xr htons 3SOCKET and .Xr ntohs 3SOCKET @@ -409,8 +433,8 @@ to read and write the member. .Lp The member .Em sll_ifindex -is the interface's index. It is used as an identifier in various ioctls -and included in the output of +is the interface's index. +It is used as an identifier in various ioctls and included in the output of .Xr ifconfig 1M . When calling .Xr bind 3SOCKET @@ -454,10 +478,11 @@ to connect to a remote host .Lp The following example shows how one would open a socket and prepare it to connect to the remote host whose address is the IP address 127.0.0.1 -on port 80. This program should be compiled with the C compiler +on port 80. +This program should be compiled with the C compiler .Sy cc -and linked against the libraries libsocket and libnsl. If this example -was named ip4.c, then the full link line would be +and linked against the libraries libsocket and libnsl. +If this example was named ip4.c, then the full link line would be .Ic cc ip4.c -lsocket -lnsl . .Bd -literal #include <sys/types.h> @@ -504,11 +529,11 @@ Preparing an IPv6 to bind to a local address .Lp The following example shows how one would open a socket and prepare it -to bind to the local IPv6 address ::1 port on port 12345. This program -should be compiled with the C compiler +to bind to the local IPv6 address ::1 port on port 12345. +This program should be compiled with the C compiler .Sy cc -and linked against the libraries libsocket and libnsl. If this example -was named ip6.c, then the full compiler line would be +and linked against the libraries libsocket and libnsl. +If this example was named ip6.c, then the full compiler line would be .Ic cc ip6.c -lsocket -lnsl . .Bd -literal #include <sys/types.h> diff --git a/usr/src/man/man4/Intro.4 b/usr/src/man/man4/Intro.4 index 7ece0b0164..ce2f7eb2f7 100644 --- a/usr/src/man/man4/Intro.4 +++ b/usr/src/man/man4/Intro.4 @@ -28,9 +28,10 @@ .Nd introduction to file formats and configurations .Sh DESCRIPTION This section outlines the formats of various files and configurations of -various subsystems. The C structure declarations for the file formats are -given where applicable. Usually, the headers containing these structure -declarations can be found in the directories +various subsystems. +The C structure declarations for the file formats are given where applicable. +Usually, the headers containing these structure declarations can be found in the +directories .Pa /usr/include or .Pa /usr/include/sys . diff --git a/usr/src/man/man4/autofs.4 b/usr/src/man/man4/autofs.4 index a7db140f06..1bc8567869 100644 --- a/usr/src/man/man4/autofs.4 +++ b/usr/src/man/man4/autofs.4 @@ -49,24 +49,29 @@ The following list describes the properties: .Bl -tag -width Ds .It Sy timeout Ns = Ns Ar num Specifies a duration, in seconds, that a file system is to remain mounted when -not in use. The default value is 600 +not in use. +The default value is 600 .Pq 10 minutes . Equivalent to the .Fl t option in .Nm automount . .It Sy automount_verbose Ns = Ns Sy true Ns | Ns Sy false -Verbose mode. Causes you to be notified of non-critical events, such as +Verbose mode. +Causes you to be notified of non-critical events, such as .Nm -mounts and unmounts. The default value is +mounts and unmounts. +The default value is .Sy false . Equivalent to the .Fl v option in .Nm automount . .It Sy automountd_verbose Ns = Ns Sy true Ns | Ns Sy false -Verbose mode. Causes status messages to be logged to the -svc:/system/filesystem/autofs:default log file. The default value is +Verbose mode. +Causes status messages to be logged to the svc:/system/filesystem/autofs:default +log file. +The default value is .Sy false . Equivalent to the .Fl v @@ -75,7 +80,8 @@ option in .It Sy nobrowse Ns = Ns Sy true Ns | Ns Sy false Turn on or off browsing for all .Nm -mount points. The default value is +mount points. +The default value is .Sy false . Equivalent to the .Fl n @@ -83,15 +89,17 @@ option in .Nm automountd . .It Sy trace Ns = Ns Ar num Expands each RPC call and logs it to svc:/system/filesystem/autofs:default -log file. The default value, 0, turns off such tracing. Starting with 1, -with each higher value, the verbosity of trace output increases. +log file. +The default value, 0, turns off such tracing. +Starting with 1, with each higher value, the verbosity of trace output +increases. .It Xo .Sy environment Ns = Ns Ar name Ns = Ns Ar value Ns .Oo , Ns Ar name Ns = Ns Ar value Oc Ns ... .Xc -Specifies a comma separated list of environment variables. If an environment -variable has more than one value, those values should be separated with a comma, -preceded by a backslash as an escape character +Specifies a comma separated list of environment variables. +If an environment variable has more than one value, those values should be +separated with a comma, preceded by a backslash as an escape character .Pq Qq Sy \e, . For example: .Bd -literal -offset indent diff --git a/usr/src/man/man4/ctf.4 b/usr/src/man/man4/ctf.4 index 6c057beb5f..7e00f8d99a 100644 --- a/usr/src/man/man4/ctf.4 +++ b/usr/src/man/man4/ctf.4 @@ -39,7 +39,8 @@ data contained in each file has information about the layout and sizes of C types, including intrinsic types, enumerations, structures, typedefs, and unions, that are used by the corresponding .Sy ELF -object. The +object. +The .Nm data may also include information about the types of global objects and the return type and arguments of functions in the symbol table. @@ -53,8 +54,8 @@ file itself, it may also be referred to as a .Lp On illumos systems, .Nm -data is consumed by multiple programs. It can be used by the modular -debugger, +data is consumed by multiple programs. +It can be used by the modular debugger, .Xr mdb 1 , as well as by .Xr dtrace 1M . @@ -65,8 +66,8 @@ data can be obtained through .Lp The .Nm -file format is broken down into seven different sections. The first -section is the +file format is broken down into seven different sections. +The first section is the .Sy preamble and .Sy header , @@ -74,18 +75,22 @@ which describes the version of the .Nm file, links it has to other .Nm -files, and the sizes of the other sections. The next section is the +files, and the sizes of the other sections. +The next section is the .Sy label section, which provides a way of identifying similar groups of .Nm -data across multiple files. This is followed by the +data across multiple files. +This is followed by the .Sy object information section, which describes the type of global -symbols. The subsequent section is the +symbols. +The subsequent section is the .Sy function information section, which describes the return -types and arguments of functions. The next section is the +types and arguments of functions. +The next section is the .Sy type information section, which describes the format and layout of the C types themselves, and finally the last @@ -106,29 +111,33 @@ A file may contain all of the type information that it requires, or it may optionally refer to another .Nm -file which holds the remaining types. When a +file which holds the remaining types. +When a .Nm file refers to another file, it is called the .Sy child and the file it refers to is called the .Sy parent . -A given file may only refer to one parent. This process is called +A given file may only refer to one parent. +This process is called .Em uniquification because it ensures each child only has type information that is -unique to it. A common example of this is that most kernel modules in -illumos are uniquified against the kernel module +unique to it. +A common example of this is that most kernel modules in illumos are uniquified +against the kernel module .Sy genunix and the type information that comes from the .Sy IP -module. This means that a module only has types that are unique to -itself and the most common types in the kernel are not duplicated. +module. +This means that a module only has types that are unique to itself and the most +common types in the kernel are not duplicated. .Sh FILE FORMAT This documents version .Em two of the .Nm -file format. All applications and tools currently produce and operate on -this version. +file format. +All applications and tools currently produce and operate on this version. .Lp The file format can be summarized with the following image, the following sections will cover this in more detail. @@ -235,26 +244,31 @@ This .Sy preamble defines the version of the .Nm -file which defines the format of the rest of the header. While the -header may change in subsequent versions, the preamble will not change +file which defines the format of the rest of the header. +While the header may change in subsequent versions, the preamble will not change across versions, though the interpretation of its flags may change from -version to version. The +version to version. +The .Em ctp_magic member defines the magic number for the .Nm -file format. This must always be +file format. +This must always be .Li 0xcff1 . If another value is encountered, then the file should not be treated as a .Nm -file. The +file. +The .Em ctp_version member defines the version of the .Nm -file. The current version is +file. +The current version is .Li 2 . -It is possible to encounter an unsupported version. In that case, -software should not try to parse the format, as it may have changed. +It is possible to encounter an unsupported version. +In that case, software should not try to parse the format, as it may have +changed. Finally, the .Em ctp_flags member describes aspects of the file which modify its interpretation. @@ -273,9 +287,10 @@ has been compressed through the .Sy zlib library and its .Sy deflate -algorithm. If this flag is not present, then the body has not been -compressed and no special action is needed to interpret it. All offsets -into the data as described by +algorithm. +If this flag is not present, then the body has not been compressed and no +special action is needed to interpret it. +All offsets into the data as described by .Sy header , always refer to the .Sy uncompressed @@ -289,8 +304,8 @@ denotes whether whether or not this .Nm file is the child of another .Nm -file and also indicates the size of the remaining sections. The -structure for the +file and also indicates the size of the remaining sections. +The structure for the .Sy header , logically contains a copy of the .Sy preamble @@ -315,37 +330,40 @@ the next two members .Em cth_parlablel and .Em cth_parname , -are used to identify the parent. The value of both members are offsets -into the +are used to identify the parent. +The value of both members are offsets into the .Sy string -section which point to the start of a null-terminated string. For more -information on the encoding of strings, see the subsection on +section which point to the start of a null-terminated string. +For more information on the encoding of strings, see the subsection on .Sx String Identifiers . If the value of either is zero, then there is no entry for that -member. If the member +member. +If the member .Em cth_parlabel is set, then the .Em ctf_parname member must be set, otherwise it will not be possible to find the -parent. If +parent. +If .Em ctf_parname is set, it is not necessary to define .Em cth_parlabel , -as the parent may not have a label. For more information on labels -and their interpretation, see +as the parent may not have a label. +For more information on labels and their interpretation, see .Sx The Label Section . .Lp The remaining members (excepting .Em cth_strlen ) -describe the beginning of the corresponding sections. These offsets are -relative to the end of the +describe the beginning of the corresponding sections. +These offsets are relative to the end of the .Sy header . Therefore, something with an offset of 0 is at an offset of thirty-six bytes relative to the start of the .Nm -file. The difference between members -indicates the size of the section itself. Different offsets have -different alignment requirements. The start of the +file. +The difference between members indicates the size of the section itself. +Different offsets have different alignment requirements. +The start of the .Em cth_objotoff and .Em cth_funcoff @@ -353,13 +371,14 @@ must be two byte aligned, while the sections .Em cth_lbloff and .Em cth_typeoff -must be four-byte aligned. The section +must be four-byte aligned. +The section .Em cth_stroff -has no alignment requirements. To calculate the size of a given section, -excepting the +has no alignment requirements. +To calculate the size of a given section, excepting the .Sy string -section, one should subtract the offset of the section from the following one. For -example, the size of the +section, one should subtract the offset of the section from the following one. +For example, the size of the .Sy types section can be calculated by subtracting .Em cth_stroff @@ -368,8 +387,8 @@ from .Lp Finally, the member .Em cth_strlen -describes the length of the string section itself. From it, you can also -calculate the size of the entire +describes the length of the string section itself. +From it, you can also calculate the size of the entire .Nm file by adding together the size of the .Sy ctf_header_t , @@ -380,9 +399,11 @@ and the size of the string section in .Ss Type Identifiers Through the .Nm ctf -data, types are referred to by identifiers. A given +data, types are referred to by identifiers. +A given .Nm -file supports up to 32767 (0x7fff) types. The first valid type identifier is 0x1. +file supports up to 32767 (0x7fff) types. +The first valid type identifier is 0x1. When a given .Nm file is a child, indicated by a non-zero entry for the @@ -403,18 +424,20 @@ Other consumers of information may use larger or opaque identifiers. .Ss String Identifiers String identifiers are always encoded as four byte unsigned integers -which are an offset into a string table. The +which are an offset into a string table. +The .Nm format supports two different string tables which have an identifier of -zero or one. This identifier is stored in the high-order bit of the -unsigned four byte offset. Therefore, the maximum supported offset into -one of these tables is 0x7ffffffff. +zero or one. +This identifier is stored in the high-order bit of the unsigned four byte +offset. +Therefore, the maximum supported offset into one of these tables is 0x7ffffffff. .Lp Table identifier zero, always refers to the .Sy string -section in the CTF file itself. String table identifier one refers to an -external string table which is the ELF string table for the ELF symbol -table associated with the +section in the CTF file itself. +String table identifier one refers to an external string table which is the ELF +string table for the ELF symbol table associated with the .Nm container. .Ss Type Encoding @@ -434,8 +457,8 @@ The length of the variable data .Lp The 16 bits that make up the encoding are broken down such that you have five bits for the kind, one bit for indicating whether or not it is a -root type, and 10 bits for the variable length. This is laid out as -follows: +root type, and 10 bits for the variable length. +This is laid out as follows: .Bd -literal -offset indent +--------------------+ | kind | root | vlen | @@ -443,12 +466,13 @@ follows: 15 11 10 9 0 .Ed .Lp -The current version of the file format defines 14 different kinds. The -interpretation of these different kinds will be discussed in the section +The current version of the file format defines 14 different kinds. +The interpretation of these different kinds will be discussed in the section .Sx The Type Section . If a kind is encountered that is not listed below, then it is not a valid .Nm -file. The kinds are defined as follows: +file. +The kinds are defined as follows: .Bd -literal -offset indent #define CTF_K_UNKNOWN 0 #define CTF_K_INTEGER 1 @@ -467,14 +491,16 @@ file. The kinds are defined as follows: .Ed .Lp Programs directly reference many types; however, other types are referenced -indirectly because they are part of some other structure. These types that are -referenced directly and used are called +indirectly because they are part of some other structure. +These types that are referenced directly and used are called .Sy root -types. Other types may be used indirectly, for example, a program may reference -a structure directly, but not one of its members which has a type. That type is -not considered a +types. +Other types may be used indirectly, for example, a program may reference +a structure directly, but not one of its members which has a type. +That type is not considered a .Sy root -type. If a type is a +type. +If a type is a .Sy root type, then it will have bit 10 set. .Lp @@ -499,16 +525,17 @@ When consuming .Nm data, it is often useful to know whether two different .Nm -containers come from the same source base and version. For example, when -building illumos, there are many kernel modules that are built against a -single collection of source code. A label is encoded into the +containers come from the same source base and version. +For example, when building illumos, there are many kernel modules that are built +against a single collection of source code. +A label is encoded into the .Nm -files that corresponds with the particular build. This ensures that if -files on the system were to become mixed up from multiple releases, that -they are not used together by tools, particularly when a child needs to -refer to a type in the parent. Because they are linked used the type -identifiers, if the wrong parent is used then the wrong type will be -encountered. +files that corresponds with the particular build. +This ensures that if files on the system were to become mixed up from multiple +releases, that they are not used together by tools, particularly when a child +needs to refer to a type in the parent. +Because they are linked used the type identifiers, if the wrong parent is used +then the wrong type will be encountered. .Lp Each label is encoded in the file format using the following eight byte structure: @@ -530,21 +557,22 @@ section. The type identifier encoded in the member .Em ctl_typeidx refers to the last type identifier that a label refers to in the current -file. Labels only refer to types in the current file, if the +file. +Labels only refer to types in the current file, if the .Nm file is a child, then it will have the same label as its parent; however, its label will only refer to its types, not its parents. .Lp It is also possible, though rather uncommon, for a .Nm -file to have multiple labels. Labels are placed one after another, every -eight bytes. When multiple labels are present, types may only belong to -a single label. +file to have multiple labels. +Labels are placed one after another, every eight bytes. +When multiple labels are present, types may only belong to a single label. .Ss The Object Section The object section provides a mapping from ELF symbols of type .Sy STT_OBJECT -in the symbol table to a type identifier. Every entry in this section is -a +in the symbol table to a type identifier. +Every entry in this section is a .Sy uint16_t which contains a type identifier as described in the section .Sx Type Identifiers . @@ -555,9 +583,10 @@ To walk the object section, you need to have a corresponding .Sy symbol table in the ELF object that contains the .Nm -data. Not every object is included in this section. Specifically, when -walking the symbol table. An entry is skipped if it matches any of the -following conditions: +data. +Not every object is included in this section. +Specifically, when walking the symbol table. +An entry is skipped if it matches any of the following conditions: .Lp .Bl -bullet -offset indent -compact .It @@ -628,40 +657,45 @@ walk_symbols(uint16_t *objtoff, Elf_Data *symdata, Elf_Data *strdata, The function section of the .Nm file encodes the types of both the function's arguments and the function's -return type. Similar to +return type. +Similar to .Sx The Object Section , the function section encodes information for all symbols of type .Sy STT_FUNCTION , -excepting those that fit specific criteria. Unlike with objects, because -functions have a variable number of arguments, they start with a type encoding -as defined in +excepting those that fit specific criteria. +Unlike with objects, because functions have a variable number of arguments, they +start with a type encoding as defined in .Sx Type Encoding , which is the size of a .Sy uint16_t . For functions which have no type information available, they are encoded as .Li CTF_TYPE_INFO(CTF_K_UNKNOWN, 0, 0) . -Functions with arguments are encoded differently. Here, the variable length is -turned into the number of arguments in the function. If a function is a +Functions with arguments are encoded differently. +Here, the variable length is turned into the number of arguments in the +function. +If a function is a .Sy varargs -type function, then the number of arguments is increased by one. Functions with -type information are encoded as: +type function, then the number of arguments is increased by one. +Functions with type information are encoded as: .Li CTF_TYPE_INFO(CTF_K_FUNCTION, 0, nargs) . .Lp For functions that have no type information, nothing else is encoded, and the -next function is encoded. For functions with type information, the next +next function is encoded. +For functions with type information, the next .Sy uint16_t -is encoded with the type identifier of the return type of the function. It is -followed by each of the type identifiers of the arguments, if any exist, in the -order that they appear in the function. Therefore, argument 0 is the first type -identifier and so on. When a function has a final varargs argument, that is -encoded with the type identifier of zero. +is encoded with the type identifier of the return type of the function. +It is followed by each of the type identifiers of the arguments, if any exist, +in the order that they appear in the function. +Therefore, argument 0 is the first type identifier and so on. +When a function has a final varargs argument, that is encoded with the type +identifier of zero. .Lp Like .Sx The Object Section , -the function section is encoded in the order of the symbol table. It has -similar, but slightly different considerations from objects. While iterating the -symbol table, if any of the following conditions are true, then the entry is -skipped and no corresponding entry is written: +the function section is encoded in the order of the symbol table. +It has similar, but slightly different considerations from objects. +While iterating the symbol table, if any of the following conditions are true, +then the entry is skipped and no corresponding entry is written: .Lp .Bl -bullet -offset indent -compact .It @@ -683,10 +717,11 @@ ELF. .Ss The Type Section The type section is the heart of the .Nm -data. It encodes all of the information about the types themselves. The base of -the type information comes in two forms, a short form and a long form, each of -which may be followed by a variable number of arguments. The following -definitions describe the short and long forms: +data. +It encodes all of the information about the types themselves. +The base of the type information comes in two forms, a short form and a long +form, each of which may be followed by a variable number of arguments. +The following definitions describe the short and long forms: .Bd -literal #define CTF_MAX_SIZE 0xfffe /* max size of a type in bytes */ #define CTF_LSIZE_SENT 0xffff /* sentinel for ctt_size */ @@ -720,14 +755,17 @@ Type sizes are stored in .Sy bytes . The basic small form uses a .Sy ushort_t -to store the number of bytes. If the number of bytes in a structure would exceed -0xfffe, then the alternate form, the +to store the number of bytes. +If the number of bytes in a structure would exceed 0xfffe, then the alternate +form, the .Sy ctf_type_t , -is used instead. To indicate that the larger form is being used, the member +is used instead. +To indicate that the larger form is being used, the member .Em ctt_size is set to value of .Sy CTF_LSIZE_SENT -(0xffff). In general, when going through the type section, consumers use the +(0xffff). +In general, when going through the type section, consumers use the .Sy ctf_type_t structure, but pay attention to the value of the member .Em ctt_size @@ -739,17 +777,21 @@ Not all kinds of types use .Sy ctt_size . Those which do not, will always use the .Sy ctf_stype_t -structure. The individual sections for each kind have more information. +structure. +The individual sections for each kind have more information. .Lp -Types are written out in order. Therefore the first entry encountered has a type -id of 0x1, or 0x8000 if a child. The member +Types are written out in order. +Therefore the first entry encountered has a type id of 0x1, or 0x8000 if a +child. +The member .Em ctt_name is encoded as described in the section .Sx String Identifiers . -The string that it points to is the name of the type. If the identifier points -to an empty string (one that consists solely of a null terminator) then the type -does not have a name, this is common with anonymous structures and unions that -only have a typedef to name them, as well as, pointers and qualifiers. +The string that it points to is the name of the type. +If the identifier points to an empty string (one that consists solely of a null +terminator) then the type does not have a name, this is common with anonymous +structures and unions that only have a typedef to name them, as well as, +pointers and qualifiers. .Lp The next member, the .Em ctt_info , @@ -757,18 +799,21 @@ is encoded as described in the section .Sx Type Encoding . The types kind tells us how to interpret the remaining data in the .Sy ctf_type_t -and any variable length data that may exist. The rest of this section will be -broken down into the interpretation of the various kinds. +and any variable length data that may exist. +The rest of this section will be broken down into the interpretation of the +various kinds. .Ss Encoding of Integers Integers, which are of type .Sy CTF_K_INTEGER , -have no variable length arguments. Instead, they are followed by a four byte +have no variable length arguments. +Instead, they are followed by a four byte .Sy uint_t -which describes their encoding. All integers must be encoded with a variable -length of zero. The +which describes their encoding. +All integers must be encoded with a variable length of zero. +The .Em ctt_size -member describes the length of the integer in bytes. In general, integer sizes -will be rounded up to the closest power of two. +member describes the length of the integer in bytes. +In general, integer sizes will be rounded up to the closest power of two. .Lp The integer encoding contains three different pieces of information: .Bl -bullet -offset indent -compact @@ -804,33 +849,37 @@ The following flags are defined for the encoding at this time: .Lp By default, an integer is considered to be unsigned, unless it has the .Sy CTF_INT_SIGNED -flag set. If the flag +flag set. +If the flag .Sy CTF_INT_CHAR is set, that indicates that the integer is of a type that stores character data, for example the intrinsic C type .Sy char would have the .Sy CTF_INT_CHAR -flag set. If the flag +flag set. +If the flag .Sy CTF_INT_BOOL -is set, that indicates that the integer represents a boolean type. For example, -the intrinsic C type +is set, that indicates that the integer represents a boolean type. +For example, the intrinsic C type .Sy _Bool would have the .Sy CTF_INT_BOOL -flag set. Finally, the flag +flag set. +Finally, the flag .Sy CTF_INT_VARARGS indicates that the integer is used as part of a variable number of arguments. This encoding is rather uncommon. .Ss Encoding of Floats Floats, which are of type .Sy CTF_K_FLOAT , -are similar to their integer counterparts. They have no variable length -arguments and are followed by a four byte encoding which describes the kind of -float that exists. The +are similar to their integer counterparts. +They have no variable length arguments and are followed by a four byte encoding +which describes the kind of float that exists. +The .Em ctt_size -member is the size, in bytes, of the float. The float encoding has three -different pieces of information inside of it: +member is the size, in bytes, of the float. +The float encoding has three different pieces of information inside of it: .Lp .Bl -bullet -offset indent -compact .It @@ -856,10 +905,11 @@ This encoding can be expressed through the following macros: .Ed .Lp Where as the encoding for integers was a series of flags, the encoding for -floats maps to a specific kind of float. It is not a flag-based value. The kinds of floats -correspond to both their size, and the encoding. This covers all of the basic C -intrinsic floating point types. The following are the different kinds of floats -represented in the encoding: +floats maps to a specific kind of float. +It is not a flag-based value. +The kinds of floats correspond to both their size, and the encoding. +This covers all of the basic C intrinsic floating point types. +The following are the different kinds of floats represented in the encoding: .Bd -literal -offset indent #define CTF_FP_SINGLE 1 /* IEEE 32-bit float encoding */ #define CTF_FP_DOUBLE 2 /* IEEE 64-bit float encoding */ @@ -877,12 +927,14 @@ represented in the encoding: .Ss Encoding of Arrays Arrays, which are of type .Sy CTF_K_ARRAY , -have no variable length arguments. They are followed by a structure which -describes the number of elements in the array, the type identifier of the -elements in the array, and the type identifier of the index of the array. With -arrays, the +have no variable length arguments. +They are followed by a structure which describes the number of elements in the +array, the type identifier of the elements in the array, and the type identifier +of the index of the array. +With arrays, the .Em ctt_size -member is set to zero. The structure that follows an array is defined as: +member is set to zero. +The structure that follows an array is defined as: .Bd -literal typedef struct ctf_array { ushort_t cta_contents; /* reference to type of array contents */ @@ -901,14 +953,15 @@ are type identifiers which are encoded as per the section .Sx Type Identifiers . The member .Em cta_nelems -is a simple four byte unsigned count of the number of elements. This count may -be zero when encountering C99's flexible array members. +is a simple four byte unsigned count of the number of elements. +This count may be zero when encountering C99's flexible array members. .Ss Encoding of Functions Function types, which are of type .Sy CTF_K_FUNCTION , -use the variable length list to be the number of arguments in the function. When -the function has a final member which is a varargs, then the argument count is -incremented by one to account for the variable argument. Here, the +use the variable length list to be the number of arguments in the function. +When the function has a final member which is a varargs, then the argument count +is incremented by one to account for the variable argument. +Here, the .Em ctt_type member is encoded with the type identifier of the return type of the function. Note that the @@ -916,31 +969,36 @@ Note that the member is not used here. .Lp The variable argument list contains the type identifiers for the arguments of -the function, if any. Each one is represented by a +the function, if any. +Each one is represented by a .Sy uint16_t and encoded according to the .Sx Type Identifiers -section. If the function's last argument is of type varargs, then it is also -written out, but the type identifier is zero. This is included in the count of -the function's arguments. +section. +If the function's last argument is of type varargs, then it is also written out, +but the type identifier is zero. +This is included in the count of the function's arguments. .Ss Encoding of Structures and Unions Structures and Unions, which are encoded with .Sy CTF_K_STRUCT and .Sy CTF_K_UNION -respectively, are very similar constructs in C. The main difference -between them is the fact that every member of a structure follows one another, -where as in a union, all members share the same memory. They are also very -similar in terms of their encoding in +respectively, are very similar constructs in C. +The main difference between them is the fact that every member of a structure +follows one another, where as in a union, all members share the same memory. +They are also very similar in terms of their encoding in .Nm . The variable length argument for structures and unions represents the number of -members that they have. The value of the member +members that they have. +The value of the member .Em ctt_size -is the size of the structure and union. There are two different structures which -are used to encode members in the variable list. When the size of a structure or -union is greater than or equal to the large member threshold, 8192, then a -different structure is used to encode the member, all members are encoded using -the same structure. The structure for members is as follows: +is the size of the structure and union. +There are two different structures which are used to encode members in the +variable list. +When the size of a structure or union is greater than or equal to the large +member threshold, 8192, then a different structure is used to encode the member, +all members are encoded using the same structure. +The structure for members is as follows: .Bd -literal typedef struct ctf_member { uint_t ctm_name; /* reference to name in string table */ @@ -961,44 +1019,52 @@ Both the .Em ctm_name and .Em ctlm_name -refer to the name of the member. The name is encoded as an offset into the -string table as described by the section +refer to the name of the member. +The name is encoded as an offset into the string table as described by the +section .Sx String Identifiers . The members .Sy ctm_type and .Sy ctlm_type -both refer to the type of the member. They are encoded as per the section +both refer to the type of the member. +They are encoded as per the section .Sx Type Identifiers . .Lp The last piece of information that is present is the offset which describes the -offset in memory that the member begins at. For unions, this value will always -be zero because the start of unions in memory is always zero. For structures, -this is the offset in +offset in memory that the member begins at. +For unions, this value will always be zero because the start of unions in memory +is always zero. +For structures, this is the offset in .Sy bits -that the member begins at. Note that a compiler may lay out a type with padding. +that the member begins at. +Note that a compiler may lay out a type with padding. This means that the difference in offset between two consecutive members may be -larger than the size of the member. When the size of the overall structure is -strictly less than 8192 bytes, the normal structure, +larger than the size of the member. +When the size of the overall structure is strictly less than 8192 bytes, the +normal structure, .Sy ctf_member_t , is used and the offset in bits is stored in the member .Em ctm_offset . However, when the size of the structure is greater than or equal to 8192 bytes, -then the number of bits is split into two 32-bit quantities. One member, +then the number of bits is split into two 32-bit quantities. +One member, .Em ctlm_offsethi , represents the upper 32 bits of the offset, while the other member, .Em ctlm_offsetlo , -represents the lower 32 bits of the offset. These can be joined together to get -a 64-bit sized offset in bits by shifting the member +represents the lower 32 bits of the offset. +These can be joined together to get a 64-bit sized offset in bits by shifting +the member .Em ctlm_offsethi to the left by thirty two and then doing a binary or of .Em ctlm_offsetlo . .Ss Encoding of Enumerations Enumerations, noted by the type .Sy CTF_K_ENUM , -are similar to structures. Enumerations use the variable list to note the number -of values that the enumeration contains, which we'll term enumerators. In C, an -enumeration is always equivalent to the intrinsic type +are similar to structures. +Enumerations use the variable list to note the number of values that the +enumeration contains, which we'll term enumerators. +In C, an enumeration is always equivalent to the intrinsic type .Sy int , thus the value of the member .Em ctt_size @@ -1032,25 +1098,27 @@ Forward references, types of kind .Sy CTF_K_FORWARD , in a .Nm -file refer to types which may not have a definition at all, only a name. If -the +file refer to types which may not have a definition at all, only a name. +If the .Nm file is a child, then it may be that the forward is resolved to an actual type in the parent, otherwise the definition may be in another .Nm -container or may not be known at all. The only member of the +container or may not be known at all. +The only member of the .Sy ctf_type_t that matters for a forward declaration is the .Em ctt_name which points to the name of the forward reference in the string table as -described earlier. There is no other information recorded for forward -references. +described earlier. +There is no other information recorded for forward references. .Ss Encoding of Pointers, Typedefs, Volatile, Const, and Restrict Pointers, typedefs, volatile, const, and restrict are all similar in .Nm . -They all refer to another type. In the case of typedefs, they provide an -alternate name, while volatile, const, and restrict change how the type is -interpreted in the C programming language. This covers the +They all refer to another type. +In the case of typedefs, they provide an alternate name, while volatile, const, +and restrict change how the type is interpreted in the C programming language. +This covers the .Nm kinds .Sy CTF_K_POINTER , @@ -1066,43 +1134,49 @@ to refer to the base type that they modify. .Ss Encoding of Unknown Types Types with the kind .Sy CTF_K_UNKNOWN -are used to indicate gaps in the type identifier space. These entries consume an -identifier, but do not define anything. Nothing should refer to these gap -identifiers. +are used to indicate gaps in the type identifier space. +These entries consume an identifier, but do not define anything. +Nothing should refer to these gap identifiers. .Ss Dependencies Between Types -C types can be imagined as a directed, cyclic, graph. Structures and unions may -refer to each other in a way that creates a cyclic dependency. In cases such as -these, the entire type section must be read in and processed. Consumers must -not assume that every type can be laid out in dependency order; they -cannot. +C types can be imagined as a directed, cyclic, graph. +Structures and unions may refer to each other in a way that creates a cyclic +dependency. +In cases such as these, the entire type section must be read in and processed. +Consumers must not assume that every type can be laid out in dependency order; +they cannot. .Ss The String Section The last section of the .Nm file is the .Sy string -section. This section encodes all of the strings that appear throughout -the other sections. It is laid out as a series of characters followed by -a null terminator. Generally, all names are written out in ASCII, as -most C compilers do not allow and characters to appear in identifiers -outside of a subset of ASCII. However, any extended characters sets -should be written out as a series of UTF-8 bytes. +section. +This section encodes all of the strings that appear throughout the other +sections. +It is laid out as a series of characters followed by a null terminator. +Generally, all names are written out in ASCII, as most C compilers do not allow +and characters to appear in identifiers outside of a subset of ASCII. +However, any extended characters sets should be written out as a series of UTF-8 +bytes. .Lp The first entry in the section, at offset zero, is a single null -terminator to reference the empty string. Following that, each C string -should be written out, including the null terminator. Offsets that refer -to something in this section should refer to the first byte which begins -a string. Beyond the first byte in the section being the null -terminator, the order of strings is unimportant. +terminator to reference the empty string. +Following that, each C string should be written out, including the null +terminator. +Offsets that refer to something in this section should refer to the first byte +which begins a string. +Beyond the first byte in the section being the null terminator, the order of +strings is unimportant. .Sh Data Encoding and ELF Considerations .Nm data is generally included in ELF objects which specify information to -identify the architecture and endianness of the file. A +identify the architecture and endianness of the file. +A .Nm -container inside such an object must match the endianness of the ELF -object. Aside from the question of the endian encoding of data, there -should be no other differences between architectures. While many of the -types in this document refer to non-fixed size C integral types, they -are equivalent in the models +container inside such an object must match the endianness of the ELF object. +Aside from the question of the endian encoding of data, there should be no other +differences between architectures. +While many of the types in this document refer to non-fixed size C integral +types, they are equivalent in the models .Sy ILP32 and .Sy LP64 . @@ -1118,15 +1192,16 @@ When placing a container inside of an ELF object, there are certain conventions that are expected for the purposes of tooling being able to find the .Nm -data. In particular, a given ELF object should only contain a single +data. +In particular, a given ELF object should only contain a single .Nm -section. Multiple containers should be merged together into a single -one. +section. +Multiple containers should be merged together into a single one. .Lp The .Nm -file should be included in its own ELF section. The section's name -must be +file should be included in its own ELF section. +The section's name must be .Ql .SUNW_ctf . The type of the section must be .Sy SHT_PROGBITS . diff --git a/usr/src/man/man4/loader.conf.4 b/usr/src/man/man4/loader.conf.4 index dc4a44b5b2..6b1286025f 100644 --- a/usr/src/man/man4/loader.conf.4 +++ b/usr/src/man/man4/loader.conf.4 @@ -41,8 +41,8 @@ described in .Xr loader 5 . .Pp Loader implements set of builtin commands and functions and script -interpreter as standalone binary program. When starting, the loader will -read the file +interpreter as standalone binary program. +When starting, the loader will read the file .Pa /boot/loader.rc as initialization and startup script, to include other support files and to read the configuration, describing current boot environment. @@ -62,7 +62,8 @@ to be automatically processed: The default .Pa /boot/loader.rc is provided by the operating system and may be replaced on operating -system update. The local updates are advised to be added into the +system update. +The local updates are advised to be added into the .Pa /boot/loader.rc.local .Pp The configuration variables are read from the following files: @@ -74,15 +75,18 @@ command. .It Ar /boot/defaults/loader.conf Loader defaults provided by the operating system. .It Ar /boot/loader.conf -System specific loader configuration. May be provided by the operating system. +System specific loader configuration. +May be provided by the operating system. .It Ar /boot/loader.conf.local User editable loader configuration. .It Ar /boot/conf.d/* -User editable loader configuration snippets. The files are proccessed in -lexicographical order. The configuration snippets mechanism is not -available in case of TFTP boot as TFTP does not provide the directory list. +User editable loader configuration snippets. +The files are proccessed in lexicographical order. +The configuration snippets mechanism is not available in case of TFTP boot as +TFTP does not provide the directory list. .It Ar /boot/transient.conf -Configuration file for transient boot. This file is created by the +Configuration file for transient boot. +This file is created by the .Xr reboot 1M command and is automatically removed when system is reaching the multi-user run level. diff --git a/usr/src/man/man4/nfs.4 b/usr/src/man/man4/nfs.4 index 959bb472c7..46c82e5e21 100644 --- a/usr/src/man/man4/nfs.4 +++ b/usr/src/man/man4/nfs.4 @@ -35,7 +35,8 @@ and daemons and .Xr mount_nfs 1M command is controlled by property values that are stored in the Service -Management Facility, smf(5). The +Management Facility, smf(5). +The .Xr sharectl 1M command should be used to query or change values for these properties. .Pp @@ -58,8 +59,9 @@ The following list describes the properties: .Sy client_versmax Ns = Ns Ar num .Xc The NFS client only uses NFS versions in the range specified by these -properties. Valid values of versions are: 2, 3, and 4. Default minimum version -is +properties. +Valid values of versions are: 2, 3, and 4. +Default minimum version is .Li 2 , while default maximum is .Li 4 . @@ -74,29 +76,34 @@ option to .Sy server_versmax Ns = Ns Ar num .Xc The NFS server only uses NFS versions in the range specified by these -properties. Valid values of versions are: 2, 3, and 4. Default minimum version -is +properties. +Valid values of versions are: 2, 3, and 4. +Default minimum version is .Li 2 , while the default maximum version is .Li 4 . .It Sy server_delegation Ns = Ns Sy on Ns | Ns Sy off -By default the NFS server provides -delegations to clients. The user can turn off delegations for all exported -filesystems by setting this variable to +By default the NFS server provides delegations to clients. +The user can turn off delegations for all exported filesystems by setting this +variable to .Li off . This variable only applies to NFS Version 4. .It Sy nfsmapid_domain Ns = Ns Op Ar string By default, the .Nm nfsmapid -uses the DNS domain of the system. This setting overrides the default. This -domain is used for identifying user and group attribute strings in the NFS -Version 4 protocol. Clients and servers must match with this domain for -operation to proceed normally. This variable only applies to NFS Version 4. See +uses the DNS domain of the system. +This setting overrides the default. +This domain is used for identifying user and group attribute strings in the NFS +Version 4 protocol. +Clients and servers must match with this domain for operation to proceed +normally. +This variable only applies to NFS Version 4. +See .Sx Setting nfsmapid_domain below for further details. .It Sy max_connections Ns = Ns Ar num -Sets the maximum number of concurrent, connection-oriented connections. The -default is +Sets the maximum number of concurrent, connection-oriented connections. +The default is .Li -1 .Pq unlimited . Equivalent to the @@ -107,14 +114,16 @@ option in Set connection queue length for the NFS over a connection-oriented transport. The default value is .Li 32 , -meaning 32 entries in the queue. Equivalent to the +meaning 32 entries in the queue. +Equivalent to the .Fl l option in .Nm nfsd . .It Sy protocol Ns = Ns Op Sy all Ns | Ns Ar protocol Start .Nm nfsd -over the specified protocol only. Equivalent to the +over the specified protocol only. +Equivalent to the .Fl p option in .Nm nfsd . @@ -123,10 +132,11 @@ is equivalent to .Fl a on the .Nm nfsd -command line. Mutually exlusive of +command line. +Mutually exlusive of .Sy device . -For the UDP protocol, only version 2 and version 3 service is established. NFS -Version 4 is not supported for the UDP protocol. +For the UDP protocol, only version 2 and version 3 service is established. +NFS Version 4 is not supported for the UDP protocol. .It Sy device Ns = Ns Op Ar devname Start NFS daemon for the transport specified by the given device only. Equivalent to the @@ -136,35 +146,41 @@ option in Mutually exclusive of .Sy protocol . .It Sy servers Ns = Ns Ar num -Maximum number of concurrent NFS requests. Equivalent to last numeric argument -on the +Maximum number of concurrent NFS requests. +Equivalent to last numeric argument on the .Nm nfsd -command line. The default is +command line. +The default is .Li 1024 . .It Sy lockd_listen_backlog Ns = Ns Ar num Set connection queue length for .Nm lockd -over a connection-oriented transport. The default and minimum value is +over a connection-oriented transport. +The default and minimum value is .Li 32 . .It Sy lockd_servers Ns = Ns Ar num Maximum number of concurrent .Nm lockd -requests. The default is 256. +requests. +The default is 256. .It Sy lockd_retransmit_timeout Ns = Ns Ar num Retransmit timeout, in seconds, before .Nm lockd -retries. The default is +retries. +The default is .Li 5 . .It Sy grace_period Ns = Ns Ar num Grace period, in seconds, that all clients .Pq both NLM and NFSv4 -have to reclaim locks after a server reboot. This parameter also controls the -NFSv4 lease interval. The default is +have to reclaim locks after a server reboot. +This parameter also controls the NFSv4 lease interval. +The default is .Li 90 . .It Sy mountd_listen_backlog Ns = Ns Ar num Set the connection queue length for .Nm mountd -over a connection-oriented transport. The default value is +over a connection-oriented transport. +The default value is .Li 64 . .It Sy mountd_max_threads Ns = Ns Ar num Maximum number of threads for @@ -178,8 +194,8 @@ As described above, the setting for overrides the domain used by .Xr nfsmapid 1M for building and comparing outbound and inbound attribute strings, respectively. -This setting overrides any other mechanism for setting the NFSv4 domain. In the -absence of a +This setting overrides any other mechanism for setting the NFSv4 domain. +In the absence of a .Sy nfsmapid_domain setting, the .Xr nfsmapid 1M @@ -216,7 +232,8 @@ falls back on using the configured domain name .Po see .Xr domainname 1M .Pc , -which is returned with the leading domain suffix removed. For example, for +which is returned with the leading domain suffix removed. +For example, for .Li widgets.sales.acme.com , .Li sales.acme.com is returned. @@ -236,30 +253,32 @@ contains a fully qualified domain name .Pp If a domainname is still not obtained following all of the preceding steps, .Nm nfsmapid -will have no domain configured. This results in the following behavior: +will have no domain configured. +This results in the following behavior: .Bl -bullet .It Outbound .Qq owner and .Qq owner_group -attribute strings are encoded as literal id's. For example, the UID 12345 is -encoded as +attribute strings are encoded as literal id's. +For example, the UID 12345 is encoded as .Li 12345 . .It .Nm nfsmapid ignores the .Qq domain portion of the inbound attribute string and performs name service lookups only -for the user or group. If the user/group exists in the local system name service -databases, then the proper uid/gid will be mapped even when no domain has been -configured. +for the user or group. +If the user/group exists in the local system name service databases, then the +proper uid/gid will be mapped even when no domain has been configured. .Pp This behavior implies that the same administrative user/group domain exists between NFSv4 client and server (that is, the same uid/gid's for users/groups -on both client and server). In the case of overlapping id spaces, the inbound -attribute string could potentially be mapped to the wrong id. However, this is -not functionally different from mapping the inbound string to +on both client and server). +In the case of overlapping id spaces, the inbound attribute string could +potentially be mapped to the wrong id. +However, this is not functionally different from mapping the inbound string to .Sy nobody , yet provides greater flexibility. .El diff --git a/usr/src/man/man5/beastie.4th.5 b/usr/src/man/man5/beastie.4th.5 index 8f2f40bd74..c9ac2e6dd3 100644 --- a/usr/src/man/man5/beastie.4th.5 +++ b/usr/src/man/man5/beastie.4th.5 @@ -34,8 +34,8 @@ The file that goes by the name of is a set of commands designed to draw the ASCII art FreeBSD mascot .Nd known simply as .Ic beastie -.Nd to the right of the boot loader menu. In illumos based systems, the -distribution specific logo is used. +.Nd to the right of the boot loader menu. +In illumos based systems, the distribution specific logo is used. The commands of .Nm by themselves are not enough for most uses. @@ -96,9 +96,11 @@ The environment variables that effect its behavior are: .It Va loader_logo Selects the desired logo in the beastie boot menu. .It Va loader_logo_x -Sets the desired column position of the logo. Default is 46. +Sets the desired column position of the logo. +Default is 46. .It Va loader_logo_y -Sets the desired row position of the logo. Default is 4. +Sets the desired row position of the logo. +Default is 4. .It Va beastie_disable If set to .Dq YES , @@ -106,9 +108,10 @@ the beastie boot menu will be skipped. The beastie boot menu is always skipped if running non-x86 hardware. .It Va loader_delay If set to a number higher than zero, introduces a delay before starting the -beastie boot menu. During the delay the user can press either Ctrl-C to skip -the menu or ENTER to proceed to the menu. The default is to not delay when -loading the menu. +beastie boot menu. +During the delay the user can press either Ctrl-C to skip the menu or ENTER to +proceed to the menu. +The default is to not delay when loading the menu. .El .Sh FILES .Bl -tag -width /boot/forth/loader.4th -compact diff --git a/usr/src/man/man5/brand.4th.5 b/usr/src/man/man5/brand.4th.5 index ce74b382a6..8bb9b7b935 100644 --- a/usr/src/man/man5/brand.4th.5 +++ b/usr/src/man/man5/brand.4th.5 @@ -79,14 +79,17 @@ The default values are 2 (x) and 1 (y). The environment variables that effect its behavior are: .Bl -tag -width bootfile -offset indent .It Va loader_brand -Selects the desired brand in the beastie boot menu. Possible values are: +Selects the desired brand in the beastie boot menu. +Possible values are: .Dq Li illumos (default) or .Dq Li none . .It Va loader_brand_x -Sets the desired column position of the brand. Default is 2. +Sets the desired column position of the brand. +Default is 2. .It Va loader_brand_y -Sets the desired row position of the brand. Default is 1. +Sets the desired row position of the brand. +Default is 1. .El .Sh FILES .Bl -tag -width /boot/forth/loader.4th -compact diff --git a/usr/src/man/man5/byteorder.5 b/usr/src/man/man5/byteorder.5 index 4172008e97..8e091f5f3d 100644 --- a/usr/src/man/man5/byteorder.5 +++ b/usr/src/man/man5/byteorder.5 @@ -20,11 +20,12 @@ .Nd byte order and endianness .Sh DESCRIPTION Integer values which occupy more than 1 byte in memory can be laid out -in different ways on different platforms. In particular, there is a -major split between those which place the least significant byte of an -integer at the lowest address, and those which place the most -significant byte there instead. As this difference relates to which -end of the integer is found in memory first, the term +in different ways on different platforms. +In particular, there is a major split between those which place the least +significant byte of an integer at the lowest address, and those which place the +most significant byte there instead. +As this difference relates to which end of the integer is found in memory first, +the term .Em endian is used to refer to a particular byte order. .Pp @@ -33,24 +34,25 @@ A platform is referred to as using a byte order when it places the most significant byte at the lowest address, and .Em little-endian -when it places the least significant byte first. Some platforms may also -switch between big- and little-endian mode and run code compiled for -either. +when it places the least significant byte first. +Some platforms may also switch between big- and little-endian mode and run code +compiled for either. .Pp Historically, there have also been some systems that utilized .Em middle-endian -byte orders for integers larger than 2 bytes. Such orderings are not in -common use today. +byte orders for integers larger than 2 bytes. +Such orderings are not in common use today. .Pp Endianness is also of particular importance when dealing with values -that are being read into memory from an external source. For example, -network protocols such as IP conventionally define the fields in a -packet as being always stored in big-endian byte order. This means that -a little-endian machine will have to perform transformations on these -fields in order to process them. +that are being read into memory from an external source. +For example, network protocols such as IP conventionally define the fields in a +packet as being always stored in big-endian byte order. +This means that a little-endian machine will have to perform transformations on +these fields in order to process them. .Ss Examples To illustrate endianness in memory, let us consider the decimal integer -2864434397. This number fits in 32 bits of storage (4 bytes). +2864434397. +This number fits in 32 bits of storage (4 bytes). .Pp On a big-endian system, this integer would be written into memory as the bytes 0xAA, 0xBB, 0xCC, 0xDD, in order from lowest memory address to @@ -89,8 +91,8 @@ bytes). On a big-endian system, this would be written into memory as 0x12, then 0x34. .Pp -On a little-endian system, it would be written as 0x34, then 0x12. Note -that this is not at all the same as seeing 0x43 then 0x21 in memory -- +On a little-endian system, it would be written as 0x34, then 0x12. +Note that this is not at all the same as seeing 0x43 then 0x21 in memory -- only the bytes are re-ordered, not any bits (or nybbles) within them. .Pp As before, storing this at address 0x100: @@ -135,15 +137,16 @@ discussing which is also known as .Em middle-endian . While the PDP-11 was a 16-bit little-endian system, it laid out 32-bit -values in a different way from current little-endian systems. First, it -would divide a 32-bit number into two 16-bit numbers. Each 16-bit number -would be stored in little-endian; however, the two 16-bit words would be -stored with the larger 16-bit word appearing first in memory, followed -by the latter. +values in a different way from current little-endian systems. +First, it would divide a 32-bit number into two 16-bit numbers. +Each 16-bit number would be stored in little-endian; however, the two 16-bit +words would be stored with the larger 16-bit word appearing first in memory, +followed by the latter. .Pp The following image illustrates PDP-endian and compares it against -little-endian values. Here, we'll start with the value 0xAABBCCDD and -show how the four bytes for it will be laid out, starting at 0x100. +little-endian values. +Here, we'll start with the value 0xAABBCCDD and show how the four bytes for it +will be laid out, starting at 0x100. .Bd -literal PDP-Endian @@ -162,16 +165,17 @@ show how the four bytes for it will be laid out, starting at 0x100. .Ed .Ss Network Byte Order The term 'network byte order' refers to big-endian ordering, and -originates from the IEEE. Early disagreements over which byte ordering -to use for network traffic prompted RFC1700 to define that all -IETF-specified network protocols use big-endian ordering unless noted -explicitly otherwise. The Internet protocol family (IP, and thus TCP and -UDP etc) particularly adhere to this convention. +originates from the IEEE. +Early disagreements over which byte ordering to use for network traffic prompted +RFC1700 to define that all IETF-specified network protocols use big-endian +ordering unless noted explicitly otherwise. +The Internet protocol family (IP, and thus TCP and UDP etc) particularly adhere +to this convention. .Ss Determining the System's Byte Order -The operating system supports both big-endian and little-endian CPUs. To -make it easier for programs to determine the endianness of the -platform they are being compiled for, functions and macro constants are -provided in the system header files. +The operating system supports both big-endian and little-endian CPUs. +To make it easier for programs to determine the endianness of the platform they +are being compiled for, functions and macro constants are provided in the system +header files. .Pp The endianness of the system can be obtained by including the header .In sys/types.h @@ -186,16 +190,18 @@ for more information. Additionally, the header .In endian.h defines an alternative means for determining the endianness of the -current system. See +current system. +See .Xr endian.h 3HEAD for more information. .Pp -illumos runs on both big- and little-endian systems. When writing -software for which the endianness is important, one must always check -the byte order and convert it appropriately. +illumos runs on both big- and little-endian systems. +When writing software for which the endianness is important, one must always +check the byte order and convert it appropriately. .Ss Converting Between Byte Orders The system provides two different sets of functions to convert values -between big-endian and little-endian. They are defined in +between big-endian and little-endian. +They are defined in .Xr byteorder 3C and .Xr endian 3C . @@ -215,23 +221,24 @@ For example, to convert a 32-bit value, a long, from network byte order to the host's, one would use the function .Xr ntohl 3SOCKET . .Pp -These functions have been standardized by POSIX. However, the 64-bit variants, +These functions have been standardized by POSIX. +However, the 64-bit variants, .Xr ntohll 3SOCKET and .Xr htonll 3SOCKET -are not standardized and may not be found on other systems. For more -information on these functions, see +are not standardized and may not be found on other systems. +For more information on these functions, see .Xr byteorder 3SOCKET . .Pp The second family of functions, .Xr endian 3C , provide a means to convert between the host's byte order -and big-endian and little-endian specifically. While these functions are -similar to those in +and big-endian and little-endian specifically. +While these functions are similar to those in .Xr byteorder 3C , -they more explicitly cover different data conversions. Like them, these -functions operate on either 16-bit, 32-bit, or 64-bit values. When -converting from big-endian, to the host's endianness, the functions +they more explicitly cover different data conversions. +Like them, these functions operate on either 16-bit, 32-bit, or 64-bit values. +When converting from big-endian, to the host's endianness, the functions begin with .Sy betoh . If instead, one is converting data from the host's native endianness to @@ -244,16 +251,15 @@ and convert little-endian data to the host's endianness and from the host's to little-endian respectively. .Pp -These functions -are not standardized and the header they appear in varies between the -BSDs and GNU/Linux. Applications that wish to be portable, should -instead use the +These functions are not standardized and the header they appear in varies +between the BSDs and GNU/Linux. +Applications that wish to be portable, shoulda instead use the .Xr byteorder 3C functions. .Pp All of these functions in both families simply return their input when -the host's native byte order is the same as the desired order. For -example, when calling +the host's native byte order is the same as the desired order. +For example, when calling .Xr htonl 3SOCKET on a big-endian system the original data is returned with no conversion or modification. diff --git a/usr/src/man/man5/eventfd.5 b/usr/src/man/man5/eventfd.5 index bcf9f58347..1466201967 100644 --- a/usr/src/man/man5/eventfd.5 +++ b/usr/src/man/man5/eventfd.5 @@ -22,10 +22,10 @@ .Sh DESCRIPTION .Nm is a Linux-borne facility for sending and receiving user -events via a file descriptor. While the facility itself is somewhat dubious -(it can be mimicked in an entirely portable way with a pipe), it is -small and straightforward and this implementation is entirely compatible -with its Linux antecedent; see +events via a file descriptor. +While the facility itself is somewhat dubious (it can be mimicked in an entirely +portable way with a pipe), it is small and straightforward and this +implementation is entirely compatible with its Linux antecedent; see .Xr eventfd 3C for details. .Sh SEE ALSO diff --git a/usr/src/man/man5/ieee802.3.5 b/usr/src/man/man5/ieee802.3.5 index b77c378db2..a32230c1f0 100644 --- a/usr/src/man/man5/ieee802.3.5 +++ b/usr/src/man/man5/ieee802.3.5 @@ -29,13 +29,14 @@ .Nd IEEE 802.3 Ethernet parameters and statistics .Sh DESCRIPTION The IEEE 802.3 standard specifies the details for Ethernet -networking. This page describes the various statistics and tunables -that device drivers supporting Ethernet commonly offer. +networking. +This page describes the various statistics and tunables that device drivers +supporting Ethernet commonly offer. . Note that not every device or driver supports every one of these values, and many devices offer additional statistics and tunables that -are specific to that hardware. See the device driver's documentation -for those specific details. +are specific to that hardware. +See the device driver's documentation for those specific details. . .Lp Values that are statistics are visible @@ -43,11 +44,12 @@ Values that are statistics are visible whereas properties are visible using the .Xr dladm 1M .Sy show-linkprop -subcommand. Tunables are properties that can be changed using the +subcommand. +Tunables are properties that can be changed using the .Xr dladm 1M .Sy set-linkprop -subcommand. A more useful summary of current operational -state can be seen with the +subcommand. +A more useful summary of current operational state can be seen with the .Xr dladm 1M .Sy show-ether subcommand. @@ -59,11 +61,13 @@ Note that some statistics are available in both 32- and 64-bit counters, in which case the name of the 64 bit statistic will be the same as the 32-bit, but with .Dq Sy 64 -appended. For example, +appended. +For example, .Sy ipackets64 is the 64-bit version of the .Sy ipackets -statistic. These are indicated with the special suffix +statistic. +These are indicated with the special suffix .Op Sy 64 in the table below. . @@ -273,7 +277,8 @@ Transceiver address. .It Sy xcvr_id Transceiver vendor and device ID. .It Sy xcvr_inuse -Identifies the type of transceiver in use. Values are as follows: +Identifies the type of transceiver in use. +Values are as follows: .Bl -column "0" .It 0 Ta Unknown or undefined. .It 1 Ta None. @@ -288,8 +293,9 @@ Identifies the type of transceiver in use. Values are as follows: .Ss Properties The following parameters are accessible with .Xr dladm 1M . -Some of these are normally read-only. Other properties that are not -specific to IEEE 802.3 / Ethernet links are also available via +Some of these are normally read-only. +Other properties that are not specific to IEEE 802.3 / Ethernet links are also +available via .Xr dladm 1M , and are documented in its man page rather than here. . @@ -301,7 +307,8 @@ Link duplex, either "full" or "half". .It Sy state Link state, either "up" or "down". .It Sy mtu -Maximum link frame size in bytes. See +Maximum link frame size in bytes. +See .Sx Jumbo Frames . .It Sy flowctrl Flow control setting, one of \(dqno\(dq, \(dqtx\(dq, \(dqrx\(dq, or \(dqbi\(dq. @@ -343,9 +350,10 @@ Advertising 10 Mbps half-duplex support. Enable 10 Mbps half-duplex. .El .Ss Auto-negotiation -With modern devices, auto-negotiation is normally handled automatically. With -10 Gbps and 1000 Gbps, it is mandatory. (10GBASE-T also requires full-duplex -operation.) It is also +With modern devices, auto-negotiation is normally handled automatically. +With 10 Gbps and 1000 Gbps, it is mandatory (10GBASE-T also requires full-duplex +operation). +It is also .Em strongly recommended for use whenever possible; without auto-negotiation the link will usually not operate unless both partners are configured to use the @@ -385,18 +393,19 @@ property in .Lp Auto-negotiation may also be disabled, by setting the .Sy adv_autoneg_cap -property to 0. In this case, the highest enabled link mode (using the above -list) is +property to 0. +In this case, the highest enabled link mode (using the above list) is .Dq forced for the link. .Ss Flow Control Link layer flow control is available on many modern devices, and is mandatory -for operation at 10 Gbps. It requires that the link be auto-negotiated, and -that the link be full-duplex, in order to function. +for operation at 10 Gbps. +It requires that the link be auto-negotiated, and that the link be full-duplex, +in order to function. .Lp -Flow control is applied when a receiver becomes congested. In this case the -receiver can send a special frame, called a pause frame, to request its -partner cease transmitting for a short period of time. +Flow control is applied when a receiver becomes congested. +In this case the receiver can send a special frame, called a pause frame, to +request its partner cease transmitting for a short period of time. .Lp Flow control can be said to be either symmetric, in which case both partners can send and honor pause frames, or asymmetric, in which case one partner @@ -404,7 +413,8 @@ may not transmit pause frames. .Lp The flow control mode used is driven by the .Sy flowctrl -property. It has the following meanings: +property. +It has the following meanings: .Lp .Bl -column -compact -offset indent Dv .It \(dqno\(dq Ta Neither send, nor honor pause frames. @@ -421,27 +431,30 @@ and .Sy link_asmpause .Pc are based on the properties exchanged in the auto-negotiation and are -confusing as a result. Administrators are advised to use the +confusing as a result. +Administrators are advised to use the .Sy flowctrl property instead. . .Ss Jumbo Frames The IEEE 802.3 standard specifies a standard frame size of 1518 bytes, which includes a 4-byte frame checksum, a 14-byte header, and 1500 bytes -of payload. Most devices support larger frame sizes than this, and -when all possible parties on the same local network can do so, it may be -advantageous to choose a larger frame size; 9000 bytes is the most common -option, as it allows a transport layer to convey 8 KB (8192) of data, while -leaving room for various link, network, and transport layer headers. +of payload. +Most devices support larger frame sizes than this, and when all possible parties +on the same local network can do so, it may be advantageous to choose a larger +frame size; 9000 bytes is the most common option, as it allows a transport layer +to convey 8 KB (8192) of data, while leaving room for various link, network, and +transport layer headers. .Lp Note that the use of frames carrying more than 1500 bytes of payload is not standardized, even though it is common practice. .Lp The .Sy mtu -property is used to configure the frame size. Note that this is the size of -the payload, and excludes the preamble, checksum, and header. It also excludes -the tag for devices that support tagging (see +property is used to configure the frame size. +Note that this is the size of the payload, and excludes the preamble, checksum, +and header. +It also excludes the tag for devices that support tagging (see .Sx Virtual LANs below). .Lp @@ -450,22 +463,24 @@ size, or communication may cease to function properly. .Lp Note that the .Sy mtu -property refers to the link layer property. It may be necessary to configure -upper layer protocols such as IP to use a different size when this changes. +property refers to the link layer property. +It may be necessary to configure upper layer protocols such as IP to use a +different size when this changes. See .Xr ifconfig 1M . . .Ss Virtual LANs Most devices support virtual LANs (and also priority control tagging) though -the use of a 4-byte tag inserted between the frame header and payload. The -details of configuration of this are covered in the +the use of a 4-byte tag inserted between the frame header and payload. +The details of configuration of this are covered in the .Xr dladm 1M manual. . .Ss Data Link Provider Interface (DLPI) Details . The correct method for applications to access Ethernet devices directly -is to use the DLPI. See +is to use the DLPI. +See .Xr dlpi 7P and .Xr libdlpi 3LIB @@ -493,14 +508,16 @@ Additionally, it is possible to configure provide names to interfaces using the .Xr dladm 1M .Sy rename-link -subcommand. Such vanity names are only accessible using DLPI style 1. +subcommand. +Such vanity names are only accessible using DLPI style 1. .Sh NOTES There may be other mechanisms available to configure link layer properties. Historically the .Xr ndd 1M command, and .Xr driver.conf 4 -files could be used to do this. These methods are deprecated in favor of +files could be used to do this. +These methods are deprecated in favor of .Xr dladm 1M properties. . diff --git a/usr/src/man/man5/loader.5 b/usr/src/man/man5/loader.5 index ef651b02a1..655e4ad955 100644 --- a/usr/src/man/man5/loader.5 +++ b/usr/src/man/man5/loader.5 @@ -33,8 +33,9 @@ The .Nm is the final stage of .Nm illumos Ns 's -kernel bootstrapping process. The actual name for the stage depends on -the platform. On IA32 (i386) architectures with BIOS firmware, it is a +kernel bootstrapping process. +The actual name for the stage depends on the platform. +On IA32 (i386) architectures with BIOS firmware, it is a .Pa BTX client and named .Nm zfsloader . @@ -49,17 +50,20 @@ supports booting from .Cm HSFS and .Cm NFS -file systems. Additionally, +file systems. +Additionally, .Nm can load files from the .Cm TFTP -file service. The NFS and TFTP based boot is enabled via +file service. +The NFS and TFTP based boot is enabled via .Xr pxeboot 5 . The .Nm -also does support uncompressing gzip files while reading. The uncompression -will happen automatically if the compressed file is stored without .gz -suffix or if the file is accessed by leaving out the .gz suffix from the name. +also does support uncompressing gzip files while reading. +The uncompression will happen automatically if the compressed file is stored +without .gz suffix or if the file is accessed by leaving out the .gz suffix from +the name. If the file is referred by full name, including .gz suffix, then the file content is read as is and the uncompression is not performed. .Pp @@ -189,8 +193,8 @@ The behavior of this builtin is changed if is loaded. .Pp .It Ic chain Ar device -Chain load another boot loader from the specified device. Device can be either -disk name or partition. +Chain load another boot loader from the specified device. +Device can be either disk name or partition. .Pp .It Ic echo Xo .Op Fl n @@ -399,7 +403,8 @@ Will set .Fl v option. .It Va boot-args -Will set custom arguments for the kernel. If set in +Will set custom arguments for the kernel. +If set in .Nm configuration, the .Nm diff --git a/usr/src/man/man5/man.5 b/usr/src/man/man5/man.5 index 0ed6910e33..6598394cd7 100644 --- a/usr/src/man/man5/man.5 +++ b/usr/src/man/man5/man.5 @@ -21,26 +21,28 @@ .Fl man .Ar .Sh DESCRIPTION -These macros are used to lay out the reference pages in this manual. Note: if +These macros are used to lay out the reference pages in this manual. +Note: if .Ar file contains format input for a preprocessor, the commands shown -above must be piped through the appropriate preprocessor. This is handled -automatically by the +above must be piped through the appropriate preprocessor. +This is handled automatically by the .Xr man 1 -command. See the +command. +See the .Sx Conventions section. .Lp Any text argument .Ar t -may be zero to six words. Quotes may be used to -include SPACE characters in a +may be zero to six words. +Quotes may be used to include SPACE characters in a .Qq word . If .Ar text is empty, the special -treatment is applied to the next input line with text to be printed. In this -way +treatment is applied to the next input line with text to be printed. +In this way .Nm \&.I may be used to italicize a whole line, or .Nm \&.SB @@ -48,7 +50,8 @@ may be used to make small bold letters. .Lp A prevailing indent distance is remembered between successive indented paragraphs, and is reset to default value upon reaching a non-indented -paragraph. Default units for indents +paragraph. +Default units for indents .Nm i are ens. .Lp @@ -108,7 +111,8 @@ Sets prevailing indent to .5i for nested indents. When formatting a manual page, .Nm examines the first line to determine -whether it requires special processing. For example a first line consisting of: +whether it requires special processing. +For example a first line consisting of: .Lp .Dl \&'\e" t .Lp @@ -122,13 +126,14 @@ A typical manual page for a command or function is laid out as follows: .It Nm \&.TH Ar title Op "1-9" . The name of the command or function, which serves as the title of the manual -page. This is followed by the number of the section in which it appears. +page. +This is followed by the number of the section in which it appears. . .It Nm \&.SH NAME . The name, or list of names, by which the command is called, followed by a dash -and then a one-line summary of the action performed. All in roman font, this -section contains no +and then a one-line summary of the action performed. +All in roman font, this section contains no .Xr troff 1 commands or escapes, and no macro requests. It is used to generate the database used by the @@ -139,48 +144,52 @@ command. .Bl -tag -width "Functions:" .It Sy Commands: The syntax of the command and its arguments, as typed on the command line. -When in boldface, a word must be typed exactly as printed. When in italics, a -word can be replaced with an argument that you supply. References to bold or -italicized items are not capitalized in other sections, even when they begin a -sentence. +When in boldface, a word must be typed exactly as printed. +When in italics, a word can be replaced with an argument that you supply. +References to bold or italicized items are not capitalized in other sections, +even when they begin a sentence. .Lp Syntactic symbols appear in roman face: .Bl -tag -width " " .It Op " " An argument, when surrounded by brackets is optional. .It | -Arguments separated by a vertical bar are exclusive. You can supply only one -item from such a list. +Arguments separated by a vertical bar are exclusive. +You can supply only one item from such a list. .It \&.\|.\|. -Arguments followed by an ellipsis can be repeated. When an ellipsis follows a -bracketed set, the expression within the brackets can be repeated. +Arguments followed by an ellipsis can be repeated. +When an ellipsis follows a bracketed set, the expression within the brackets can +be repeated. .El .It Sy Functions: If required, the data declaration, or .Li #include directive, is shown first, -followed by the function declaration. Otherwise, the function declaration is -shown. +followed by the function declaration. +Otherwise, the function declaration is shown. .El . .It Nm \&.SH DESCRIPTION . -A narrative overview of the command or function's external behavior. This -includes how it interacts with files or data, and how it handles the standard -input, standard output and standard error. Internals and implementation details -are normally omitted. This section attempts to provide a succinct overview in -answer to the question, "what does it do?" +A narrative overview of the command or function's external behavior. +This includes how it interacts with files or data, and how it handles the +standard input, standard output and standard error. +Internals and implementation details are normally omitted. +This section attempts to provide a succinct overview in answer to the question, +"what does it do?" .Lp Literal text from the synopsis appears in constant width, as do literal filenames and references to items that appear elsewhere in the reference -manuals. Arguments are italicized. +manuals. +Arguments are italicized. .Lp If a command interprets either subcommands or an input grammar, its command interface or input grammar is normally described in a .Nm USAGE section, which follows the .Nm OPTIONS -section. The +section. +The .Nm DESCRIPTION section only describes the behavior of the command itself, not that of subcommands. @@ -223,14 +232,15 @@ with the command or function. .Sh NOTES The .Nm -package should not be used for new documentation. The +package should not be used for new documentation. +The .Xr mdoc 5 , package is preferred, as it uses semantic markup rather than physical markup. .Sh CODE SET INDEPENDENCE When processed with .Xr mandoc 1 , -this package is Code Set Independent. However, when processed with -legacy tools such as +this package is Code Set Independent. +However, when processed with legacy tools such as .Xr nroff 1 and .Xr troff 1 , diff --git a/usr/src/man/man5/mdoc.5 b/usr/src/man/man5/mdoc.5 index 643a269781..6d81124b02 100644 --- a/usr/src/man/man5/mdoc.5 +++ b/usr/src/man/man5/mdoc.5 @@ -374,8 +374,8 @@ This often contains snippets of well-formed, well-tested invocations. Make sure that examples work properly! .It Em DIAGNOSTICS Documents error and diagnostic messages displayed to the user or -sent to logs. Note that exit -status and return values should be documented in the +sent to logs. +Note that exit status and return values should be documented in the .Em EXIT STATUS and .Em RETURN VALUES @@ -394,100 +394,113 @@ This section is usually absent, but will be present when the interface is specific to one or more architectures. .It Em CODE SET INDEPENDENCE Indicates whether the interface operates correctly with various different -code sets. True independent code sets will support not only ASCII and -Extended UNIX Codesets (EUC), but also other multi-byte encodings such as -UTF-8 and GB2312. +code sets. +True independent code sets will support not only ASCII and Extended UNIX +Codesets (EUC), but also other multi-byte encodings such as UTF-8 and GB2312. .Pp -Generally there will be some limitations that are fairly standard. See -.Xr standards 5 for more information about some of these. Most interfaces -should support at least UTF-8 in addition to ASCII. +Generally there will be some limitations that are fairly standard. +See +.Xr standards 5 +for more information about some of these. +Most interfaces should support at least UTF-8 in addition to ASCII. .It Em INTERFACE STABILITY -Indicates the level of commitment to the interface. Interfaces can be described -with in the following ways: +Indicates the level of commitment to the interface. +Interfaces can be described with in the following ways: .Bl -tag -width Ds .It Nm Standard Indicates that the interface is defined by one or more standards bodies. Generally, changes to the interface will be carefully managed to conform -to the relevant standards. These interfaces are generally the most suitable -for use in portable programs. +to the relevant standards. +These interfaces are generally the most suitable for use in portable programs. .It Nm Committed Indicates that the interface is intended to be preserved for the long-haul, and will rarely, if ever change, and never without notification (barring -extraordinary and extenuating circumstances). These interfaces are -preferred over other interfaces with the exeception of +extraordinary and extenuating circumstances). +These interfaces are preferred over other interfaces with the exeception of .Nm Standard interfaces. .It Nm Uncommitted -Indicates that the interface may change. Generally, changes to these interfaces -should be infrequent, and some effort will be made to address compatibility -considerations when changing or removing such interfaces. However, there is -no firm commitment to the preservation of the interface. Most often this -is applied to interfaces where operational experience with the interface -is still limited and some need to change may be anticipated. +Indicates that the interface may change. +Generally, changes to these interfaces should be infrequent, and some effort +will be made to address compatibility considerations when changing or removing +such interfaces. +However, there is no firm commitment to the preservation of the interface. +Most often this is applied to interfaces where operational experience with the +interface is still limited and some need to change may be anticipated. .Pp Consumers should expect to revalidate any .Nm Uncommitted -interfaces when crossing release boundaries. Products intended for -use on many releases or intended to support compatibility with future -releases should avoid these interfaces. +interfaces when crossing release boundaries. +Products intended for use on many releases or intended to support compatibility +with future releases should avoid these interfaces. .It Nm Volatile -The interface can change at any time for any reason. Often this relates to -interfaces that are part of external software components that are still evolving -rapidly. Consumers should not expect that the interface (either binary or -source level) will be unchanged from one release to the next. +The interface can change at any time for any reason. +Often this relates to interfaces that are part of external software components +that are still evolving rapidly. +Consumers should not expect that the interface (either binary or source level) +will be unchanged from one release to the next. .It Nm Not-an-Interface Describes something that is specifically not intended for programmatic -consumption. For example, specific human-readable output, or the layout -of graphical items on a user interface, may be described this way. Generally -programmatic alternatives to these will be available, and should be used -when programmatic consumption is needed. +consumption. +For example, specific human-readable output, or the layout of graphical items on +a user interface, may be described this way. +Generally programmatic alternatives to these will be available, and should be +used when programmatic consumption is needed. .It Nm Private -This is an internal interface. Generally these interfaces should only be -used within the project, and should not be used by other programs or modules. -The interface can and will change without notice as the project needs, at -any time. +This is an internal interface. +Generally these interfaces should only be used within the project, and should +not be used by other programs or modules. +The interface can and will change without notice as the project needs, at any +time. .Pp Most often, Private interfaces will lack any documentation whatsoever, and generally any undocumented interface can be assumed to be Private. .It Nm Obsolete The interface is not intended for use in new projects or programs, and may -be removed at a future date. The +be removed at a future date. +The .Nm Obsolete word is a modifier that can -be applied to other commitment levels. For example an +be applied to other commitment levels. +For example an .Nm Obsolete Committed interface is unlikely to be removed or changed, but nonetheless new use is discouraged (perhaps a better newer alternative is present). .El .It Em MT-LEVEL This section describes considerations for the interface when used within -programs that use multiple threads. More discussion of these considerations -is made in the MT-Level section of +programs that use multiple threads. +More discussion of these considerations is made in the MT-Level section of .Xr attributes 5 . The interface can be described in the following ways. .Bl -tag -width Ds .It Nm Safe -Indicates the interface is safe for use within multiple threads. There -may be additional caveats that apply, in which case those will be -described. Note that some interfaces have semantics which may affect -other threads, but these should be an intrinsic part of the interface -rather than an unexpected side effect. For example, closing a file in -one thread will cause that file to be closed in all threads. +Indicates the interface is safe for use within multiple threads. +There may be additional caveats that apply, in which case those will be +described. +Note that some interfaces have semantics which may affect other threads, but +these should be an intrinsic part of the interface rather than an unexpected +side effect. +For example, closing a file in one thread will cause that file to be closed in +all threads. .It Nm Unsafe Indicates the interface is unsuitable for concurrent use within multiple -threads. A threaded application may still make use of the interface, but -will be required to provide external synchronization means to ensure that -only a single thread calls the interface at a time. +threads. +A threaded application may still make use of the interface, but will be required +to provide external synchronization means to ensure that only a single thread +calls the interface at a time. .It Nm MT-Safe Indicates that the interface is not only safe for concurrent use, but is -designed for such use. For example, a +designed for such use. +For example, a .Nm Safe interface may make use of a global lock to provide safety, but at reduced internal concurrency, whereas an .Nm MT-Safe interface will be designed to be efficient even when used concurrently. .It Nm Async-Signal-Safe -Indicates that the library is safe for use within a signal handler. An +Indicates that the library is safe for use within a signal handler. +An .Nm MT-Safe interface can be made .Nm Async-Signal-Safe @@ -1261,7 +1274,8 @@ See also and .Sx \&Ox . .Ss \&Cd -Kernel configuration declaration. It is found in pages for +Kernel configuration declaration. +It is found in pages for .Bx and not used here. .Pp diff --git a/usr/src/man/man5/menu.4th.5 b/usr/src/man/man5/menu.4th.5 index e4644008ed..92f15d9d9b 100644 --- a/usr/src/man/man5/menu.4th.5 +++ b/usr/src/man/man5/menu.4th.5 @@ -142,7 +142,8 @@ Default is .It Va loader_menu_title_align Default is to align .Ic loader_menu_title -centered above the menu. This can be set to +centered above the menu. +This can be set to .Dq Li left or .Dq Li right @@ -268,8 +269,8 @@ represents the ASCII decimal value for .Pp For all values of .Dq Li x -above, use any number between 1 through 9. Sorry, double-digits are not -currently supported. +above, use any number between 1 through 9. +Sorry, double-digits are not currently supported. .Sh FILES .Bl -tag -width /boot/forth/loader.4th -compact .It Pa /boot/zfsloader diff --git a/usr/src/man/man5/pam_timestamp.5 b/usr/src/man/man5/pam_timestamp.5 index 7e31657ab1..59b425d8f1 100644 --- a/usr/src/man/man5/pam_timestamp.5 +++ b/usr/src/man/man5/pam_timestamp.5 @@ -15,8 +15,7 @@ .Os .Sh NAME .Nm pam_timestamp -.Nd PAM authentication module using cached successful -authentication attempts +.Nd PAM authentication module using cached successful authentication attempts .Sh SYNOPSIS .Nm pam_timestamp.so.1 .Op Ar debug @@ -50,7 +49,7 @@ and Proper authentication operation requires .Xr pam_unix_cred 5 be stacked above -.Xr pam_timestamp . +.Nm . .Sh OPTIONS .Bl -tag -width Ds .It Dv debug @@ -60,8 +59,8 @@ debugging information at the .Sy LOG_AUTH | LOG_DEBUG level. .It Dv timeout -Specifies the period (in miniutes) for which the timestamp -file is valid. The default value is 5 minutes. +Specifies the period (in miniutes) for which the timestamp file is valid. +The default value is 5 minutes. .El .Sh FILES .Bl -tag -width indent diff --git a/usr/src/man/man5/zfsloader.5 b/usr/src/man/man5/zfsloader.5 index f6b56a9245..ebfed4f0c2 100644 --- a/usr/src/man/man5/zfsloader.5 +++ b/usr/src/man/man5/zfsloader.5 @@ -94,6 +94,7 @@ set currdev=zfs:rpool/ROOT/knowngood: Although setting the .Va currdev as shown in the example above is supported, it is advisable to use loader -beadm command or boot environment menu instead. The reason is, the beadm -or menu selection will also instruct loader to clean up the currently set -configuration and load configuration from the new boot environment. +beadm command or boot environment menu instead. +The reason is, the beadm or menu selection will also instruct loader to clean up +the currently set configuration and load configuration from the new boot +environment. diff --git a/usr/src/man/man7d/afe.7d b/usr/src/man/man7d/afe.7d index 9f7c380050..3fb7991769 100644 --- a/usr/src/man/man7d/afe.7d +++ b/usr/src/man/man7d/afe.7d @@ -36,8 +36,9 @@ PCI controllers originally produced by ADMtek and Infineon. .Lp These devices generally support the standard Fast Ethernet features, including 10BASE-T and 100BASE-TX, both full and half duplex operation, IEEE 802.3 -autonegotiation, etc. They also support full size MTUs (1500 bytes), -even when used with VLANs. Most of them also support flow control. +autonegotiation, etc. +They also support full size MTUs (1500 bytes), even when used with VLANs. +Most of them also support flow control. . .Lp The device driver supports the diff --git a/usr/src/man/man7d/blkdev.7d b/usr/src/man/man7d/blkdev.7d index 022dbe4b0d..44f5fec7db 100644 --- a/usr/src/man/man7d/blkdev.7d +++ b/usr/src/man/man7d/blkdev.7d @@ -20,17 +20,17 @@ The .Nm driver supports generic block-oriented devices, such as non-volatile -memory storage devices. It provides a hardware independent layer -for such storage devices, allowing them to concentrate on the -hardware-specific details, while +memory storage devices. +It provides a hardware independent layer for such storage devices, allowing them +to concentrate on the hardware-specific details, while .Nm takes care of all the other details, such as .Xr dkio 7I . .Lp The .Nm -driver only supports block-oriented, random-access devices. It does -not support traditional rotational media and does not support +driver only supports block-oriented, random-access devices. +It does not support traditional rotational media and does not support SCSI commands. .Lp The most typical use case for @@ -65,7 +65,8 @@ logical unit number as well. .It Va sn This is the .Em slice -number, representing a subset of the disk. See +number, representing a subset of the disk. +See .Xr dkio 7I . .El . diff --git a/usr/src/man/man7d/elxl.7d b/usr/src/man/man7d/elxl.7d index 2abd3f962e..cc49101dbd 100644 --- a/usr/src/man/man7d/elxl.7d +++ b/usr/src/man/man7d/elxl.7d @@ -32,16 +32,17 @@ The .Nm driver provides support for the 3Com Etherlink XL -family of Ethernet and Fast Ethernet PCI controllers. These are often known -by their part numbers, most often 3c905 or 3c900 variants. +family of Ethernet and Fast Ethernet PCI controllers. +These are often known by their part numbers, most often 3c905 or 3c900 variants. .Lp The 3c905 devices generally support some form of 100 Mbps Ethernet, -whereas the 3c900 devices usually only support 10 Mbps. Some devices -support legacy media such as 10BASE-15, 10BASE-2, and even 10BASE-FL. +whereas the 3c900 devices usually only support 10 Mbps. +Some devices support legacy media such as 10BASE-15, 10BASE-2, and even +10BASE-FL. . Where applicable, the devices support auto-negotiation, both full and -half duplex, etc. They also support full size MTUs (1500 bytes), -even when used with VLANs. +half duplex, etc. +They also support full size MTUs (1500 bytes), even when used with VLANs. . .Lp The device driver supports the diff --git a/usr/src/man/man7d/i40e.7d b/usr/src/man/man7d/i40e.7d index e7d157b667..992297fe7d 100644 --- a/usr/src/man/man7d/i40e.7d +++ b/usr/src/man/man7d/i40e.7d @@ -53,20 +53,22 @@ support the use of flow control through hardware pause frames. .Sh APPLICATION PROGRAMMING INTERFACE For each device supported by the .Nm -installed in the system, a character-special file will be created. This -file supports the Data Link Provider Interface (DLPI) which is documented +installed in the system, a character-special file will be created. +This file supports the Data Link Provider Interface (DLPI) which is documented in .Xr dlpi 7P . For most consumers, the use of .Xr libdlpi 3LIB , is recommended. .Pp -Each instance is assigned a unique ascending integer identifier. A -device which has multiple ports may appear to the system as separate -instances. The system does not provide a guarnatee on how these will be -presented. Using this instance identifier, one can determine the exact -character-special file to open. For example, the first instance -enumerated in the system, with id 0, would be named +Each instance is assigned a unique ascending integer identifier. +A device which has multiple ports may appear to the system as separate +instances. +The system does not provide a guarnatee on how these will be presented. +Using this instance identifier, one can determine the exact character-special +file to open. +For example, the first instance enumerated in the system, with id 0, would be +named .Sy i40e0 . It exists in the file system at .Pa /dev/i40e0 . @@ -74,8 +76,8 @@ It exists in the file system at The .Nm i40e driver always performs auto-negotiation and depending on the model may -negotiate to 40 Gbps, 25 Gbps, 10 Gbps, or 1 Gbps. At this time, the -driver requires the use of auto-negotiation. +negotiate to 40 Gbps, 25 Gbps, 10 Gbps, or 1 Gbps. +At this time, the driver requires the use of auto-negotiation. .Pp The .Nm @@ -83,10 +85,13 @@ driver is managed by the .Xr dladm 1M utility. .Xr dladm 1M -is the preferred interface for setting all properties. While -.Xr driver.conf based configuration is possible, +is the preferred interface for setting all properties. +While +.Xr driver.conf 4 +based configuration is possible, .Xr dladm 1M -is recommended. The +is recommended. +The .Nm driver may be joined into an aggregation based on the link aggregation control protocol (LACP) through @@ -95,10 +100,10 @@ control protocol (LACP) through The device supports the following properties which may be tuned through its driver.conf file, .Pa /kernel/drv/i40e.conf . -Most of these properties cannot be changed after the device has been -started. The device is started in response to a DLPI consumer opening -the device and binding to it. This happens when an IP interfaces is -plumbed or another +Most of these properties cannot be changed after the device has been started. +The device is started in response to a DLPI consumer opening the device and +binding to it. +This happens when an IP interfaces is plumbed or another .Xr dlpi 7P consumer such as .Xr snoop 1M @@ -106,11 +111,13 @@ or an LLDP daemon is started. .Pp Some properties may be tuned at runtime with the .Xr dladm 1M -utility. Properties that can be will have the name of the dladm property -called out explicitly. +utility. +Properties that can be will have the name of the dladm property called out +explicitly. .Pp -These properties are not considered stable at this time. They may change -and should not be relied on. They are considered +These properties are not considered stable at this time. +They may change and should not be relied on. +They are considered .Sy Volatile . It is not expected that administrators of the system will have to tune these values. @@ -129,7 +136,8 @@ The .Sy default_mtu property determines the starting MTU of the various device instances. Note that the device's MTU also determines the upper bound of the MTU of -all VNICs created over the device. The default MTU is +all VNICs created over the device. +The default MTU is .Sy 1500 . .Ed .It Sy mr_enable @@ -143,8 +151,9 @@ Maximum: The .Sy mr_enable proeprty determines whether or not support for multiple rings is enabled -for the device. The default is always to enable them. It is not -recommended to to disable them. +for the device. +The default is always to enable them. +It is not recommended to to disable them. .Ed .It Sy rx_ring_size .Bd -filled -compact @@ -157,10 +166,10 @@ Maximum: The .Sy rx_ring_size property determines the number of descriptors that will be used in each -receive ring on the card. Administrators should not normally need to -tune this value. Hardware requires that the ring size be a multiple of -32. The system will round up the set value to the nearest multiple of -32. +receive ring on the card. +Administrators should not normally need to tune this value. +Hardware requires that the ring size be a multiple of 32. +The system will round up the set value to the nearest multiple of 32. .Ed .It Sy tx_ring_size .Bd -filled -compact @@ -173,10 +182,10 @@ Maximum: The .Sy tx_ring_size property determines the number of descriptors that will be used in each -transmit ring on the card. Administrators should not normally need to -tune this value. Hardware requires that the ring size be a multiple of -32. The system will round up the set value to the nearest multiple of -32. +transmit ring on the card. +Administrators should not normally need to tune this value. +Hardware requires that the ring size be a multiple of 32. +The system will round up the set value to the nearest multiple of 32. .Ed .It Sy tx_resched_threshold .Bd -filled -compact @@ -189,11 +198,13 @@ Maximum: The .Sy tx_resched_threshold property determines the number of descriptors that must be available for -a frame to be transmitted. The maximum is variable. It is dependent on -the value of the +a frame to be transmitted. +The maximum is variable. +It is dependent on the value of the .Sy tx_ring_size -property. At least eight descriptors must be available for the device to -function correctly. +property. +At least eight descriptors must be available for the device to function +correctly. .Ed .It Sy rx_limit_per_intr .Bd -filled -compact @@ -206,9 +217,9 @@ Maximum: The .Sy rx_limit_per_intr property determines the maximum number of packets that will be processed -on a given ring during a single interrupt. This is done to try and -guarantee some amount of liveness in the system. It is not expected -that administrators will have to tune this value. +on a given ring during a single interrupt. +This is done to try and guarantee some amount of liveness in the system. +It is not expected that administrators will have to tune this value. .Ed .It Sy tx_hcksum_enable .Bd -filled -compact @@ -221,10 +232,10 @@ Maximum: The .Sy tx_hcksum_enable property controls whether or not the device enables support for hardware -checksuming of outgoing packets. The default is to always enable support -for this. Turning it off will increase latency and decrease throughput -when transmitting packets, but should be done if a hardware bug is -suspected. +checksuming of outgoing packets. +The default is to always enable support for this. +Turning it off will increase latency and decrease throughput when transmitting +packets, but should be done if a hardware bug is suspected. .Ed .It Sy rx_hcksum_enable .Bd -filled -compact @@ -237,10 +248,10 @@ Maximum: The .Sy rx_hcksum_enable property controls whether or not the device enables support for hardware -checksuming of incoming packets. The default is to always enable support -for this. Turning it off will increase latency and decrease throughput -when receiving packets, but should be done if a hardware bug is -suspected. +checksuming of incoming packets. +The default is to always enable support for this. +Turning it off will increase latency and decrease throughput when receiving +packets, but should be done if a hardware bug is suspected. .Ed .It Sy rx_dma_threshold .Bd -filled -compact @@ -256,9 +267,11 @@ The .Sy rx_dma_treshold indicates the size in bytes of a received frame, including all of its headers, at which the driver should not copy the frame but instead bind -DMA memory. By setting this property to its minimum, all frames will be -processed with DMA binding. By setting this property to its maximum, all -frames will be processed by copying the frame. +DMA memory. +By setting this property to its minimum, all frames will be processed with DMA +binding. +By setting this property to its maximum, all frames will be processed by copying +the frame. .Ed .El .Sh ARCHITECTURE diff --git a/usr/src/man/man7d/iprb.7d b/usr/src/man/man7d/iprb.7d index 2e7ca9a416..6ac7c445ac 100644 --- a/usr/src/man/man7d/iprb.7d +++ b/usr/src/man/man7d/iprb.7d @@ -32,14 +32,16 @@ The .Nm driver provides support for the Intel PRO/100 family of Fast Ethernet -PCI controllers. This includes support for Intel 82558, 82559, 82550, -and 82551 parts, as well as certain controllers found on certain Intel -southbridge controllers (ICH2 and ICH3). +PCI controllers. +This includes support for Intel 82558, 82559, 82550, and 82551 parts, as well as +certain controllers found on certain Intel southbridge controllers (ICH2 and +ICH3). .Lp These devices generally support the standard Fast Ethernet features, including 10BASE-T and 100BASE-TX, both full and half duplex operation, IEEE 802.3 -autonegotiation, etc. They also support full size MTUs (1500 bytes), -even when used with VLANs. Some of them also support flow control. +autonegotiation, etc. +They also support full size MTUs (1500 bytes), even when used with VLANs. +Some of them also support flow control. . .Lp The device driver supports the diff --git a/usr/src/man/man7d/mxfe.7d b/usr/src/man/man7d/mxfe.7d index 38253b4b5a..5b0f49fe76 100644 --- a/usr/src/man/man7d/mxfe.7d +++ b/usr/src/man/man7d/mxfe.7d @@ -37,8 +37,8 @@ PCI controllers. .Lp These devices generally support the standard Fast Ethernet features, including 10BASE-T and 100BASE-TX, both full and half duplex operation, IEEE 802.3 -autonegotiation, etc. They also support full size MTUs (1500 bytes), -even when used with VLANs. +autonegotiation, etc. +They also support full size MTUs (1500 bytes), even when used with VLANs. . .Lp The device driver supports the diff --git a/usr/src/man/man7d/rtls.7d b/usr/src/man/man7d/rtls.7d index 4389bf3141..f3159bb278 100644 --- a/usr/src/man/man7d/rtls.7d +++ b/usr/src/man/man7d/rtls.7d @@ -36,8 +36,8 @@ PCI controllers. .Lp These devices generally support the standard Fast Ethernet features, including 10BASE-T and 100BASE-TX, both full and half duplex operation, IEEE 802.3 -autonegotiation, etc. They also support full size MTUs (1500 bytes), -even when used with VLANs. +autonegotiation, etc. +They also support full size MTUs (1500 bytes), even when used with VLANs. . .Lp The device driver supports the diff --git a/usr/src/man/man7d/usba.7d b/usr/src/man/man7d/usba.7d index 87c61d6758..3565badc61 100644 --- a/usr/src/man/man7d/usba.7d +++ b/usr/src/man/man7d/usba.7d @@ -12,13 +12,13 @@ .Nd illumos USB Architecture (USBA) .Sh DESCRIPTION USB provides a low-cost means for attaching peripheral devices, including -mass-storage devices, keyboards, mice, and printers, to a system. For complete -information on the USB architecture, visit the USB website at +mass-storage devices, keyboards, mice, and printers, to a system. +For complete information on the USB architecture, visit the USB website at http://www.usb.org. .Pp -USBA supports 126 hot-pluggable USB devices per USB bus. The maximum data -transfer rate is 5 Gbits (SuperSpeed USB 3.0), 480 Mbits (high speed USB -2.0), 12 Mbits (full speed USB 1.x), or 1.5 Mbits (low speed USB 1.x). +USBA supports 126 hot-pluggable USB devices per USB bus. +The maximum data transfer rate is 5 Gbits (SuperSpeed USB 3.0), 480 Mbits (high +speed USB 2.0), 12 Mbits (full speed USB 1.x), or 1.5 Mbits (low speed USB 1.x). .Pp USBA adheres to the .Em Universal Serial Bus 3.0 @@ -38,9 +38,11 @@ Devices without a driver may be able to leverage .Xr libusb 3LIB . .Sh FILES Listed below are drivers and modules which either utilize or are utilized by -USBA. Drivers in -.Pa /kernel/drv\ -are 32 bit drivers (x86 only). Drivers in +USBA. +Drivers in +.Pa /kernel/drv +are 32 bit drivers (x86 only). +Drivers in .Pa /kernel/drv/sparcv9 or .Pa kernel/drv/amd64 @@ -117,7 +119,8 @@ are 64 bit drivers. .El .Sh DIAGNOSTICS The messages described below may appear on the system console as well as being -logged. All messages are formatted in the following manner: +logged. +All messages are formatted in the following manner: .Bl -tag -width Sy -offset 2n .It WARNING: Error message... .El @@ -125,14 +128,17 @@ logged. All messages are formatted in the following manner: .It Sy no driver found for device <device_name> (interface <number> node name=<node_name>) The installed software does not contain a supported driver for this -hardware. <number> is the interface number. <name> is either the device path name or the device name. +hardware. +<number> is the interface number. +<name> is either the device path name or the device name. .It Sy Draining callbacks timed out! -An internal error occurred. Please reboot your system. If this problem -persists, contact your system vendor. +An internal error occurred. +Please reboot your system. +If this problem persists, contact your system vendor. .El .Pp -The following messages may be logged into the system log. They are formatted in -the following manner: +The following messages may be logged into the system log. +They are formatted in the following manner: .Bd -literal -offset 2n <device path><usba<instance number>): message... .Ed diff --git a/usr/src/man/man7d/xhci.7d b/usr/src/man/man7d/xhci.7d index e2822fd19c..4f2836b97e 100644 --- a/usr/src/man/man7d/xhci.7d +++ b/usr/src/man/man7d/xhci.7d @@ -23,9 +23,9 @@ The .Nm driver supports PCI devices that implement versions 1.0 and 1.1 of the -Extensible Host Controller Inteface Specification. These devices provide -support for USB 3.0, USB 2.x, and USB 1.x devices and is integrated into -the broader illumos USB Architecture (USBA). +Extensible Host Controller Inteface Specification. +These devices provide support for USB 3.0, USB 2.x, and USB 1.x devices and is +integrated into the broader illumos USB Architecture (USBA). .Pp The .Nm @@ -38,15 +38,16 @@ and .Pp Administrators do not interact with the .Nm -driver directly. USB devices are managed with +driver directly. +USB devices are managed with .Xr cfgadm 1M . See .Xr cfgadm_usb 1M for more information on how to specifically manage USB devices and how they are laid out in the system. .Xr cfgadm 1M -is only used to manage devices at a USB level. For example, a USB NIC -would still be managed with +is only used to manage devices at a USB level. +For example, a USB NIC would still be managed with .Xr dladm 1M at a networking level. .Pp @@ -54,15 +55,16 @@ On some x86 systems USB ports may be routed to either an instance of the .Nm driver or an instance of the .Xr ehci 7D -driver. By default, all such ports are routed to the +driver. +By default, all such ports are routed to the .Nm driver, allowing those devices to operate at USB 3.x speed by default. -This is most common on Intel platforms and chipsets. While this is -controlled with the +This is most common on Intel platforms and chipsets. +While this is controlled with the .Sy xhci-reroute property discussed below, changing it may not be sufficient to change -the behavior. The BIOS or ACPI data for many x86 systems may toggle this -automatically. +the behavior. +The BIOS or ACPI data for many x86 systems may toggle this automatically. .Sh PROPERTIES The .Nm @@ -77,8 +79,9 @@ The .Sy xhci-reroute property determines whether or not USB ports are re-routed to the .Nm -driver. The default behavior is to route such ports. To disable this, -the property should be set to +driver. +The default behavior is to route such ports. +To disable this, the property should be set to .Sy 0 . Any other value, or the lack of the property, cause the default behavior to take place. diff --git a/usr/src/man/man7p/ndp.7p b/usr/src/man/man7p/ndp.7p index 589a6dc5ad..28d4d2a1d4 100644 --- a/usr/src/man/man7p/ndp.7p +++ b/usr/src/man/man7p/ndp.7p @@ -32,20 +32,24 @@ ioctl(s, SIOCLIFSETND, &lifr); ioctl(s, SIOCLIFDELND, &lifr); .Ed .Sh DESCRIPTION -The Neighbor Discovery Protocol (NDP) is a protocol used to distribute and request -information about neighboring IPv6 systems on the local network, much like +The Neighbor Discovery Protocol (NDP) is a protocol used to distribute and +request information about neighboring IPv6 systems on the local network, much +like .Xr ARP 7P -for IPv4. NDP is also responsible for spreading information about the network -gateway and how hosts should configure themselves +for IPv4. +NDP is also responsible for spreading information about the network gateway and +how hosts should configure themselves .Pq see Xr in.ndpd 1M for more on how this happens . .Sh APPLICATION PROGRAMMING INTERFACE The operating system provides several ioctls to help manipulate the mappings -obtained through NDP. They are +obtained through NDP. +They are .Sy SIOCLIFGETND , .Sy SIOCLIFSETND , and .Sy SIOCLIFDELND , -for getting, setting, and deleting respectively. Each of these ioctls takes a +for getting, setting, and deleting respectively. +Each of these ioctls takes a .Vt struct lifreq .Pq see Xr if 7P for details , where the @@ -120,13 +124,14 @@ Flags that can be placed in are: .Bl -tag -offset indent -width 16m .It Sy NDF_ISROUTER_ON -Mark this entry as being a router. This will cause Neighbor Advertisements for -this address to be sent with the R-bit (Router). +Mark this entry as being a router. +This will cause Neighbor Advertisements for this address to be sent with the +R-bit (Router). .It Sy NDF_ISROUTER_OFF If this entry was flagged as being a router, remove the flag. .It Sy NDF_ANYCAST_ON -Mark this entry as being for an anycast address. This prevents sending Neighbor -Advertisements with the O-bit (Override). +Mark this entry as being for an anycast address. +This prevents sending Neighbor Advertisements with the O-bit (Override). .It Sy NDF_ANYCAST_OFF If this entry was flagged as an anycast address, remove the flag. .It Sy NDF_STATIC @@ -136,7 +141,8 @@ Prevent this entry from being deleted by the system. When using .Sy SIOCLIFGETND , these flags represent the current state of the corresponding Neighbor Cache -Entry. When using +Entry. +When using .Sy SIOCLIFSETND , these flags represent what changes should be applied to the underlying entry. .Pp @@ -148,8 +154,9 @@ ioctls are .Fa lifr_name and .Fa lnr_addr . -All other fields should be zeroed out. After successfully getting an entry, the -other fields will be filled in. When using +All other fields should be zeroed out. +After successfully getting an entry, the other fields will be filled in. +When using .Sy SIOCLIFSETND , all fields should be set to an appropriate value, as described above, with the exception of @@ -164,15 +171,17 @@ variable: .It Sy EAFNOSUPPORT A non-IPv6 socket was used to perform the ioctl. .It Sy EINVAL -The request contents were bad. This could be because conflicting flags were -used, the specified interface wasn't logical unit zero, or another reason. +The request contents were bad. +This could be because conflicting flags were used, the specified interface +wasn't logical unit zero, or another reason. .It Sy ENOMEM The system ran out of memory for internal data structures. .It Sy ENXIO The specified interface does not exist. .It Sy EPERM The caller does not have permission to modify the Neighbor Cache Entries -associated with this interface. They may be lacking the +associated with this interface. +They may be lacking the .Sy PRIV_SYS_NET_CONFIG privilege .Po see Xr privileges 5 Pc , @@ -182,8 +191,9 @@ There is no entry matching the specified address. .El .Sh EXAMPLES The following examples demonstrate how to get and set NDP mappings using the -provided ioctls. They can be compiled by using a C compiler and linking against -the sockets library. +provided ioctls. +They can be compiled by using a C compiler and linking against the sockets +library. .Ss Example 1: Getting a mapping .Bd -literal -offset indent $ gcc -Wall -lsocket -o get get.c diff --git a/usr/src/man/man9/Intro.9 b/usr/src/man/man9/Intro.9 index ab51ec889c..aaab907d35 100644 --- a/usr/src/man/man9/Intro.9 +++ b/usr/src/man/man9/Intro.9 @@ -7,8 +7,8 @@ .Nd introduction to kernel concepts .Sh DESCRIPTION This section outlines high-level concepts of the illumos kernel and its -subsystems. Specific documentation can be found in this section's -sub\-sections. +subsystems. +Specific documentation can be found in this section's sub\-sections. .Bl -tag -width Ds .It Section 9E Driver Entry Points diff --git a/usr/src/man/man9/vmem.9 b/usr/src/man/man9/vmem.9 index e42b05dc07..eb1f36ec1a 100644 --- a/usr/src/man/man9/vmem.9 +++ b/usr/src/man/man9/vmem.9 @@ -58,19 +58,21 @@ some subset of its parent. The virtual memory allocator manages these arenas and supports their natural hierarchical structure. .Ss Arenas -An arena is nothing more than a set of integers. These integers most -commonly represent virtual addresses, but in fact they can represent -anything at all. For example, we could use an arena containing the -integers minpid through maxpid to allocate process IDs. For uses of this -nature, prefer +An arena is nothing more than a set of integers. +These integers most commonly represent virtual addresses, but in fact they can +represent anything at all. +For example, we could use an arena containing the integers minpid through maxpid +to allocate process IDs. +For uses of this nature, prefer .Xr id_space 9F instead. .Pp .Fn vmem_create and .Fn vmem_destroy -create and destroy vmem arenas. In order to differentiate between arenas used -for addresses and arenas used for identifiers, the +create and destroy vmem arenas. +In order to differentiate between arenas used for addresses and arenas used for +identifiers, the .Dv VMC_IDENTIFIER flag is passed to .Fn vmem_create . @@ -79,8 +81,8 @@ failure. .Ss Spans We represent the integers in an arena as a collection of .Em spans , -or contiguous ranges of integers. For example, the kernel heap consists of -just one span: +or contiguous ranges of integers. +For example, the kernel heap consists of just one span: .Li "[kernelheap, ekernelheap)" . Spans can be added to an arena in two ways: explicitly, by .Fn vmem_add ; @@ -90,16 +92,17 @@ below. .Ss Segments Spans are subdivided into .Em segments , -each of which is either allocated or free. A segment, like a span, is a -contiguous range of integers. Each allocated segment +each of which is either allocated or free. +A segment, like a span, is a contiguous range of integers. +Each allocated segment .Li "[addr, addr + size)" represents exactly one .Li "vmem_alloc(size)" that returned .Sy addr . -Free segments represent the space between allocated segments. If two free -segments are adjacent, we coalesce them into one larger segment; that is, if -segments +Free segments represent the space between allocated segments. +If two free segments are adjacent, we coalesce them into one larger segment; +that is, if segments .Li "[a, b)" and .Li "[b, c)" @@ -108,18 +111,20 @@ are both free, we merge them into a single segment The segments within a span are linked together in increasing\-address order so we can easily determine whether coalescing is possible. .Pp -Segments never cross span boundaries. When all segments within an imported -span become free, we return the span to its source. +Segments never cross span boundaries. +When all segments within an imported span become free, we return the span to its +source. .Ss Imported Memory -As mentioned in the overview, some arenas are logical subsets of -other arenas. For example, +As mentioned in the overview, some arenas are logical subsets of other arenas. +For example, .Sy kmem_va_arena (a virtual address cache that satisfies most .Fn kmem_slab_create requests) is just a subset of .Sy heap_arena -(the kernel heap) that provides caching for the most common slab sizes. When +(the kernel heap) that provides caching for the most common slab sizes. +When .Sy kmem_va_arena runs out of virtual memory, it .Em imports @@ -130,9 +135,9 @@ is the for .Sy kmem_va_arena. .Fn vmem_create -allows you to specify any existing vmem arena as the source for your new -arena. Topologically, since every arena is a child of at most one source, the -set of all arenas forms a collection of trees. +allows you to specify any existing vmem arena as the source for your new arena. +Topologically, since every arena is a child of at most one source, the set of +all arenas forms a collection of trees. .Ss Constrained Allocations Some vmem clients are quite picky about the kind of address they want. For example, the DVMA code may need an address that is at a particular @@ -147,14 +152,14 @@ Every arena has a notion of .Sq quantum , specified at .Fn vmem_create -time, that defines the arena's minimum unit of currency. Most commonly the -quantum is either 1 or +time, that defines the arena's minimum unit of currency. +Most commonly the quantum is either 1 or .Dv PAGESIZE , -but any power of 2 is legal. All vmem allocations are guaranteed to be -quantum\-aligned. +but any power of 2 is legal. +All vmem allocations are guaranteed to be quantum\-aligned. .Ss Relationship to the Kernel Memory Allocator -Every kmem cache has a vmem arena as its slab supplier. The kernel memory -allocator uses +Every kmem cache has a vmem arena as its slab supplier. +The kernel memory allocator uses .Fn vmem_alloc and .Fn vmem_free diff --git a/usr/src/man/man9e/mac.9e b/usr/src/man/man9e/mac.9e index 68ab72150d..deab66fe27 100644 --- a/usr/src/man/man9e/mac.9e +++ b/usr/src/man/man9e/mac.9e @@ -27,15 +27,18 @@ illumos DDI specific The .Sy MAC framework provides a means for implementing high-performance networking -device drivers. It is the successor to the GLD interfaces and is -sometimes referred to as the GLDv3. The remainder of this manual -introduces the aspects of writing devices drivers that leverage the MAC -framework. While both the GLDv3 and MAC framework refer to the same thing, in -this manual page we use the term the +device drivers. +It is the successor to the GLD interfaces and is sometimes referred to as the +GLDv3. +The remainder of this manual introduces the aspects of writing devices drivers +that leverage the MAC framework. +While both the GLDv3 and MAC framework refer to the same thing, in this manual +page we use the term the .Em MAC framework to refer to the device driver interface. .Pp -MAC device drivers are character devices. They define the standard +MAC device drivers are character devices. +They define the standard .Xr _init 9E , .Xr _fini 9E , and @@ -49,18 +52,20 @@ structures. The main interface with MAC is through a series of callbacks defined in a .Xr mac_callbacks 9S -structure. These callbacks control all the aspects of the device. They -range from sending data, getting and setting of -properties, controlling mac address filters, and also managing -promiscuous mode. +structure. +These callbacks control all the aspects of the device. +They range from sending data, getting and setting of properties, controlling mac +address filters, and also managing promiscuous mode. .Pp The MAC framework takes care of many aspects of the device driver's -management. A device that uses the MAC framework does not have to worry -about creating device nodes or implementing +management. +A device that uses the MAC framework does not have to worry about creating +device nodes or implementing .Xr open 9E or .Xr close 9E -routines. In addition, all of the work to interact with +routines. +In addition, all of the work to interact with .Xr dlpi 7P is taken care of automatically and transparently. .Ss Initializing MAC Support @@ -78,7 +83,8 @@ structure which is pointed to by a .Xr modldrv 9S structure and the corresponding NULL-terminated .Xr modlinkage 9S -structure. The +structure. +The .Xr dev_ops 9S structure should have a .Xr cb_ops 9S @@ -127,9 +133,10 @@ function pointers that will be used as callbacks by the framework. .Pp These steps should all be taken during a device's .Xr attach 9E -entry point. It is recommended that the driver perform this sequence of -steps after the device has finished its initialization of the chipset -and interrupts, though interrupts should not be enabled at that point. +entry point. +It is recommended that the driver perform this sequence of steps after the +device has finished its initialization of the chipset and interrupts, though +interrupts should not be enabled at that point. After it calls .Xr mac_register 9F it will start receiving callbacks from the MAC framework. @@ -142,23 +149,26 @@ as the argument to .Xr mac_alloc 9F . Upon successful completion, the driver will receive a .Sy mac_register_t -structure which it should fill in. The structure and its members are -documented in +structure which it should fill in. +The structure and its members are documented in .Xr mac_register 9S . .Pp The .Xr mac_callbacks 9S structure is not allocated as a part of the .Xr mac_register 9S -structure. In general, device drivers declare this statically. See the +structure. +In general, device drivers declare this statically. +See the .Sx MAC Callbacks section for more information on how to fill it out. .Pp Once the structure has been filled in, the driver should call .Xr mac_register 9F -to register itself with MAC. The handle that it uses to register with -should be part of the driver's soft state. It will be used in various -other support functions and callbacks. +to register itself with MAC. +The handle that it uses to register with should be part of the driver's soft +state. +It will be used in various other support functions and callbacks. .Pp If the call is successful, then the device driver should enable interrupts and finish any other initialization required. @@ -171,25 +181,28 @@ from its routine. .Ss MAC Callbacks The MAC framework interacts with a device driver through a series of -callbacks. These callbacks are described in their individual manual -pages and the collection of callbacks is indicated in the +callbacks. +These callbacks are described in their individual manual pages and the +collection of callbacks is indicated in the .Xr mac_callbacks 9S -manual page. This section does not focus on the specific functions, but -rather on interactions between them and the rest of the device driver -framework. +manual page. +This section does not focus on the specific functions, but rather on +interactions between them and the rest of the device driver framework. .Pp A device driver should make no assumptions about when the various callbacks will be called and whether or not they will be called -simultaneously. For example, a device driver may be asked to -transmit data through a call to its +simultaneously. +For example, a device driver may be asked to transmit data through a call to its .Xr mc_tx 9F entry point while it is being asked to get a device property through a call to its .Xr mc_getprop 9F -entry point. As such, while some calls may be serialized to the device, -such as setting properties, the device driver should always presume that -all of its data needs to be protected with locks. While the device is -holding locks, it is safe for it call the following MAC routines: +entry point. +As such, while some calls may be serialized to the device, such as setting +properties, the device driver should always presume that all of its data needs +to be protected with locks. +While the device is holding locks, it is safe for it call the following MAC +routines: .Bl -bullet -offset indent -compact .It .Xr mac_hcksum_get 9F @@ -226,23 +239,28 @@ while locks are held or in interrupt context, though it is generally legal to do so. .Ss Receiving Data A device driver will often receive data through the means of an -interrupt. When that interrupt occurs, the device driver will receive -one or more frames with optional metadata. Often each frame has a -corresponding descriptor which has information about whether or not -there were errors or whether or not the device successfully checksummed -the packet. +interrupt. +When that interrupt occurs, the device driver will receive one or more frames +with optional metadata. +Often each frame has a corresponding descriptor which has information about +whether or not there were errors or whether or not the device successfully +checksummed the packet. .Pp During a single interrupt, a device driver should process a fixed number -of frames. For each frame the device driver should: +of frames. +For each frame the device driver should: .Bl -enum -offset indent .It -First check whether or not the frame has errors. If errors were -detected, then the frame should not be sent to the operating system. It -is recommended that devices keep kstats (see +First check whether or not the frame has errors. +If errors were detected, then the frame should not be sent to the operating +system. +It is recommended that devices keep kstats (see .Xr kstat_create 9S for more information) and bump the counter whenever such an error is -detected. If the device distinguishes between the types of errors, then -separate kstats for each class of error are recommended. See the +detected. +If the device distinguishes between the types of errors, then separate kstats +for each class of error are recommended. +See the .Sx STATISTICS section for more information on the various error cases that should be considered. @@ -264,17 +282,19 @@ It should then append this new message block to the .Em end of the message block chain, linking it to the .Sy b_next -pointer. It is vitally important that all the frames be chained in the -order that they were received. If the device driver mistakenly reorders -frames, then it may cause performance impacts in the TCP stack and -potentially impact application correctness. +pointer. +It is vitally important that all the frames be chained in the order that they +were received. +If the device driver mistakenly reorders frames, then it may cause performance +impacts in the TCP stack and potentially impact application correctness. .El .Pp Once all the frames have been processed and assembled, the device driver should deliver them to the rest of the operating system by calling .Xr mac_rx 9F . The device driver should try to give as many mblk_t structures to the -system at once. It +system at once. +It .Em should not call .Xr mac_rx 9F @@ -287,8 +307,8 @@ networking stack and some replies may be generated and given to the driver to send out. .Pp It is not the device driver's responsibility to determine whether or not -the system can keep up with a driver's delivery rate of frames. The rest -of the networking stack will handle issues related to keeping up +the system can keep up with a driver's delivery rate of frames. +The rest of the networking stack will handle issues related to keeping up appropriately and ensure that kernel memory is not exhausted by packets that are not being processed. .Pp @@ -299,11 +319,11 @@ can be received. A device driver will be asked to transmit a message block chain by having it's .Xr mc_tx 9E -entry point called. While the driver is processing the message blocks, -it may run out of resources. For example, a transmit descriptor ring may -become full. At that point, the device driver should return the -remaining unprocessed frames. The act of returning frames indicates that -the device has asserted flow control. +entry point called. +While the driver is processing the message blocks, it may run out of resources. +For example, a transmit descriptor ring may become full. +At that point, the device driver should return the remaining unprocessed frames. +The act of returning frames indicates that the device has asserted flow control. Once this has been done, no additional calls will be made to the driver's transmit entry point and the back pressure will be propagated throughout the rest of the networking stack. @@ -311,46 +331,52 @@ throughout the rest of the networking stack. At some point in the future when resources have become available again, for example after an interrupt indicating that some portion of the transmit ring has been sent, then the device driver must notify the -system that it can continue transmission. To do this, the -driver should call +system that it can continue transmission. +To do this, the driver should call .Xr mac_tx_update 9F . After that point, the driver will receive calls to its .Xr mc_tx 9E -entry point again. As mentioned in the section on callbacks, the device -driver should avoid holding any particular locks across the call to +entry point again. +As mentioned in the section on callbacks, the device driver should avoid holding +any particular locks across the call to .Xr mac_tx_update 9F . .Ss Interrupt Coalescing For devices operating at higher data rates, interrupt coalescing is an important part of a well functioning device and may impact the -performance of the device. Not all devices support interrupt -coalescing. If interrupt coalescing is supported on the device, it is -recommended that device driver writers provide private properties for -their device to control the interrupt coalescing rate. This will make it -much easier to perform experiments and observe the impact of different -interrupt rates on the rest of the system. +performance of the device. +Not all devices support interrupt coalescing. +If interrupt coalescing is supported on the device, it is recommended that +device driver writers provide private properties for their device to control the +interrupt coalescing rate. +This will make it much easier to perform experiments and observe the impact of +different interrupt rates on the rest of the system. .Ss MAC Address Filter Management The MAC framework will attempt to use as many MAC address filters as a -device has. To program a multicast address filter, the driver's +device has. +To program a multicast address filter, the driver's .Xr mc_multicst 9E -entry point will be called. If the device driver runs out of filters, it -should not take any special action and just return the appropriate error -as documented in the corresponding manual pages for the entry points. +entry point will be called. +If the device driver runs out of filters, it should not take any special action +and just return the appropriate error as documented in the corresponding manual +pages for the entry points. The framework will ensure that the device is placed in promiscuous mode if it needs to. .Ss Link Updates It is the responsibility of the device driver to keep track of the -data link's state. Many devices provide a means of receiving an -interrupt when the state of the link changes. When such a change -happens, the driver should update its internal data structures and then -call +data link's state. +Many devices provide a means of receiving an interrupt when the state of the +link changes. +When such a change happens, the driver should update its internal data +structures and then call .Xr mac_link_update 9F -to inform the MAC layer that this has occurred. If the device driver -does not properly inform the system about link changes, then various -features like link aggregations and other mechanisms that leverage the -link state will not work correctly. +to inform the MAC layer that this has occurred. +If the device driver does not properly inform the system about link changes, +then various features like link aggregations and other mechanisms that leverage +the link state will not work correctly. .Ss Link Speed and Auto-negotiation Many networking devices support more than one possible speed that they -can operate at. The selection of a speed is often performed through +can operate at. +The selection of a speed is often performed through .Em auto-negotiation , though some devices allow the user to control what speeds are advertised and used. @@ -372,35 +398,41 @@ A user can control what speeds a device advertises via auto-negotiation and whether or not it performs auto-negotiation at all by using a series of properties that have .Sy _EN_ -in the name. These are read/write properties and there is one for each -speed supported in the operating system. For a full list of them, see -the +in the name. +These are read/write properties and there is one for each speed supported in the +operating system. +For a full list of them, see the .Sx PROPERTIES section. .Pp In addition to these properties, there is a corresponding set of properties with .Sy _ADV_ -in the name. These are similar to the +in the name. +These are similar to the .Sy _EN_ family of properties, but they are read-only and indicate what the -device has actually negotiated. While they are generally similar to the +device has actually negotiated. +While they are generally similar to the .Sy _EN_ -family of properties, they may change depending on power settings. See -the +family of properties, they may change depending on power settings. +See the .Sy Ethernet Link Properties section in .Xr dladm 1M for more information. .Pp It's worth discussing how these different values get used throughout the -different entry points. The first entry point to consider is the +different entry points. +The first entry point to consider is the .Xr mc_propinfo 9E -entry point. For a given speed, the driver should consult whether or not -the hardware supports this speed. If it does, it should fill in the -default value that the hardware takes and whether or not the property is -writable. The properties should also be updated to indicate whether or -not it is writable. This holds for both the +entry point. +For a given speed, the driver should consult whether or not the hardware +supports this speed. +If it does, it should fill in the default value that the hardware takes and +whether or not the property is writable. +The properties should also be updated to indicate whether or not it is writable. +This holds for both the .Sy _EN_ and .Sy _ADV_ @@ -409,15 +441,18 @@ family of properties. The next entry point is .Xr mc_getprop 9E . Here, the device should first consult whether the given speed is -supported. If it is not, then the driver should return +supported. +If it is not, then the driver should return .Er ENOTSUP . If it does, then it should return the current value of the property. .Pp The last property endpoint is the .Xr mc_setprop 9E -entry point. Here, the same logic applies. Before the driver considers -whether or not the property is writable, it should first check whether -or not it's a supported property. If it's not, then it should return +entry point. +Here, the same logic applies. +Before the driver considers whether or not the property is writable, it should +first check whether or not it's a supported property. +If it's not, then it should return .Er ENOTSUP . Otherwise, it should proceed to check whether the property is writable, and if it is and a valid value, then it should update the property and @@ -425,19 +460,22 @@ restart the link's negotiation. .Pp Finally, there is the .Xr mc_getstat 9E -entry point. Several of the statistics that are queried relate to -auto-negotiation and hardware capabilities. When a statistic relates to -the hardware supporting a given speed, the +entry point. +Several of the statistics that are queried relate to auto-negotiation and +hardware capabilities. +When a statistic relates to the hardware supporting a given speed, the .Sy _EN_ -properties should be ignored. The only thing that should be consulted is -what the hardware itself supports. Otherwise, the statistics should look -at what is currently being advertised by the device. +properties should be ignored. +The only thing that should be consulted is what the hardware itself supports. +Otherwise, the statistics should look at what is currently being advertised by +the device. .Ss Unregistering from MAC During a driver's .Xr detach 9E routine, it should unregister the device instance from MAC by calling .Xr mac_unregister 9F -on the handle that it originally called it on. If the call to +on the handle that it originally called it on. +If the call to .Xr mac_unregister 9F failed, then the device is likely still in use and the driver should fail the call to @@ -445,8 +483,8 @@ fail the call to .Ss Interacting with Devices Administrators always interact with devices through the .Xr dladm 1M -command line interface. The state of devices such as whether the link is -considered +command line interface. +The state of devices such as whether the link is considered .Sy up or .Sy down , @@ -457,8 +495,8 @@ state, and .Sy flow control state, -are all exposed. It is also the preferred way that these properties are -set and configured. +are all exposed. +It is also the preferred way that these properties are set and configured. .Pp While device tunables may be presented in a .Xr driver.conf 4 @@ -468,26 +506,27 @@ private properties, whether explicitly documented or not. .Sh CAPABILITIES Capabilities in the MAC Framework are optional features that a device supports which indicate various hardware features that the device -supports. The two current capabilities that the system supports are -related to being able to hardware perform large send offloads (LSO), -often also known as TCP segmentation and the ability for hardware to -calculate and verify the checksums present in IPv4, IPV6, and protocol -headers such as TCP and UDP. +supports. +The two current capabilities that the system supports are related to being able +to hardware perform large send offloads (LSO), often also known as TCP +segmentation and the ability for hardware to calculate and verify the checksums +present in IPv4, IPV6, and protocol headers such as TCP and UDP. .Pp The MAC framework will query a device for support of a capability through the .Xr mc_getcapab 9E -function. Each capability has its own constant and may have -corresponding data that goes along with it and a specific structure that -the device is required to fill in. Note, the set of capabilities changes -over time and there are also private capabilities in the system. Several -of the capabilities are used in the implementation of the MAC framework. +function. +Each capability has its own constant and may have corresponding data that goes +along with it and a specific structure that the device is required to fill in. +Note, the set of capabilities changes over time and there are also private +capabilities in the system. +Several of the capabilities are used in the implementation of the MAC framework. Others, like .Sy MAC_CAPAB_RINGS , -represent feature that have not been stabilized and thus both API and -binary compatibility for them is not guaranteed. It is important that -the device driver handles unknown capabilities correctly. For more -information, see +represent feature that have not been stabilized and thus both API and binary +compatibility for them is not guaranteed. +It is important that the device driver handles unknown capabilities correctly. +For more information, see .Xr mc_getcapab 9E . .Pp The following capabilities are @@ -496,33 +535,35 @@ stable and defined in the system: The .Sy MAC_CAPAB_HCKSUM capability indicates to the system that the device driver supports some -amount of checksumming. The specific data for this capability is a -pointer to a +amount of checksumming. +The specific data for this capability is a pointer to a .Sy uint32_t . To indicate no support for any kind of checksumming, the driver should either set this value to zero or simply return that it doesn't support the capability. .Pp Note, the values that the driver declares in this capability indicate -what it can do when it transmits data. If the driver can only -verify checksums when receiving data, then it should not indicate that -it supports this capability. The following set of flags may be combined -through a bitwise inclusive OR: +what it can do when it transmits data. +If the driver can only verify checksums when receiving data, then it should not +indicate that it supports this capability. +The following set of flags may be combined through a bitwise inclusive OR: .Bl -tag -width Ds .It Sy HCKSUM_INET_PARTIAL This indicates that the hardware can calculate a partial checksum for both IPv4 and IPv6; however, it requires the pseudo-header checksum be -calculated for it. The pseudo-header checksum will be available for the -mblk_t when calling +calculated for it. +The pseudo-header checksum will be available for the mblk_t when calling .Xr mac_hcksum_get 9F . Note this does not imply that the hardware is capable of calculating the -IPv4 header checksum. That should be indicated with the +IPv4 header checksum. +That should be indicated with the .Sy HCKSUM_IPHDRCKSUM flag. .It Sy HCKSUM_INET_FULL_V4 This indicates that the hardware will fully calculate the L4 checksum for outgoing IPv4 packets and does not require a pseudo-header checksum. Note this does not imply that the hardware is capable of calculating the -IPv4 header checksum. That should be indicated with the +IPv4 header checksum. +That should be indicated with the .Sy HCKSUM_IPHDRCKSUM . .It Sy HCKSUM_INET_FULL_V6 This indicates that the hardware will fully calculate the L4 checksum @@ -533,34 +574,38 @@ the IPv4 header itself. .El .Pp When in a driver's transmit function, the driver will be processing a -single frame. It should call +single frame. +It should call .Xr mac_hcksum_get 9F -to see what checksum flags are set on it. Note that the flags that are -set on it are different from the ones described above and are documented -in its manual page. These flags indicate how the driver is expected to -program the hardware and what checksumming is required. Not all frames -will require hardware checksumming or will ask the hardware to checksum -it. +to see what checksum flags are set on it. +Note that the flags that are set on it are different from the ones described +above and are documented in its manual page. +These flags indicate how the driver is expected to program the hardware and what +checksumming is required. +Not all frames will require hardware checksumming or will ask the hardware to +checksum it. .Pp If a driver supports offloading the receive checksum and verification, -it should check to see what the hardware indicated was verified. The -driver should then call +it should check to see what the hardware indicated was verified. +The driver should then call .Xr mac_hcksum_set 9F . The flags used are different from the ones above and are discussed in detail in the .Xr mac_hcksum_set 9F -manual page. If there is no checksum information available or the driver -does not support checksumming, then it should simply not call +manual page. +If there is no checksum information available or the driver does not support +checksumming, then it should simply not call .Xr mac_hcksum_set 9F . .Pp Note that the checksum flags should be set on the first -mblk_t that makes up a given message. In other words, if multiple -mblk_t structures are linked together by the +mblk_t that makes up a given message. +In other words, if multiple mblk_t structures are linked together by the .Sy b_cont member to describe a single frame, then it should only be called on the -first mblk_t of that set. However, each distinct message should have the -checksum bits set on it, if applicable. In other words, each mblk_t that -is linked together by the +first mblk_t of that set. +However, each distinct message should have the checksum bits set on it, if +applicable. +In other words, each mblk_t that is linked together by the .Sy b_next pointer may have checksum flags set. .Pp @@ -568,8 +613,9 @@ It is recommended that device drivers provide a private property or .Xr driver.conf 4 property to control whether or not checksumming is enabled for both rx and tx; however, the default disposition is recommended to be enabled -for both. This way if hardware bugs are found in the checksumming -implementation, they can be disabled without requiring software updates. +for both. +This way if hardware bugs are found in the checksumming implementation, they can +be disabled without requiring software updates. The transmit property should be checked when determining how to reply to .Xr mc_getcapab 9E and the receive property should be checked in the context of the receive @@ -578,9 +624,11 @@ function. The .Sy MAC_CAPAB_LSO capability indicates that the driver supports various forms of large -send offload (LSO). The private data is a pointer to a +send offload (LSO). +The private data is a pointer to a .Sy mac_capab_lso_t -structure. At the moment, LSO support is limited to TCP inside of IPv4. +structure. +At the moment, LSO support is limited to TCP inside of IPv4. This structure has the following members which are used to indicate various types of LSO support. .Bd -literal -offset indent @@ -591,12 +639,14 @@ lso_basic_tcp_ivr4_t lso_basic_tcp_ipv4; The .Sy lso_flags member is used to indicate which members are valid and should be -considered. Each flag represents a different form of LSO. The member -should be set to the bitwise inclusive OR of the following values: +considered. +Each flag represents a different form of LSO. +The member should be set to the bitwise inclusive OR of the following values: .Bl -tag -width Dv -offset indent .It Sy LSO_TX_BASIC_TCP_IPV4 This indicates hardware support for performing TCP segmentation -offloading over IPv4. When this flag is set, the +offloading over IPv4. +When this flag is set, the .Sy lso_basic_tcp_ipv4 member must be filled in. .El @@ -619,31 +669,37 @@ means for disabling the support of LSO even if it is enabled by default. This deals with the case where issues that pop up for LSO may be worked around without requiring additional driver work. .Sh PROPERTIES -Properties in the MAC framework represent aspects of a link. These -include things like the link's current state and MTU. Many of the -properties in the system are focused around auto-negotiation and -controlling what link speeds are advertised. Information about -properties is covered by three different device entry points. The +Properties in the MAC framework represent aspects of a link. +These include things like the link's current state and MTU. +Many of the properties in the system are focused around auto-negotiation and +controlling what link speeds are advertised. +Information about properties is covered by three different device entry points. +The .Xr mc_propinfo 9E -entry point obtains metadata about the property. The +entry point obtains metadata about the property. +The .Xr mc_getprop 9E -entry point obtains the property. The +entry point obtains the property. +The .Xr mc_setprop 9E entry point updates the property to a new value. .Pp -Many of the properties listed below are read-only. Each property -indicates whether it's read-only or it's read/write. However, driver -writers may not implement the ability to set all writable properties. -Many of these depend on the card itself. In particular, all properties -that relate to auto-negotiation and are read/write may not be updated -if the hardware in question does not support toggling what link speeds -are auto-negotiated. While copper Ethernet often does not have this -restriction, it often exists with various fiber standards and phys. +Many of the properties listed below are read-only. +Each property indicates whether it's read-only or it's read/write. +However, driver writers may not implement the ability to set all writable +properties. +Many of these depend on the card itself. +In particular, all properties that relate to auto-negotiation and are read/write +may not be updated if the hardware in question does not support toggling what +link speeds are auto-negotiated. +While copper Ethernet often does not have this restriction, it often exists with +various fiber standards and phys. .Pp The following properties are the subset of MAC framework properties that -driver writers should be aware of and handle. While other properties -exist in the system, driver writers should always return an error when a -property not listed below is encountered. See +driver writers should be aware of and handle. +While other properties exist in the system, driver writers should always return +an error when a property not listed below is encountered. +See .Xr mc_getprop 9E and .Xr mc_setprop 9E @@ -659,20 +715,22 @@ Permissions: .Pp The .Sy MAC_PROP_DUPLEX -property is used to indicate whether or not the link is duplex. A duplex -link may have traffic flowing in both directions at the same time. The +property is used to indicate whether or not the link is duplex. +A duplex link may have traffic flowing in both directions at the same time. +The .Sy link_duplex_t is an enumeration which may be set to any of the following values: .Bl -tag -width Ds .It Sy LINK_DUPLEX_UNKNOWN -The current state of the link is unknown. This may be because the link -has not negotiated to a specific speed or it is down. +The current state of the link is unknown. +This may be because the link has not negotiated to a specific speed or it is +down. .It Sy LINK_DUPLEX_HALF -The link is running at half duplex. Communication may travel in only one -direction on the link at a given time. +The link is running at half duplex. +Communication may travel in only one direction on the link at a given time. .It Sy LINK_DUPLEX_FULL -The link is running at full duplex. Communication may travel in both -directions on the link simultaneously. +The link is running at full duplex. +Communication may travel in both directions on the link simultaneously. .El .It Sy MAC_PROP_SPEED .Bd -filled -compact @@ -684,9 +742,9 @@ Permissions: .Pp The .Sy MAC_PROP_SPEED -property stores the current link speed in bits per second. A link -that is running at 100 MBit/s would store the value 100000000ULL. A link -that is running at 40 Gbit/s would store the value 40000000000ULL. +property stores the current link speed in bits per second. +A link that is running at 100 MBit/s would store the value 100000000ULL. +A link that is running at 40 Gbit/s would store the value 40000000000ULL. .It Sy MAC_PROP_STATUS .Bd -filled -compact Type: @@ -697,21 +755,24 @@ Permissions: .Pp The .Sy MAC_PROP_STATUS -property is used to indicate the current state of the link. It indicates -whether the link is up or down. The +property is used to indicate the current state of the link. +It indicates whether the link is up or down. +The .Sy link_state_t is an enumeration which may be set to any of the following values: .Bl -tag -width Ds .It Sy LINK_STATE_UNKNOWN -The current state of the link is unknown. This may be because the -driver's +The current state of the link is unknown. +This may be because the driver's .Xr mc_start 9E endpoint has not been called so it has not attempted to start the link. .It Sy LINK_STATE_DOWN -The link is down. This may be because of a negotiation problem, a cable -problem, or some other device specific issue. +The link is down. +This may be because of a negotiation problem, a cable problem, or some other +device specific issue. .It Sy LINK_STATE_UP -The link is up. If auto-negotiation is in use, it should have completed. +The link is up. +If auto-negotiation is in use, it should have completed. Traffic should be able to flow over the link, barring other issues. .El .It Sy MAC_PROP_AUTONEG @@ -725,17 +786,20 @@ Permissions: The .Sy MAC_PROP_AUTONEG property indicates whether or not the device is currently configured to -perform auto-negotiation. A value of +perform auto-negotiation. +A value of .Sy 0 -indicates that auto-negotiation is disabled. A +indicates that auto-negotiation is disabled. +A .Sy non-zero -value indicates that auto-negotiation is enabled. Devices should -generally default to enabling auto-negotiation. +value indicates that auto-negotiation is enabled. +Devices should generally default to enabling auto-negotiation. .Pp When getting this property, the device driver should return the current -state. When setting this property, if the device supports operating in -the requested mode, then the device driver should reset the link to -negotiate to the new speed after updating any internal registers. +state. +When setting this property, if the device supports operating in the requested +mode, then the device driver should reset the link to negotiate to the new speed +after updating any internal registers. .It Sy MAC_PROP_MTU .Bd -filled -compact Type: @@ -746,24 +810,25 @@ Permissions: .Pp The .Sy MAC_PROP_MTU -property determines the maximum transmission unit (MTU). This indicates -the maximum size packet that the device can transmit, ignoring its own -headers. For an Ethernet device, this would exclude the size of the -Ethernet header and any VLAN headers that would be placed. It is up to -the driver to ensure that any MTU values that it accepts when adding in -its margin and header sizes does not exceed its maximum frame size. +property determines the maximum transmission unit (MTU). +This indicates the maximum size packet that the device can transmit, ignoring +its own headers. +For an Ethernet device, this would exclude the size of the Ethernet header and +any VLAN headers that would be placed. +It is up to the driver to ensure that any MTU values that it accepts when adding +in its margin and header sizes does not exceed its maximum frame size. .Pp By default, drivers for Ethernet should initialize this value and the MTU to .Sy 1500 . When getting this property, the driver should return its current -recorded MTU. When setting this property, the driver should first -validate that it is within the device's valid range and then it must -call +recorded MTU. +When setting this property, the driver should first validate that it is within +the device's valid range and then it must call .Xr mac_maxsdu_update 9F . -Note that the call may fail. If the call completes successfully, the -driver should update the hardware with the new value of the MTU and -perform any other work needed to handle it. +Note that the call may fail. +If the call completes successfully, the driver should update the hardware with +the new value of the MTU and perform any other work needed to handle it. .Pp If the device does not support changing the MTU after the device's .Xr mc_start 9E @@ -780,15 +845,17 @@ Permissions: The .Sy MAC_PROP_FLOWCTRL property manages the configuration of pause frames as part of Ethernet -flow control. Note, this only describes what this device will advertise. +flow control. +Note, this only describes what this device will advertise. What is actually enabled may be different and is subject to the rules of -auto-negotiation. The +auto-negotiation. +The .Sy link_flowctrl_t is an enumeration that may be set to one of the following values: .Bl -tag -width Ds .It Sy LINK_FLOWCTRL_NONE -Flow control is disabled. No pause frames should be generated or -honored. +Flow control is disabled. +No pause frames should be generated or honored. .It Sy LINK_FLOWCTRL_RX The device can receive pause frames; however, it should not generate them. @@ -801,27 +868,33 @@ The device supports both sending and receiving pause frames. .Pp When getting this property, the device driver should return the way that it has configured the device, not what the device has actually -negotiated. When setting the property, it should update the hardware and -allow the link to potentially perform auto-negotiation again. +negotiated. +When setting the property, it should update the hardware and allow the link to +potentially perform auto-negotiation again. .El .Pp The remaining properties are all about various auto-negotiation link -speeds. They fall into two different buckets: properties with +speeds. +They fall into two different buckets: properties with .Sy _ADV_ in the name and properties with .Sy _EN_ -in the name. For any given supported speed, there is one of each. The +in the name. +For any given supported speed, there is one of each. +The .Sy _EN_ set of properties are read/write properties that control what should be -advertised by the device. When these are retrieved, they should return -the current value of the property. When they are set, they should change -how the hardware advertises the specific speed and trigger any kind of -link reset and auto-negotiation, if enabled, to occur. +advertised by the device. +When these are retrieved, they should return the current value of the property. +When they are set, they should change how the hardware advertises the specific +speed and trigger any kind of link reset and auto-negotiation, if enabled, to +occur. .Pp The .Sy _ADV_ -set of properties are read-only properties. They are meant to reflect -what has actually been negotiated. These may be different from the +set of properties are read-only properties. +They are meant to reflect what has actually been negotiated. +These may be different from the .Sy _EN_ family of properties, especially when different power management settings are at play. @@ -1125,23 +1198,24 @@ enabled. .El .Ss Private Properties In addition to the defined properties above, drivers are allowed to -define private properties. These private properties are device-specific -properties. All private properties share the same constant, +define private properties. +These private properties are device-specific properties. +All private properties share the same constant, .Sy MAC_PROP_PRIVATE . -Properties are distinguished by a name, which is a character string. The -list of such private properties is defined when registering with mac in -the +Properties are distinguished by a name, which is a character string. +The list of such private properties is defined when registering with mac in the .Sy m_priv_props member of the .Xr mac_register 9S structure. .Pp The driver may define whatever semantics it wants for these private -properties. They will not be listed when running +properties. +They will not be listed when running .Xr dladm 1M , -unless explicitly requested by name. All such properties should start -with a leading underscore character and then consist of alphanumeric -ASCII characters and additional underscores or hyphens. +unless explicitly requested by name. +All such properties should start with a leading underscore character and then +consist of alphanumeric ASCII characters and additional underscores or hyphens. .Pp Properties of type .Sy MAC_PROP_PRIVATE @@ -1157,13 +1231,15 @@ When encountering properties that it doesn't know, it should treat them like all other unknown properties. .Sh STATISTICS The MAC framework defines a couple different sets of statistics which -are based on various standards for devices to implement. Statistics are -retrieved through the +are based on various standards for devices to implement. +Statistics are retrieved through the .Xr mc_getstat 9E -entry point. There are both statistics that are required for all devices -and then there is a separate set of Ethernet specific statistics. Not -all devices will support every statistic. In many cases, several device -registers will need to be combined to create the proper stat. +entry point. +There are both statistics that are required for all devices and then there is a +separate set of Ethernet specific statistics. +Not all devices will support every statistic. +In many cases, several device registers will need to be combined to create the +proper stat. .Pp In general, if the device is not keeping track of these statistics, then it is recommended that the driver store these values as a @@ -1171,8 +1247,9 @@ it is recommended that the driver store these values as a to ensure that overflow does not occur. .Pp If a device does not support a specific statistic, then it is fine to -return that it is not supported. The same should be used for -unrecognized statistics. See +return that it is not supported. +The same should be used for unrecognized statistics. +See .Xr mc_getstat 9E for more information on the proper way to handle these. .Ss General Device Statistics @@ -1228,9 +1305,9 @@ The total number of packets that were larger than the maximum sized packet for the device and were therefore dropped. .El .Ss Ethernet Specific Statistics -The following statistics are specific to Ethernet devices. They refer to -values from RFC 1643 and include various MII/GMII specific stats. Many -of these are also defined in IEEE 802.3. +The following statistics are specific to Ethernet devices. +They refer to values from RFC 1643 and include various MII/GMII specific stats. +Many of these are also defined in IEEE 802.3. .Bl -tag -width Ds .It Sy ETHER_STAT_ADV_CAP_1000FDX Indicates that the device is advertising support for 1 Gbit/s @@ -1281,8 +1358,9 @@ Indicates that the device is advertising support for detecting faults in the remote link peer. .It Sy ETHER_STAT_ALIGN_ERRORS Indicates the number of times an alignment error was generated by the -Ethernet device. This is a count of packets that were not an integral -number of octets and failed the FCS check. +Ethernet device. +This is a count of packets that were not an integral number of octets and failed +the FCS check. .It Sy ETHER_STAT_CAP_1000FDX Indicates the device supports 1 Gbit/s full-duplex operation. .It Sy ETHER_STAT_CAP_1000HDX @@ -1341,8 +1419,8 @@ frames. Indicates whether the current link state is a result of auto-negotiation. .It Sy ETHER_STAT_LINK_DUPLEX -Indicates the current duplex state of the link. The values used here -should be the same as documented for +Indicates the current duplex state of the link. +The values used here should be the same as documented for .Sy MAC_PROP_DUPLEX . .It Sy ETHER_STAT_LINK_PAUSE Indicates whether the link is currently configured to generate pause @@ -1393,8 +1471,8 @@ error when attempting to process and transmit a frame. Indicates the number of times that a frame was eventually transmitted successfully, but only after more than one collision. .It Sy ETHER_STAT_SQE_ERRORS -Indicates the number of times that an SQE error occurred. The specific -conditions for this error are documented in IEEE 802.3. +Indicates the number of times that an SQE error occurred. +The specific conditions for this error are documented in IEEE 802.3. .It Sy ETHER_STAT_TOOLONG_ERRORS Indicates the number of frames that were received that were longer than the maximum frame size supported by the device. @@ -1409,8 +1487,8 @@ Indicates the address of the MII/GMII receiver address. .It Sy ETHER_STAT_XCVR_ID Indicates the id of the MII/GMII receiver address. .It Sy ETHER_STAT_XCVR_INUSE -Indicates what kind of receiver is in use. The following values may be -used: +Indicates what kind of receiver is in use. +The following values may be used: .Bl -tag -width Ds .It Sy XCVR_UNDEFINED The receiver type is undefined by the hardware. @@ -1425,11 +1503,11 @@ The receiver supports 100BASE-TX operation. .It Sy XCVR_100T2 The receiver supports 100BASE-T2 operation. .It Sy XCVR_1000X -The receiver supports 1000BASE-X operation. This is used for all fiber -receivers. +The receiver supports 1000BASE-X operation. +This is used for all fiber receivers. .It Sy XCVR_1000T -The receiver supports 1000BASE-T operation. This is used for all copper -receivers. +The receiver supports 1000BASE-T operation. +This is used for all copper receivers. .El .El .Ss Device Specific kstats @@ -1440,12 +1518,12 @@ statistics, it should create its own kstats through the function to allow operators to observe them. .Sh TX STALL DETECTION, DEVICE RESETS, AND FAULT MANAGEMENT Device drivers are the first line of defense for dealing with broken -devices and bugs in their firmware. While most devices will rarely fail, -it is important that when designing and implementing the device driver -that particular attention is paid in the design with respect to RAS -(Reliability, Availability, and Serviceability). While everything -described in this section is optional, it is highly recommended that -all new device drivers follow these guidelines. +devices and bugs in their firmware. +While most devices will rarely fail, it is important that when designing and +implementing the device driver that particular attention is paid in the design +with respect to RAS (Reliability, Availability, and Serviceability). +While everything described in this section is optional, it is highly recommended +that all new device drivers follow these guidelines. .Pp The Fault Management Architecture (FMA) provides facilities for detecting and reporting various classes of defects and faults. @@ -1483,10 +1561,12 @@ calling .Xr ddi_fm_init 9F from their .Xr attach 9E -routine. By registering with the fault management framework, a device -driver is given the chance to detect and notice transport errors as well -as report other errors that exist. While a device driver does not need to -indicate that it is capable of all such capabilities described in +routine. +By registering with the fault management framework, a device driver is given the +chance to detect and notice transport errors as well as report other errors that +exist. +While a device driver does not need to indicate that it is capable of all such +capabilities described in .Xr ddi_fm_init 9F , we suggest that device drivers at least register the .Sy DDI_FM_EREPORT_CAPABLE @@ -1500,14 +1580,15 @@ during its .Xr detach 9E entry point. .Ss Transport Errors -Many modern networking devices leverage PCI or PCI Express. As such, -there are two primary ways that device drivers access data: they either +Many modern networking devices leverage PCI or PCI Express. +As such, there are two primary ways that device drivers access data: they either memory map device registers and use routines like .Xr ddi_get8 9F and .Xr ddi_put8 9F -or they use direct memory access (DMA). New device drivers should always -enable checking of the transport layer by marking their support in the +or they use direct memory access (DMA). +New device drivers should always enable checking of the transport layer by +marking their support in the .Xr ddi_device_acc_attr_t 9S structure and using routines like .Xr ddi_fm_acc_err_get 9F @@ -1516,62 +1597,66 @@ and to detect if errors have occurred. .Ss Device Indicated Errors Many devices have capabilities to announce to a device driver that a -fatal correctable error or uncorrectable error has occurred. Other -devices have the ability to indicate that various physical issues have +fatal correctable error or uncorrectable error has occurred. +Other devices have the ability to indicate that various physical issues have occurred such as a fan failing or a temperature sensor having fired. .Pp Drivers should wire themselves to receive notifications when these -events occur. The means and capabilities will vary from device to -device. For example, some devices will generate information about these -notifications through special interrupts. Other devices may have a -register that software can poll. In the cases where polling is required, -driver writers should try not to poll too frequently and should -generally only poll when the device is actively being used, e.g. between -calls to the +events occur. +The means and capabilities will vary from device to device. +For example, some devices will generate information about these notifications +through special interrupts. +Other devices may have a register that software can poll. +In the cases where polling is required, driver writers should try not to poll +too frequently and should generally only poll when the device is actively being +used, e.g. between calls to the .Xr mc_start 9E and .Xr mc_stop 9E entry points. .Ss Driver Transmit Stall Detection One of the primary responsibilities of a hardened device driver is to -perform transmit stall detection. The core idea behind tx stall -detection is that the driver should record when it's getting activity -related to when data has been successfully transmitted. Most devices -should be transmitting data on a regular basis as long as the link is -up. If it is not, then this may indicate that the device is stuck and -needs to be reset. At this time, the MAC framework does not provide any -resources for performing these checks; however, polling on each -individual transmit ring for the last completion time while something is -actively being transmitted through the use of routines such as +perform transmit stall detection. +The core idea behind tx stall detection is that the driver should record when +it's getting activity related to when data has been successfully transmitted. +Most devices should be transmitting data on a regular basis as long as the link +is up. +If it is not, then this may indicate that the device is stuck and needs to be +reset. +At this time, the MAC framework does not provide any resources for performing +these checks; however, polling on each individual transmit ring for the last +completion time while something is actively being transmitted through the use of +routines such as .Xr timeout 9F may be a reasonable starting point. .Ss Driver Command Timeout Detection -Each device is programmed in different ways. Some devices are programmed -through asynchronous commands while others are programmed by writing -directly to memory mapped registers. If a device receives asynchronous -replies to commands, then the device driver should set reasonable -timeouts for all such commands and plan on detecting them. If a timeout -occurs, the driver should presume that there is an issue with the +Each device is programmed in different ways. +Some devices are programmed through asynchronous commands while others are +programmed by writing directly to memory mapped registers. +If a device receives asynchronous replies to commands, then the device driver +should set reasonable timeouts for all such commands and plan on detecting them. +If a timeout occurs, the driver should presume that there is an issue with the hardware and proceed to abort the command or reset the device. .Pp -Many devices do not have such a communication mechanism. However, -whenever there is some activity where the device driver must wait, then +Many devices do not have such a communication mechanism. +However, whenever there is some activity where the device driver must wait, then it should be prepared for the fact that the device may never get back to it and react appropriately by performing some kind of device reset. .Ss Reacting to Errors When any of the above categories of errors has been triggered, the behavior that the device driver should take depends on the kind of -error. If a fatal error, for example, a transport error, a transmit -stall was detected, or the device indicated an uncorrectable error was -detected, then it is +error. +If a fatal error, for example, a transport error, a transmit stall was detected, +or the device indicated an uncorrectable error was detected, then it is important that the driver take the following steps: .Bl -enum -offset indent .It Set a flag in the device driver's state that indicates that it has hit -an error condition. When this error condition flag is asserted, -transmitted packets should be accepted and dropped and actions that would -require writing to the device state should fail with an error. This flag -should remain until the device has been successfully restarted. +an error condition. +When this error condition flag is asserted, transmitted packets should be +accepted and dropped and actions that would require writing to the device state +should fail with an error. +This flag should remain until the device has been successfully restarted. .It If the error was not a transport error that was indicated by the fault management architecture, e.g. a transport error that was detected, then @@ -1591,9 +1676,9 @@ At this point the device driver should issue a device reset through some device-specific means. .It When the device reset has been completed, then the device driver should -restore all of the programmed state to the device. This includes things -like the current MTU, advertised auto-negotiation speeds, MAC address -filters, and more. +restore all of the programmed state to the device. +This includes things like the current MTU, advertised auto-negotiation speeds, +MAC address filters, and more. .It Finally, when service has been restored, the device driver should call .Xr ddi_fm_service_impact 9F @@ -1610,27 +1695,29 @@ value depending on the nature of the problem that has occurred. .Pp Device drivers should never make the decision to remove a device from service based on errors that have occurred nor should they panic the -system. Rather, the device driver should always try to notify the -operating system with various ereports and allow its policy decisions to -occur. The decision to retire a device lies in the hands of the fault -management architecture. It knows more about the operator's intent and -the surrounding system's state than the device driver itself does and it -will make the call to offline and retire the device if it is required. +system. +Rather, the device driver should always try to notify the operating system with +various ereports and allow its policy decisions to occur. +The decision to retire a device lies in the hands of the fault management +architecture. +It knows more about the operator's intent and the surrounding system's state +than the device driver itself does and it will make the call to offline and +retire the device if it is required. .Ss Device Resets -When resetting a device, a device driver must exercise caution. If a -device driver has not been written to plan for a device reset, then it -may not correctly restore the device's state after such a reset. Such -state should be stored in the instance's private state data as the MAC +When resetting a device, a device driver must exercise caution. +If a device driver has not been written to plan for a device reset, then it +may not correctly restore the device's state after such a reset. +Such state should be stored in the instance's private state data as the MAC framework does not know about device resets and will not inform the device again about the expected, programmed state. .Pp One wrinkle with device resets is that many networking cards show up as multiple PCI functions on a single device, for example, each port may show up as a separate function and thus have a separate instance of the -device driver attached. When resetting a function, device driver writers -should carefully read the device programming manuals and verify whether -or not a reset impacts only the stalled function or if it impacts all -function across the device. +device driver attached. +When resetting a function, device driver writers should carefully read the +device programming manuals and verify whether or not a reset impacts only the +stalled function or if it impacts all function across the device. .Pp If the only way to reset a given function is through the device, then this may require more coordination and work on the part of the device @@ -1641,28 +1728,32 @@ occurring. .Sh MBLKS AND DMA The networking stack manages framed data through the use of the .Xr mblk 9S -structure. The mblk allows for a single message to be made up of -individual blocks. Each part is linked together through its +structure. +The mblk allows for a single message to be made up of individual blocks. +Each part is linked together through its .Sy b_cont -member. However, it also allows for multiple messages to be chained -together through the use of the +member. +However, it also allows for multiple messages to be chained together through the +use of the .Sy b_next -member. While the networking stack works with these structures, device -drivers generally work with DMA regions. There are two different -strategies that device drivers use for handling these two different -cases: copying and binding. +member. +While the networking stack works with these structures, device drivers generally +work with DMA regions. +There are two different strategies that device drivers use for handling these +two different cases: copying and binding. .Ss Copying Data The first way that device drivers handle interfacing between the two is -by having two separate regions of memory. One part is memory which has -been allocated for DMA through a call to +by having two separate regions of memory. +One part is memory which has been allocated for DMA through a call to .Xr ddi_dma_alloc 9F and the other is memory associated with the memory block. .Pp In this case, a driver will use .Xr bcopy 9F -to copy memory between the two distinct regions. When transmitting a -packet, it will copy the memory from the mblk_t to the DMA region. When -receiving memory, it will allocate a mblk_t through the +to copy memory between the two distinct regions. +When transmitting a packet, it will copy the memory from the mblk_t to the DMA +region. +When receiving memory, it will allocate a mblk_t through the .Xr allocb 9F routine, copy the memory across with .Xr bcopy 9F , @@ -1671,67 +1762,74 @@ and then increment the mblk_t's structure. .Pp If, when receiving, memory is not available for a new message block, -then the frame should be skipped and effectively dropped. A kstat should -be bumped when such an occasion occurs. +then the frame should be skipped and effectively dropped. +A kstat should be bumped when such an occasion occurs. .Ss Binding Data -An alternative approach to copying data is to use DMA binding. When -using DMA binding, the OS takes care of mapping between DMA memory and -normal device memory. The exact process is a bit different between -transmit and receive. +An alternative approach to copying data is to use DMA binding. +When using DMA binding, the OS takes care of mapping between DMA memory and +normal device memory. +The exact process is a bit different between transmit and receive. .Pp When transmitting a device driver has an mblk_t and needs to call the .Xr ddi_dma_addr_bind_handle 9F -function to bind it to an already existing DMA handle. At that point, it -will receive various DMA cookies that it can use to obtain the addresses -to program the device with for transmitting data. Once the transmit is -done, the driver must then make sure to call +function to bind it to an already existing DMA handle. +At that point, it will receive various DMA cookies that it can use to obtain the +addresses to program the device with for transmitting data. +Once the transmit is done, the driver must then make sure to call .Xr freemsg 9F -to release the data. It must not call +to release the data. +It must not call .Xr freemsg 9F before it receives an interrupt from the device indicating that the data has been transmitted, otherwise it risks sending arbitrary kernel memory. .Pp -When receiving data, the device can perform a similar operation. First, -it must bind the DMA memory into the kernel's virtual memory address +When receiving data, the device can perform a similar operation. +First, it must bind the DMA memory into the kernel's virtual memory address space through a call to the .Xr ddi_dma_addr_bind_handle 9F -function if it has not already. Once it has, it must then call +function if it has not already. +Once it has, it must then call .Xr desballoc 9F -to try and create a new mblk_t which leverages the associated memory. It -can then pass that mblk_t up to the stack. +to try and create a new mblk_t which leverages the associated memory. +It can then pass that mblk_t up to the stack. .Ss Considerations When deciding which of these options to use, there are many different -considerations that must be made. The answer as to whether to bind -memory or to copy data is not always simpler. +considerations that must be made. +The answer as to whether to bind memory or to copy data is not always simpler. .Pp The first thing to remember is that DMA resources may be finite on a -given platform. Consider the case of receiving data. A device driver -that binds one of its receive descriptors may not get it back for quite -some time as it may be used by the kernel until an application actually -consumes it. Device drivers that try to bind memory for receive, often -work with the constraint that they must be able to replace that DMA -memory with another DMA descriptor. If they were not replaced, then -eventually the device would not be able to receive additional data into -the ring. +given platform. +Consider the case of receiving data. +A device driver that binds one of its receive descriptors may not get it back +for quite some time as it may be used by the kernel until an application +actually consumes it. +Device drivers that try to bind memory for receive, often work with the +constraint that they must be able to replace that DMA memory with another DMA +descriptor. +If they were not replaced, then eventually the device would not be able to +receive additional data into the ring. .Pp On the other hand, particularly for larger frames, copying every packet from one buffer to another can be a source of additional latency and -memory waste in the system. For larger copies, the cost of copying may -dwarf any potential cost of performing DMA binding. +memory waste in the system. +For larger copies, the cost of copying may dwarf any potential cost of +performing DMA binding. .Pp For device driver authors that are unsure of what to do, they should first employ the copying method to simplify the act of writing the -device driver. The copying method is simpler and also allows the device -driver author not to worry about allocated DMA memory that is still -outstanding when it is asked to unload. +device driver. +The copying method is simpler and also allows the device driver author not to +worry about allocated DMA memory that is still outstanding when it is asked to +unload. .Pp If device driver writers are worried about the cost, it is recommended to make the decision as to whether or not to copy or bind DMA data -a separate private property for both transmitting and receiving. That -private property should indicate the size of the received frame at which -to switch from one format to the other. This way, data can be gathered -to determine what the impact of each method is on a given platform. +a separate private property for both transmitting and receiving. +That private property should indicate the size of the received frame at which +to switch from one format to the other. +This way, data can be gathered to determine what the impact of each method is on +a given platform. .Sh SEE ALSO .Xr dladm 1M , .Xr driver.conf 4 , diff --git a/usr/src/man/man9e/mc_getcapab.9e b/usr/src/man/man9e/mc_getcapab.9e index b890163c53..8f553ac00d 100644 --- a/usr/src/man/man9e/mc_getcapab.9e +++ b/usr/src/man/man9e/mc_getcapab.9e @@ -38,14 +38,14 @@ structure to the .Xr mac_register 9F function. .It Fa capab -A value which indicates the capability being asked about. For a full -list of capabilities, see the +A value which indicates the capability being asked about. +For a full list of capabilities, see the .Sx CAPABILITIES section of .Xr mac 9E . .It Fa cap_data -Capability specific data that may need to be filled in. The type of data -used is listed in the +Capability specific data that may need to be filled in. +The type of data used is listed in the .Sx CAPABILITIES section of .Xr mac 9E . @@ -54,32 +54,33 @@ section of The .Fn mc_getcapab entry point is called to determine whether or not a device supports a -specific capability. The capability in question is specified in +specific capability. +The capability in question is specified in .Fa capab and the list of possible capabilities is listed in the .Sx CAPABILITIES section of .Xr mac 9E . .Pp -Capabilities are generally only queried once for a given device. An -instance of a device cannot change whether or not it supports a given +Capabilities are generally only queried once for a given device. +An instance of a device cannot change whether or not it supports a given capability after it has been queried by the system. .Pp Each capability has its own specific kind of data that a device driver -needs to fill in as part of declaring that it supports a given -capability. That data is present in +needs to fill in as part of declaring that it supports a given capability. +That data is present in .Fa cap_data . The device driver should cast .Fa cap_data -to the appropriate structure and fill it in. The structures to use for a -given capability are all listed in the +to the appropriate structure and fill it in. +The structures to use for a given capability are all listed in the .Sx CAPABILITIES section of .Xr mac 9E . .Pp The return value is used to indicate whether or not a device driver -supports the given capability. If it does, then the device driver should -return +supports the given capability. +If it does, then the device driver should return .Sy B_TRUE after filling in .Fa cap_data . @@ -90,25 +91,26 @@ Many device drivers employ .Sy switch statements and return .Sy B_FALSE -from their default case statement. The system will present unknown -capabilities to device drivers and they must properly return +from their default case statement. +The system will present unknown capabilities to device drivers and they must +properly return .Sy B_FALSE . .Pp The driver has access to its soft state by casting the .Fa driver -argument to the specific structure. The device driver is responsible for -any necessary locking. +argument to the specific structure. +The device driver is responsible for any necessary locking. .Pp -Many capabilities are related to features of hardware. However, all -hardware and firmware has the possibility of having bugs. It is -recommended that any capability that is supported have some form of +Many capabilities are related to features of hardware. +However, all hardware and firmware has the possibility of having bugs. +It is recommended that any capability that is supported have some form of tunable, whether in the form of a .Sy MAC_PROP_PRIVATE driver-specific property and/or a .Xr driver.conf 5 -property to disable it. This way when problems are discovered in the -field, they can be worked around without requiring initial changes to -the device driver. +property to disable it. +This way when problems are discovered in the field, they can be worked around +without requiring initial changes to the device driver. .Sh CONTEXT This function is generally only called from .Sy kernel diff --git a/usr/src/man/man9e/mc_getprop.9e b/usr/src/man/man9e/mc_getprop.9e index 7f8912711e..d14bcd77b5 100644 --- a/usr/src/man/man9e/mc_getprop.9e +++ b/usr/src/man/man9e/mc_getprop.9e @@ -75,8 +75,8 @@ the value in is sufficient for the property, comparing it to the minimum size listed for the property in .Xr mac 9E . -If it is not, then it should return an error. Otherwise, it should copy -the property's value into +If it is not, then it should return an error. +Otherwise, it should copy the property's value into .Fa pr_val . When an unknown or unsupported property is encountered, generally the @@ -85,25 +85,25 @@ case of the switch statement, the device driver should return an error. .Pp The special property .Sy MAC_PROP_PRIVATE -indicates that this is a device driver specific private property. The -device driver must then look at the value of the +indicates that this is a device driver specific private property. +The device driver must then look at the value of the .Fa pr_name argument and use .Xr strcmp 9F on it, comparing it to each of its private (bounded-size) properties to identify which one it is. .Pp -At this time, private properties are limited to being string based -properties. If other types of property values are used, they will not be -rendered correctly by +At this time, private properties are limited to being string based properties. +If other types of property values are used, they will not be rendered +correctly by .Xr dladm 1M . .Pp The device driver can access its device soft state by casting the .Fa device -pointer to the appropriate structure. As this may be called while other -operations are ongoing, the device driver should employ the appropriate -locking while reading the properties. +pointer to the appropriate structure. +As this may be called while other operations are ongoing, the device driver +should employ the appropriate locking while reading the properties. .Sh CONTEXT The .Fn mc_getprop @@ -217,9 +217,9 @@ example_m_getprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, } .Ed .Sh ERRORS -The device driver may return one of the following errors. While this list -is not intended to be exhaustive, it is recommended to use one of these -if possible. +The device driver may return one of the following errors. +While this list is not intended to be exhaustive, it is recommended to use one +of these if possible. .Bl -tag -width Er .It Er ENOTSUP This error should be used whenever an unknown or unsupported property is diff --git a/usr/src/man/man9e/mc_getstat.9e b/usr/src/man/man9e/mc_getstat.9e index a2733606c1..8312f4f4c4 100644 --- a/usr/src/man/man9e/mc_getstat.9e +++ b/usr/src/man/man9e/mc_getstat.9e @@ -47,12 +47,12 @@ place the statistic. .Sh DESCRIPTION The .Fn mc_getstat -entry point is used to get statistics from the device driver. Statistics -are stored as monotonic values. They should only ever increase over the -lifetime of a device, resetting only as part of the instance of a -device attaching and detaching. When hardware has values that may -overflow, it is up to the device driver to store them as a 64-bit -quantity that does not overflow in its soft state. +entry point is used to get statistics from the device driver. +Statistics are stored as monotonic values. +They should only ever increase over the lifetime of a device, resetting only as +part of the instance of a device attaching and detaching. +When hardware has values that may overflow, it is up to the device driver to +store them as a 64-bit quantity that does not overflow in its soft state. .Pp Most device drivers will use a .Sy switch @@ -75,10 +75,10 @@ and instead return .Pp The device driver can obtain access to its soft state through the .Fa driver -member. It should be cast to the appropriate structure. The device -driver should employ any necessary locking to access the statistic -members of its soft state to ensure that the data is properly -serialized. +member. +It should be cast to the appropriate structure. +The device driver should employ any necessary locking to access the statistic +members of its soft state to ensure that the data is properly serialized. .Sh RETURN VALUES Upon successful completion, the device driver should fill in .Fa stat_value @@ -137,9 +137,9 @@ example_m_getstat(void *arg, uint_t stat, uint64_t *val) } .Ed .Sh ERRORS -The device driver may return one of the following errors. While this list -is not intended to be exhaustive, it is recommended to use one of these -if possible. +The device driver may return one of the following errors. +While this list is not intended to be exhaustive, it is recommended to use one +of these if possible. .Bl -tag -width Er .It Er ENOTSUP The specified statistic is unknown, unsupported, or unimplemented. diff --git a/usr/src/man/man9e/mc_ioctl.9e b/usr/src/man/man9e/mc_ioctl.9e index 65f93e1be0..cb5bba6aac 100644 --- a/usr/src/man/man9e/mc_ioctl.9e +++ b/usr/src/man/man9e/mc_ioctl.9e @@ -51,21 +51,22 @@ request. .Sh DESCRIPTION The .Fn mc_ioctl -entry point is an optional GLDv3 entry point. It provides a means -for device-specific I/O control operations to be initiated. In general, -this entry point is not recommended for most devices and is +entry point is an optional GLDv3 entry point. +It provides a means for device-specific I/O control operations to be initiated. +In general, this entry point is not recommended for most devices and is unimplemented. .Pp The I/O control interface is not like a traditional character or block device's .Xr ioctl 9E -entry point, rather it is a STREAMS-based I/O control operation. The -data pointer of the +entry point, rather it is a STREAMS-based I/O control operation. +The data pointer of the .Fa mp argument is a .Xr iocblk 9S -structure. After handling the message, the driver will need to reply to -the message, which is usually done by using the +structure. +After handling the message, the driver will need to reply to the message, which +is usually done by using the .Xr miocack 9F and .Xr miocnak 9F diff --git a/usr/src/man/man9e/mc_multicst.9e b/usr/src/man/man9e/mc_multicst.9e index daf47bf675..dc0791f546 100644 --- a/usr/src/man/man9e/mc_multicst.9e +++ b/usr/src/man/man9e/mc_multicst.9e @@ -42,16 +42,17 @@ A boolean value that indicates whether the device driver should add the specified address to its filter list or remove it. .It Fa mac A pointer to an array of bytes that contains the new multicast address being -added or removed. It is guaranteed to be at least a number of bytes long equal -to the length of the MAC plugin's address length. For Ethernet devices that -length is six bytes, +added or removed. +It is guaranteed to be at least a number of bytes long equal to the length of +the MAC plugin's address length. +For Ethernet devices that length is six bytes, .Sy ETHERADDRL . .El .Sh DESCRIPTION The .Fn mc_multicst -entry point is used to program a device driver's multicast filters. For -more background on filter management, see the +entry point is used to program a device driver's multicast filters. +For more background on filter management, see the .Sx MAC Address Filter Management section in .Xr mac 9E . @@ -59,19 +60,21 @@ section in The device driver can optionally sanity check .Fa mac by making sure that it's both a valid multicast address and by checking -whether or not it's already programmed the address. Based on the value of +whether or not it's already programmed the address. +Based on the value of .Fa add , the driver should either add the specified address, .Fa mac , -or remove it from its filter tables. The device driver is not -responsible for any form of reference counting on these requests: that -is maintained by the broader framework. +or remove it from its filter tables. +The device driver is not responsible for any form of reference counting on these +requests: that is maintained by the broader framework. .Pp The device driver can access its own device soft state by casting the .Fa device -pointer. The device driver should employ the appropriate locking while -updating and manipulating its filter tables and its own records. It is -recommended that device drivers always maintain a copy of the addresses +pointer. +The device driver should employ the appropriate locking while updating and +manipulating its filter tables and its own records. +It is recommended that device drivers always maintain a copy of the addresses programmed into the device's filter tables so that they can more easily recover from various device resets and errors, or handle requests to suspend and resume the device that may result in the device registers @@ -205,9 +208,9 @@ example_m_multicst(void *arg, boolean_t add, const uint8_t *mac_addr) } .Ed .Sh ERRORS -The device driver may return one of the following errors. While this list -is not intended to be exhaustive, it is recommended to use one of these -if possible. +The device driver may return one of the following errors. +While this list is not intended to be exhaustive, it is recommended to use one +of these if possible. .Bl -tag -width Er .It Er EINVAL The address diff --git a/usr/src/man/man9e/mc_open.9e b/usr/src/man/man9e/mc_open.9e index 7a16ff84ed..0194425536 100644 --- a/usr/src/man/man9e/mc_open.9e +++ b/usr/src/man/man9e/mc_open.9e @@ -47,22 +47,24 @@ The and .Fn mc_close entry points are called when the file system node corresponding to the -device is opened. Standard device drivers do not need to implement this -function and should not define the callback. +device is opened. +Standard device drivers do not need to implement this function and should not +define the callback. .Pp The GLDv3 guarantees that calls to the .Fn mc_open and .Fn mc_close -entry points are serialized. Only one such call will be issued to the -device driver at any time. +entry points are serialized. +Only one such call will be issued to the device driver at any time. .Sh RETURN VALUES Upon successful completion, the device driver should return .Sy 0 for its .Fn mc_open -entry point. Otherwise, it should return a non-zero error number to -indicate an error occurred. +entry point. +Otherwise, it should return a non-zero error number to indicate an error +occurred. .Sh SEE ALSO .Xr mac 9E , .Xr mac_register 9F , diff --git a/usr/src/man/man9e/mc_propinfo.9e b/usr/src/man/man9e/mc_propinfo.9e index cbc43e8774..371e7d12a3 100644 --- a/usr/src/man/man9e/mc_propinfo.9e +++ b/usr/src/man/man9e/mc_propinfo.9e @@ -59,9 +59,10 @@ or .Xr mc_setprop 9E entry points then it does not need to implement the .Xr mc_propinfo 9E -entry point. However, it is highly recommended that these interfaces be -implemented in order to give users and administrators of the system -access to the properties of the device. +entry point. +However, it is highly recommended that these interfaces be implemented in order +to give users and administrators of the system access to the properties of the +device. .Pp When the .Fn mc_propinfo @@ -77,16 +78,16 @@ Most drivers will use a statement and for any property that it supports it should call the appropriate .Xr mac_prop_info 9F -functions to set values and then return. When an unknown or unsupported -property is encountered, generally the +functions to set values and then return. +When an unknown or unsupported property is encountered, generally the .Sy default case of the switch statement, the device driver should simply do nothing and return. .Pp The special property .Sy MAC_PROP_PRIVATE -indicates that this is a device driver specific private property. The -device driver must then look at the value of the +indicates that this is a device driver specific private property. +The device driver must then look at the value of the .Fa pr_name argument and use .Xr strcmp 9F @@ -94,37 +95,41 @@ on it, comparing it to each of its private properties to identify which one it is. .Pp For each property the driver has three different sets of information -that it can fill in. The driver should try to fill in all of these that -make sense, if possible. +that it can fill in. +The driver should try to fill in all of these that make sense, if possible. .Bl -enum .It First, the driver should fill in the permissions of the property with the .Xr mac_prop_info_set_perm 9F -function. These permissions indicate what the device driver supports for -a given property. For each non-private property, see the property list -in +function. +These permissions indicate what the device driver supports for a given property. +For each non-private property, see the property list in .Xr mac 9E -to see what the maximum property permissions are. As discussed in +to see what the maximum property permissions are. +As discussed in .Xr mac 9E , -a device driver may have more limited permissions than the default. For -example, on some SFP-based devices, it may not be possible to change any +a device driver may have more limited permissions than the default. +For example, on some SFP-based devices, it may not be possible to change any of the auto-negotiation properties. .It The driver should then fill in any default value that it has for a -property. This is the value that the device driver sets by default if no -other tuning has been performed. There are different functions depending -on the type of the default value to call. They are all listed in +property. +This is the value that the device driver sets by default if no other tuning has +been performed. +There are different functions depending on the type of the default value to +call. +They are all listed in .Xr mac_prop_info 9F . .It -Finally, a driver may optionally set one or more value ranges. These are -used for integer properties such as +Finally, a driver may optionally set one or more value ranges. +These are used for integer properties such as .Sy MAC_PROP_MTU . The driver may call .Xr mac_prop_info_set_range_uint32 9F to set a series of one or more inclusive ranges that describe valid -values for the property. For example, a device that supports jumbo -frames up to 9600 bytes would call +values for the property. +For example, a device that supports jumbo frames up to 9600 bytes would call .Xr mac_prop_info_set_range_uint32 9F to convey that it supports MTUs in the range of 1500-9600 bytes. .El @@ -132,15 +137,15 @@ to convey that it supports MTUs in the range of 1500-9600 bytes. If the device driver needs to access its private data, it will be available in the .Fa driver -argument which it should cast to the appropriate structure. From there, -the device driver may need to lock the structure to ensure that access -to it is properly serialized. +argument which it should cast to the appropriate structure. +From there, the device driver may need to lock the structure to ensure that +access to it is properly serialized. .Sh RETURN VALUES The .Fn mc_propinfo -entry point does not have a return value. Drivers should simply ignore -and immediately return when encountering unsupported and unknown -properties. +entry point does not have a return value. +Drivers should simply ignore and immediately return when encountering +unsupported and unknown properties. .Sh EXAMPLES The following example shows how a device driver might structure its .Fn mc_propinfo diff --git a/usr/src/man/man9e/mc_setpromisc.9e b/usr/src/man/man9e/mc_setpromisc.9e index 4c3d4f9113..8f037ca202 100644 --- a/usr/src/man/man9e/mc_setpromisc.9e +++ b/usr/src/man/man9e/mc_setpromisc.9e @@ -38,9 +38,11 @@ structure to the function. .It Fa enable A boolean that indicates the desired state of the device's promiscuous -mode. If set to +mode. +If set to .Sy B_TRUE , -promiscuous mode should be enabled on the device. If set to +promiscuous mode should be enabled on the device. +If set to .Sy B_FALSE , then promiscuous mode should be disabled on the device. .El @@ -48,32 +50,35 @@ then promiscuous mode should be disabled on the device. The .Fn mc_setpromisc entry point is called when the GLDv3 wants to change the device's -promiscuous mode. When this entry point is called, the device should -manipulate both its unicast and multicast promiscuous mode. +promiscuous mode. +When this entry point is called, the device should manipulate both its unicast +and multicast promiscuous mode. .Pp When .Fa enable is true, then it should make sure that both unicast and multicast -promiscuous mode are enabled. When it's set to false, then they should -be disabled. In general, devices should always start with promiscuous -mode disabled until the framework indicates that it should be enabled. +promiscuous mode are enabled. +When it's set to false, then they should be disabled. +In general, devices should always start with promiscuous mode disabled until the +framework indicates that it should be enabled. .Pp The device driver's private state is available by casting the .Fa driver -argument to the function. Note, this entry point may be called in -parallel with others and therefore the device driver should employ any -necessary locking on that structure. +argument to the function. +Note, this entry point may be called in parallel with others and therefore the +device driver should employ any necessary locking on that structure. .Sh RETURN VALUES Upon successful completion, the device driver's .Fn mc_setpromisc entry point should return .Sy 0 -after having set the device's state. Otherwise, it should return a -non-zero positive error number to indicate the error that occurred. +after having set the device's state. +Otherwise, it should return a non-zero positive error number to indicate the +error that occurred. .Sh ERRORS -The device driver may return one of the following errors. While this list -is not intended to be exhaustive, it is recommended to use one of these -if possible. +The device driver may return one of the following errors. +While this list is not intended to be exhaustive, it is recommended to use one +of these if possible. .Bl -tag -width Er .It Er EIO The driver encountered a device or transport error while trying to diff --git a/usr/src/man/man9e/mc_setprop.9e b/usr/src/man/man9e/mc_setprop.9e index c978ef6974..b6d8a9a371 100644 --- a/usr/src/man/man9e/mc_setprop.9e +++ b/usr/src/man/man9e/mc_setprop.9e @@ -75,8 +75,8 @@ the value in is sufficient for the property, comparing it to the minimum size listed for the property in .Xr mac 9E . -If it is not, then it should return an error. Otherwise, it should -update the property based on the value in +If it is not, then it should return an error. +Otherwise, it should update the property based on the value in .Fa pr_val . When an unknown or unsupported property is encountered, generally the .Sy default @@ -84,25 +84,26 @@ case of the switch statement, the device driver should return an error. .Pp The special property .Sy MAC_PROP_PRIVATE -indicates that this is a device driver specific private property. The -device driver must then look at the value of the +indicates that this is a device driver specific private property. +The device driver must then look at the value of the .Fa pr_name argument and use .Xr strcmp 9F on it, comparing it to each of its private properties to identify which one it is. .Pp -Not all properties are supposed to be writable. Some devices may opt to -not allow a property that is designated as read/write to be set. When -such a property is encountered, the driver should return the appropriate +Not all properties are supposed to be writable. +Some devices may opt to not allow a property that is designated as read/write to +be set. +When such a property is encountered, the driver should return the appropriate error. .Pp The device driver can access its device soft state by casting the .Fa device -pointer to the appropriate structure. As this may be called while other -operations are ongoing, the device driver should employ the appropriate -locking while writing the properties. +pointer to the appropriate structure. +As this may be called while other operations are ongoing, the device driver +should employ the appropriate locking while writing the properties. .Sh RETURN VALUES Upon successful completion, the device driver should have copied the value of the property into @@ -211,9 +212,9 @@ exmple_m_setprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, } .Ed .Sh ERRORS -The device driver may return one of the following errors. While this list -is not intended to be exhaustive, it is recommended to use one of these -if possible. +The device driver may return one of the following errors. +While this list is not intended to be exhaustive, it is recommended to use one +of these if possible. .Bl -tag -width Er .It Er EINVAL The contents of @@ -221,18 +222,20 @@ The contents of are outside the valid range for the property. .It Er ENOTSUP This error should be used whenever an unknown or unsupported property is -encountered. It should also be used when the property is not writable. +encountered. +It should also be used when the property is not writable. .It Er EOVERFLOW This error should be used when .Fa pr_valsize is smaller than the required size for a given value. .It Er EBUSY This error should be used when a property can't be set because the -device has started. Note that device driver writers are encouraged to design -device drivers such that this error is not possible. +device has started. +Note that device driver writers are encouraged to design device drivers such +that this error is not possible. .It Er ECANCELLED -The device is in a state that does not allow it to handle data; for -example, it's suspended. +The device is in a state that does not allow it to handle data; +for example, it's suspended. .El .Sh SEE ALSO .Xr mac 9E , diff --git a/usr/src/man/man9e/mc_start.9e b/usr/src/man/man9e/mc_start.9e index db8a47339c..ec3c7e98de 100644 --- a/usr/src/man/man9e/mc_start.9e +++ b/usr/src/man/man9e/mc_start.9e @@ -45,11 +45,11 @@ function. The .Fn mc_start entry point for a driver indicates that it should initialize the chip -to be ready to send or receive data. This entry point is guaranteed to -be called before any entry points that are expected to be able to send -and receive data. During this entry point, most devices will allocate -DMA resources, enable the link, and finish performing any necessary -device programming. +to be ready to send or receive data. +This entry point is guaranteed to be called before any entry points that are +expected to be able to send and receive data. +During this entry point, most devices will allocate DMA resources, enable the +link, and finish performing any necessary device programming. .Pp The .Fn mc_stop @@ -60,7 +60,8 @@ not expected to perform any additional I/O. The driver has access to its private data in the .Fa driver argument to either function, which it should cast to the -appropriate structure. The system guarantees that only one of the +appropriate structure. +The system guarantees that only one of the .Fn mc_start and .Fn mc_stop @@ -69,17 +70,19 @@ Similarly, these should not be called at the same time as a device's .Xr attach 9E or .Xr detach 9E -routine. However, the driver may have other ongoing routines that it -needs to protect against. The device driver should always apply the -appropriate locking techniques needed to ensure that access to the data -in its soft state is protected. +routine. +However, the driver may have other ongoing routines that it needs to protect +against. +The device driver should always apply the appropriate locking techniques needed +to ensure that access to the data in its soft state is protected. .Sh RETURN VALUES Upon successful completion, device drivers should return .Sy 0 for the .Fn mc_start -entry point. Otherwise, they should return a non-zero positive error -number to indicate the error that occurred. +entry point. +Otherwise, they should return a non-zero positive error number to indicate the +error that occurred. .Sh SEE ALSO .Xr mac 9E , .Xr mac_register 9F , diff --git a/usr/src/man/man9e/mc_tx.9e b/usr/src/man/man9e/mc_tx.9e index d50ad25fee..625587cd76 100644 --- a/usr/src/man/man9e/mc_tx.9e +++ b/usr/src/man/man9e/mc_tx.9e @@ -48,23 +48,25 @@ member. The .Fn mc_tx entry point is called when the system requires a device driver to -transmit data. The device driver will receive a chain of messge blocks. +transmit data. +The device driver will receive a chain of messge blocks. The .Fa mp_chain -argument represents the first frame. The frame may be spread out -across one or more +argument represents the first frame. +The frame may be spread out across one or more .Xr mblk 9S structures that are linked together by the .Sy b_cont -member. There may be multiple frames, linked together by the +member. +There may be multiple frames, linked together by the .Sy b_next pointer of the .Xr mblk 9S . .Pp For each frame, the driver should allocate the required resources and -prepare it for being transmitted on the wire. The driver may opt to copy -those resources to a DMA buffer or it may bind them. For more -information on these options, see the +prepare it for being transmitted on the wire. +The driver may opt to copy those resources to a DMA buffer or it may bind them. +For more information on these options, see the .Sx MBLKS AND DMA section of .Xr mac 9E . @@ -78,8 +80,9 @@ flags, it must check whether either apply for the given frame using the .Xr mac_hcksum_get 9F and .Xr mac_lso_get 9F -functions respectively. If either is enabled for the given frame, the -hardware must arrange for that to be taken care of. +functions respectively. +If either is enabled for the given frame, the hardware must arrange for that to +be taken care of. .Pp For each frame that the device driver processes it is responsible for doing one of three things with it: @@ -99,27 +102,30 @@ The device driver is in charge of the memory associated with If the device driver does not return the message blocks to the GLDv3, then it must call .Xr freemsg 9F -on the frames. If it does not, the memory associated with them -will be leaked. When a frame is being transmitted, if the device driver -performed DMA binding, it should not free the message block until after -it is guaranteed that the frame has been transmitted. If the message -block was copied to a DMA buffer, then it is allowed to call +on the frames. +If it does not, the memory associated with them will be leaked. +When a frame is being transmitted, if the device driver performed DMA binding, +it should not free the message block until after it is guaranteed that the frame +has been transmitted. +If the message block was copied to a DMA buffer, then it is allowed to call .Xr freemsg 9F at any point. .Pp In general, the device driver should not drop frames without -transmitting them unless it has no other choice. Times when this happens -may include the device driver being in a state where it can't transmit, -an error was found in the frame while trying to establish the checksum -or LSO state, or some other kind of error that represents an issue with +transmitting them unless it has no other choice. +Times when this happens may include the device driver being in a state where it +can't transmit, an error was found in the frame while trying to establish the +checksum or LSO state, or some other kind of error that represents an issue with the passed frame. .Pp The device driver should not free the chain when it does not have enough -resources. For example, if entries in a device's descriptor ring fill -up, then it should not drop those frames and instead should return all -of the frames that were not transmitted. This indicates to the stack -that the device is full and that flow control should be asserted. Back -pressure will be applied to the rest of the stack, allowing most systems +resources. +For example, if entries in a device's descriptor ring fill up, then it should +not drop those frames and instead should return all of the frames that were not +transmitted. +This indicates to the stack that the device is full and that flow control should +be asserted. +Back pressure will be applied to the rest of the stack, allowing most systems to behave better. .Pp Once a device driver has returned unprocessed frames from its @@ -129,21 +135,24 @@ calls to its .Fn mc_tx entry point until it calls .Xr mac_tx_update 9F -to indicate that resources are available again. Note that because it is -the device driver that is calling this function to indicate resources -are available, it is very important that it only return frames in cases -where the device driver itself will be notified that resources are -available again. For example, when it receives an interrupt indicating -that the data that it transmitted has been completed so it can use -entries in its descriptor ring or other data structures again. +to indicate that resources are available again. +Note that because it is the device driver that is calling this function to +indicate resources are available, it is very important that it only return +frames in cases where the device driver itself will be notified that resources +are available again. +For example, when it receives an interrupt indicating that the data that it +transmitted has been completed so it can use entries in its descriptor ring or +other data structures again. .Pp The device driver can obtain access to its soft state through the .Fa driver -member. It should cast it to the appropriate structure. The device -driver should employ any necessary locking to access the transmit -related data structures. Note that the device driver should expect that -it may have its transmit endpoints called into from other threads while -it's servicing device interrupts related to them. +member. +It should cast it to the appropriate structure. +The device driver should employ any necessary locking to access the transmit +related data structures. +Note that the device driver should expect that it may have its transmit +endpoints called into from other threads while it's servicing device interrupts +related to them. .Sh CONTEXT The .Fn mc_tx diff --git a/usr/src/man/man9e/mc_unicst.9e b/usr/src/man/man9e/mc_unicst.9e index c9df221f71..9886dc22af 100644 --- a/usr/src/man/man9e/mc_unicst.9e +++ b/usr/src/man/man9e/mc_unicst.9e @@ -38,20 +38,23 @@ structure to the function. .It Fa mac A pointer to an array of bytes that contains the new unicast address of -the device. It is guaranteed to be at least a number of bytes long equal -to the length of the MAC plugin's address length. For Ethernet devices that -length is six bytes, +the device. +It is guaranteed to be at least a number of bytes long equal to the length of +the MAC plugin's address length. +For Ethernet devices that length is six bytes, .Sy ETHERADDRL . .El .Sh DESCRIPTION The .Fn mc_unicst entry point is used by the GLDv3 to indicate that the device driver -should update the primary MAC address of the device. In the basic mode -of operation, this entry point is required and the device has a single -primary MAC address. If multiple MAC addresses are required, the -device will be placed into promiscuous mode. This call should overwrite -the existing MAC address that is programmed into the device. +should update the primary MAC address of the device. +In the basic mode of operation, this entry point is required and the device has +a single primary MAC address. +If multiple MAC addresses are required, the device will be placed into +promiscuous mode. +This call should overwrite the existing MAC address that is programmed into the +device. .Pp As noted in the .Sx PARAMETERS @@ -62,22 +65,24 @@ specify an address; however, it should be assumed to be no longer than that value. .Pp The device driver can optionally assert that the address is in the -valid form for a unicast address and then program the device. The device -driver can access its device soft state by casting the +valid form for a unicast address and then program the device. +The device driver can access its device soft state by casting the .Fa device -pointer to the appropriate structure. As this may be called while other -operations are ongoing, the device driver should employ the appropriate -locking while updating the data. +pointer to the appropriate structure. +As this may be called while other operations are ongoing, the device driver +should employ the appropriate locking while updating the data. .Pp It is recommended that device drivers always maintain a copy of the current unicast address in its soft state so that way it can recover from various device reset and errors or handle requests to suspend and resume the device that may result in device registers being cleared. .Pp -Some devices support multiple MAC address filters. The +Some devices support multiple MAC address filters. +The .Fn mc_unicst -entry point only supports a single MAC address. In this case, devices -should only use a single MAC address and replace that MAC address. +entry point only supports a single MAC address. +In this case, devices should only use a single MAC address and replace that MAC +address. Support for using more than a single MAC address filter will be provided by future interfaces. .Sh RETURN VALUES @@ -87,9 +92,9 @@ unicast filter and return Otherwise, the MAC address should remain unchanged and the driver should return an appropriate error number. .Sh ERRORS -The device driver may return one of the following errors. While this list -is not intended to be exhaustive, it is recommended to use one of these -if possible. +The device driver may return one of the following errors. +While this list is not intended to be exhaustive, it is recommended to use one +of these if possible. .Bl -tag -width Er .It Er EINVAL The address diff --git a/usr/src/man/man9e/usba_hcdi.9e b/usr/src/man/man9e/usba_hcdi.9e index a60f56db58..28d1fbe207 100644 --- a/usr/src/man/man9e/usba_hcdi.9e +++ b/usr/src/man/man9e/usba_hcdi.9e @@ -29,11 +29,13 @@ This may be removed or changed at any time. .Sy hcdi drivers are device drivers that support USB host controller hardware. USB host controllers provide an interface between the operating system -and USB devices. They abstract the interface to the devices, often -provide ways of performing DMA, and also act as the root hub. +and USB devices. +They abstract the interface to the devices, often provide ways of performing +DMA, and also act as the root hub. .Pp .Sy hcdi -drivers are part of the illumos USB Architecture (USBA). The +drivers are part of the illumos USB Architecture (USBA). +The .Xr usba 7D driver provides support for many of the surrounding needs of an .Sy hcdi @@ -43,9 +45,10 @@ vector, These functions cover everything from initialization to performing I/O to USB devices on behalf of client device drivers. .Ss USB Speed and Version Background -USB devices are often referred to in two different ways. The first way -is the USB version that they conform to. In the wild this looks like USB -1.1, USB 2.0, USB 3.0, etc.. However, devices are also referred to as +USB devices are often referred to in two different ways. +The first way is the USB version that they conform to. +In the wild this looks like USB 1.1, USB 2.0, USB 3.0, etc.. +However, devices are also referred to as .Sq full- , .Sq low- , .Sq high- , @@ -53,20 +56,23 @@ is the USB version that they conform to. In the wild this looks like USB speed devices. .Pp The latter description describes the maximum theoretical speed of a -given device. For example, a super-speed device theoretically caps out -around 5 Gbit/s, whereas a low-speed device caps out at 1.5 Mbit/s. +given device. +For example, a super-speed device theoretically caps out around 5 Gbit/s, +whereas a low-speed device caps out at 1.5 Mbit/s. .Pp In general, each speed usually corresponds to a specific USB protocol -generation. For example, all USB 3.0 devices are super-speed devices. -All 'high-speed' devices are USB 2.x devices. Full-speed devices are -special in that they can either be USB 1.x or USB 2.x devices. Low-speed -devices are only a USB 1.x thing, they did not jump the fire line to USB -2.x. +generation. +For example, all USB 3.0 devices are super-speed devices. +All 'high-speed' devices are USB 2.x devices. +Full-speed devices are special in that they can either be USB 1.x or USB 2.x +devices. +Low-speed devices are only a USB 1.x thing, they did not jump the fire line to +USB 2.x. .Pp USB 3.0 devices and ports generally have the wiring for both USB 2.0 and -USB 3.0. When a USB 3.0 device is plugged into a USB 2.0 port or hub, -then it will report its version as USB 2.1, to indicate that it is -actually a USB 3.0 device. +USB 3.0. +When a USB 3.0 device is plugged into a USB 2.0 port or hub, then it will report +its version as USB 2.1, to indicate that it is actually a USB 3.0 device. .Ss USB Endpoint Background To understand the organization of the functions that make up the hcdi operations vector, it helps to understand how USB devices are organized @@ -74,136 +80,149 @@ and work at a high level. .Pp A given USB device is made up of .Em endpoints . -A request, or transfer, is made to a specific USB endpoint. These -endpoints can provide different services and have different expectations +A request, or transfer, is made to a specific USB endpoint. +These endpoints can provide different services and have different expectations around the size of the data that'll be used in a given request and the -periodicity of requests. Endpoints themselves are either used to make -one-shot requests, for example, making requests to a mass storage device -for a given sector, or for making periodic requests where you end up -polling on the endpoint, for example, polling on a USB keyboard for -keystrokes. +periodicity of requests. +Endpoints themselves are either used to make one-shot requests, for example, +making requests to a mass storage device for a given sector, or for making +periodic requests where you end up polling on the endpoint, for example, polling +on a USB keyboard for keystrokes. .Pp Each endpoint encodes two different pieces of information: a direction -and a type. There are two different directions: IN and OUT. These refer -to the general direction that data moves relative to the operating -system. For example, an IN transfer transfers data in to the operating -system, from the device. An OUT transfer transfers data from the -operating system, out to the device. +and a type. +There are two different directions: IN and OUT. +These refer to the general direction that data moves relative to the operating +system. +For example, an IN transfer transfers data in to the operating system, from the +device. +An OUT transfer transfers data from the operating system, out to the device. .Pp There are four different kinds of endpoints: .Bl -tag -width Sy -offset indent .It Sy BULK -These transfers are large transfers of data to or from a device. The -most common use for bulk transfers is for mass storage devices. Though -they are often also used by network devices and more. Bulk endpoints do -not have an explicit time component to them. They are always used for -one-shot transfers. +These transfers are large transfers of data to or from a device. +The most common use for bulk transfers is for mass storage devices. +Though they are often also used by network devices and more. +Bulk endpoints do not have an explicit time component to them. +They are always used for one-shot transfers. .It Sy CONTROL These transfers are used to manipulate devices themselves and are used for USB protocol level operations (whether device-specific, -class-specific, or generic across all of USB). Unlike other transfers, -control transfers are always bi-directional and use different kinds of -transfers. +class-specific, or generic across all of USB). +Unlike other transfers, control transfers are always bi-directional and use +different kinds of transfers. .It Sy INTERRUPT Interrupt transfers are used for small transfers that happen -infrequently, but need reasonable latency. A good example of interrupt -transfers is to receive input from a USB keyboard. Interrupt-IN -transfers are generally polled. Meaning that a client (device driver) -opens up an interrupt-IN endpoint to poll on it, and receives periodic -updates whenever there is information available. However, Interrupt -transfers can be used as one-shot transfers both going IN and OUT. +infrequently, but need reasonable latency. +A good example of interrupt transfers is to receive input from a USB keyboard. +Interrupt-IN transfers are generally polled. +Meaning that a client (device driver) opens up an interrupt-IN endpoint to poll +on it, and receives periodic updates whenever there is information available. +However, Interrupt transfers can be used as one-shot transfers both going IN and +OUT. .It Sy ISOCHRONOUS These transfers are things that happen once per time-interval at a very -regular rate. A good example of these transfers are for audio and video. +regular rate. +A good example of these transfers are for audio and video. A device may describe an interval as 10ms at which point it will read or write the next batch of data every 10ms and transform it for the user. -There are no one-shot Isochronous-IN transfers. There are one-shot -Isochronous-OUT transfers, but these are used by device drivers to -always provide the system with sufficient data. +There are no one-shot Isochronous-IN transfers. +There are one-shot Isochronous-OUT transfers, but these are used by device +drivers to always provide the system with sufficient data. .El .Pp To find out information about the endpoints, USB devices have a series -of descriptors that cover different aspects of the device. For example, -there are endpoint descriptors which cover the properties of endpoints -such as the maximum packet size or polling interval. +of descriptors that cover different aspects of the device. +For example, there are endpoint descriptors which cover the properties of +endpoints such as the maximum packet size or polling interval. .Pp -Descriptors exist at all levels of USB. For example, there are general -descriptors for every device. The USB device descriptor is described in +Descriptors exist at all levels of USB. +For example, there are general descriptors for every device. +The USB device descriptor is described in .Xr usb_dev_descr 9S . Host controllers will look at these descriptors to ensure that they program the device correctly; however, they are more often used by -client device drivers. There are also descriptors that exist at a class -level. For example, the hub class has a class-specific descriptor which -describes properties of the hub. That information is requested for and -used by the hub driver. +client device drivers. +There are also descriptors that exist at a class level. +For example, the hub class has a class-specific descriptor which describes +properties of the hub. +That information is requested for and used by the hub driver. .Pp All of the different descriptors are gathered by the system and placed into a tree, with device descriptors, configurations, endpoints, and -more. Client device drivers gain access to this tree and then use them -to then open endpoints, which are called pipes in USBA (and some -revisions of the USB specification). +more. +Client device drivers gain access to this tree and then use them to then open +endpoints, which are called pipes in USBA (and some revisions of the USB +specification). .Pp Each pipe gives access to a specific endpoint on the device which can be -used to perform transfers of a specific type and direction. For example, -a mass storage device often has three different endpoints, the default -control endpoint (which every device has), a Bulk-IN endpoint, and a -Bulk-OUT endpoint. The device driver ends up with three open pipes. One -to the default control endpoint to configure the device, and then the +used to perform transfers of a specific type and direction. +For example, a mass storage device often has three different endpoints, the +default control endpoint (which every device has), a Bulk-IN endpoint, and a +Bulk-OUT endpoint. +The device driver ends up with three open pipes. +One to the default control endpoint to configure the device, and then the other two are used to perform I/O. .Pp These routines translate more or less directly into calls to a host -controller driver. A request to open a pipe takes an endpoint descriptor -that describes the properties of the pipe, and the host controller -driver goes through and does any work necessary to allow the client -device driver to access it. Once the pipe is open, it either makes -one-shot transfers specific to the transfer type or it starts performing -a periodic poll of an endpoint. +controller driver. +A request to open a pipe takes an endpoint descriptor that describes the +properties of the pipe, and the host controller driver goes through and does any +work necessary to allow the client device driver to access it. +Once the pipe is open, it either makes one-shot transfers specific to the +transfer type or it starts performing a periodic poll of an endpoint. .Pp All of these different actions translate into requests to the host -controller. The host controller driver itself is in charge of making -sure that all of the required resources for polling are allocated with a -request and then proceed to give the driver's periodic callbacks. +controller. +The host controller driver itself is in charge of making sure that all of the +required resources for polling are allocated with a request and then proceed to +give the driver's periodic callbacks. .Pp -For each of the different operations described above, there is a -corresponding entry in +For each of the different operations described above, there is a corresponding +entry in .Xr usba_hcdi_ops 9S . For example, open an endpoint, the host controller has to implement .Xr usba_hcdi_pipe_open 9E -and for each transfer type, there is a different transfer function. One -example is +and for each transfer type, there is a different transfer function. +One example is .Xr usba_hcdi_bulk_xfer 9E . See .Xr usba_hcdi_ops 9S for a full list of the different function endpoints. .Ss HCDI Initialization -hcdi drivers are traditional character device drivers. To start with, an -hcdi driver should define traditional +hcdi drivers are traditional character device drivers. +To start with, an hcdi driver should define traditional .Xr dev_ops 9S and .Xr cb_ops 9S -structures. To get started, the device driver should perform normal -device initialization in an +structures. +To get started, the device driver should perform normal device initialization in +an .Xr attach 9E -entry point. For example, PCI devices should setup the device's -registers and program them. In addition, all devices should -configure interrupts, before getting ready to call into the USBA. Each -instance of a device must be initialized and registered with the USBA. +entry point. +For example, PCI devices should setup the device's registers and program them. +In addition, all devices should configure interrupts, before getting ready to +call into the USBA. +Each instance of a device must be initialized and registered with the USBA. .Pp To initialize a device driver with the USBA, it must first call .Xr usba_alloc_hcdi_ops 9F . This provides a device driver with the .Xr usba_hcdi_ops 9S -structure that it must fill out. Please see +structure that it must fill out. +Please see .Xr usba_hcdi_ops 9S -for instructions on how it should be filled out. Once filled out, the -driver should call +for instructions on how it should be filled out. +Once filled out, the driver should call .Xr usba_hcdi_register 9F . .Pp If the call to register fails for whatever reason, the device driver should fail its .Xr attach 9E -entry point. After this call successfully completes, the driver should -assume that any of the functions it registered with the call to +entry point. +After this call successfully completes, the driver should assume that any of the +functions it registered with the call to .Xr usba_hcdi_register 9F will be called at this point. .Ss Binding the Root Hub @@ -211,49 +230,52 @@ Once this is set up, the hcdi driver must initialize its root hub by calling Xr usba_hcdi_bind_root_hub 9F . To bind the root hub, the device driver is responsible for providing a -device descriptor that represents the hardware. Depending on the -hardware, this descriptor may be either static or dynamic. +device descriptor that represents the hardware. + Depending on the hardware, this descriptor may be either static or dynamic. .Pp This device descriptor should be a packed descriptor that is the same -that would be read off of the device. The device descriptor should match -a hub of a USB generation equivalent to the maximum speed of the device. +that would be read off of the device. +The device descriptor should match a hub of a USB generation equivalent to the +maximum speed of the device. For example, a USB 3.0 host controller would use a USB 3.0 hub's device -descriptor. Similarly, a USB 2.0 host controller would use a USB 2.0 -hub's device descriptor. +descriptor. +Similarly, a USB 2.0 host controller would use a USB 2.0 hub's device +descriptor. .Pp The descriptor first starts with a USB configuration descriptor, as defined in .Xr usb_cfg_descr 9S . -It is then followed by an interface descriptor. The definition for it -can be found in +It is then followed by an interface descriptor. +The definition for it can be found in .Xr usb_if_descr 9S . Next is the endpoint descriptor for the single Interrupt-IN endpoint that all hubs have as defined in .Xr usb_ep_descr 9S . -Finally, any required companion descriptors should be used. For example, -a USB 3.x hub will have a +Finally, any required companion descriptors should be used. +For example, a USB 3.x hub will have a .Xr usb_ep_ss_comp_descr 9S appended to the structure. .Pp Note, that the structure needs to be packed, as though it were read from -a device. The structures types referenced in +a device. +The structures types referenced in .Xr usb_cfg_descr 9S , .Xr usb_if_descr 9S , .Xr usb_ep_descr 9S , and .Xr usb_ep_ss_comp_descr 9S -are not packed for this purpose. They should not be used as they have -gaps added by the compiler for alignment. +are not packed for this purpose. +They should not be used as they have gaps added by the compiler for alignment. .Pp Once assembled, the device driver should call .Xr usb_hubdi_bind_root_hub 9F . This will cause an instance of the .Xr hubd 7D -driver to be attached and associated with the root controller. As such, -driver writers need to ensure that all initialization is done prior to -loading the root hub. Once successfully loaded, driver writers should -assume that they'll get other calls into the driver's operation vector -before the call to +driver to be attached and associated with the root controller. +As such, driver writers need to ensure that all initialization is done prior to +loading the root hub. +Once successfully loaded, driver writers should assume that they'll get other +calls into the driver's operation vector before the call to .Xr usb_hcdi_bind_root_hub 9F. .Pp If the call to @@ -283,8 +305,8 @@ and return .Dv DDI_FAILURE . .Pp Once the root hub has been unbound, the device driver can continue by -removing its hcdi registration with USBA. To do this, the driver should -call +removing its hcdi registration with USBA. +To do this, the driver should call .Xr usba_hcdi_unregister 9F . As this call always succeeds, at this point, it is safe for the driver to tear down all the rest of its resources and successfully detach. @@ -297,14 +319,15 @@ hcdi drivers .Em must not store any data with .Xr ddi_get_driver_private 9F . -This private data is used by USBA. If it has been called before the -device registers, then it will fail to register successfully with the -USBA. However, setting it after that point will corrupt the state of the -USBA and likely lead to data corruption and crashes. +This private data is used by USBA. +If it has been called before the device registers, then it will fail to register +successfully with the USBA. +However, setting it after that point will corrupt the state of the USBA and +likely lead to data corruption and crashes. .Pp Similarly, part of the minor number space is utilized to represent -various devices like the root hub. Whenever a device driver is presented -with a +various devices like the root hub. +Whenever a device driver is presented with a .Ft dev_t and it's trying to extract the minor number, it must take into account the constant @@ -319,7 +342,8 @@ minor_t minor = getminor(dev) & ~HUBD_IS_ROOT_HUB; .Ss Required Character and Device Operations The USBA handles many character and device operations entry points for a device driver or has strict rules on what a device driver must do in -them. This section summarizes those constraints. +them. +This section summarizes those constraints. .Pp In the .Xr dev_ops 9S @@ -365,7 +389,8 @@ The device driver should implement an entry point that obtains access to its .Sy dev_info_t and then calls -.Xr usba_hubdi_open 9F . See +.Xr usba_hubdi_open 9F . +See .Xr usba_hcdi_cb_open 9E for more information. .It Sy cb_close @@ -374,7 +399,8 @@ The device driver should implement a entry point that obtains access to its .Sy dev_info_t and then calls -.Xr usba_hubdi_close 9F . See +.Xr usba_hubdi_close 9F . + See .Xr usba_hcdi_cb_close 9E for more information. .It Sy cb_ioctl @@ -424,8 +450,9 @@ or In general, the USBA calls into a device driver through one of the functions that it has register in the .Xr usba_hcdi_ops 9S -structure. However, in response to a data transfer, the device driver -will need to call back into the USBA by calling +structure. +However, in response to a data transfer, the device driver will need to call +back into the USBA by calling .Xr usba_hcdi_cb 9F . .Pp A device driver must hold @@ -438,35 +465,38 @@ another call back to one of the vectors. .Pp Outside of that constraint, the device driver should perform locking of -its data structures. It should assume that many of its entry points will -be called in parallel across the many devices that exist. +its data structures. +It should assume that many of its entry points will be called in parallel across +the many devices that exist. .Pp There are certain occasions where a device driver may have to enter the .Sy p_mutex member of the .Xr usba_pipe_handle_data 9S -structure when duplicating isochronous or interrupt requests. The USBA -should in general, not hold this lock across calls to the HCD driver, -and in turn, the HCD driver should not hold this lock across any calls -back to the USBA. As such, the HCD driver should make sure to -incorporate the lock ordering of this mutex into its broader lock -ordering and operational theory. Generally, the +structure when duplicating isochronous or interrupt requests. +The USBA should in general, not hold this lock across calls to the HCD driver, +and in turn, the HCD driver should not hold this lock across any calls back to +the USBA. +As such, the HCD driver should make sure to incorporate the lock ordering of +this mutex into its broader lock ordering and operational theory. +Generally, the .Sy p_mutex mutex will be entered after any HCD-specific locks. .Pp The final recommendation is that due to the fact that the host controller driver provides services to a multitude of USB devices at once, it should strive not to hold its own internal locks while waiting -for I/O to complete, such as an issued command. This is particularly -true if the device driver uses coarse grained locking. If the device -driver does not pay attention to these conditions, it can easily lead to -service stalls. +for I/O to complete, such as an issued command. +This is particularly true if the device driver uses coarse grained locking. +If the device driver does not pay attention to these conditions, it can easily +lead to service stalls. .Ss Synchronous and Asynchronous Entry Points The majority of the entry points that a host controller driver has to implement are .Em synchronous . All actions that the entry point implies must be completed before the -entry point returns. However, the various transfer routines: +entry point returns. +However, the various transfer routines: .Xr usba_hcdi_pipe_bulk_xfer 9E , .Xr usba_hcdi_pipe_ctrl_xfer 9E , .Xr usba_hcdi_pipe_intr_xfer 9E , @@ -476,14 +506,15 @@ are ultimately .Em asynchronous entry points. .Pp -Each of the above entry points begins one-shot or periodic I/O. When the -driver returns +Each of the above entry points begins one-shot or periodic I/O. +When the driver returns .Sy USB_SUCCESS from one of those functions, it is expected that it will later call .Xr usba_hcdi_cb 9F -when the I/O completes, whether successful or not. It is the driver's -responsibility to keep track of these outstanding transfers and time -them out. For more information on timeouts, see the section +when the I/O completes, whether successful or not. +It is the driver's responsibility to keep track of these outstanding transfers +and time them out. +For more information on timeouts, see the section .Sx Endpoint Timeouts . .Pp If for some reason, the driver fails to initialize the I/O transfer and @@ -494,24 +525,26 @@ from its entry point, then it must not call for that transfer. .Ss Short Transfers Not all USB transfers will always return the full amount of data -requested in the transfer. Host controller drivers need to be ready for -this and report it. Each request structure has an attribute to indicate -whether or not short transfers are OK. If a short transfer is OK, then -the driver should update the transfer length. Otherwise, it should -instead return an error. See the individual entry point pages for more -information. +requested in the transfer. +Host controller drivers need to be ready for this and report it. +Each request structure has an attribute to indicate whether or not short +transfers are OK. +If a short transfer is OK, then the driver should update the transfer length. +Otherwise, it should instead return an error. +See the individual entry point pages for more information. .Ss Root Hub Management -As was mentioned earlier, every host controller is also a root hub. The -USBA interfaces with the root hub no differently than any other hub. The -USBA will open pipes and issue both control and periodic interrupt-IN +As was mentioned earlier, every host controller is also a root hub. +The USBA interfaces with the root hub no differently than any other hub. +The USBA will open pipes and issue both control and periodic interrupt-IN transfers to the root hub. .Pp In the host controller driver's .Xr usba_hcdi_pipe_open 9E entry point, it already has to look at the pipe handle it's been given -to determine the attributes of the endpoint it's looking at. However, -before it does that it needs to look at the USB address of the device -the handle corresponds to. If the device address matches the macro +to determine the attributes of the endpoint it's looking at. +However, before it does that it needs to look at the USB address of the device +the handle corresponds to. +If the device address matches the macro .Sy ROOT_HUB_ADDR , then this is a time where the USBA is opening one of the root hub's endpoints. @@ -525,15 +558,15 @@ described: .Bl -tag -width Fn .It Fn usba_hcdi_pipe_ctrl_xfer The device driver needs to intercept control transfers to the root hub -and translate them into the appropriate form for the device. For -example, the device driver may be asked to get a port's status. It -should determine the appropriate way to perform this, such as reading a +and translate them into the appropriate form for the device. +For example, the device driver may be asked to get a port's status. +It should determine the appropriate way to perform this, such as reading a PCI memory-mapped register, and then create the appropriate response. .Pp The device driver needs to implement all of the major hub specific -request types. It is recommended that driver writers see what existing -host controller drivers implement and what the hub driver currently -requires to implement this. +request types. +It is recommended that driver writers see what existing host controller drivers +implement and what the hub driver currently requires to implement this. .Pp Aside from the fact that the request is not being issued to a specific USB device, a request to the root hub follows the normal rules for a @@ -541,22 +574,23 @@ transfer and the device driver will need to call .Xr usba_hcdi_cb 9F to indicate that it has finished. .It Fn usba_hcdi_pipe_bulk_xfer -The root hub does not support bulk transfers. If for some reason one is -requested on the root hub, the driver should return +The root hub does not support bulk transfers. +If for some reason one is requested on the root hub, the driver should return .Sy USB_NOT_SUPPORTED . .It Fn usba_hcdi_pipe_intr_xfer -The root hub only supports periodic interrupt-IN transfers. If an -interrupt-OUT transfer or an interrupt-IN transfer with the +The root hub only supports periodic interrupt-IN transfers. +If an interrupt-OUT transfer or an interrupt-IN transfer with the .Sy USB_ATTRS_ONE_XFER attribute is set, then the driver should return .Sy USB_NOT_SUPPORTED . .Pp Otherwise, this represents a request to begin polling on the status -endpoint for a hub. This is a periodic request, see the section +endpoint for a hub. +This is a periodic request, see the section .Sx Device Addressing -Every USB device has an address assigned to it. The addresses assigned -to each controller are independent. The root hub of a given controller -always has an address of +Every USB device has an address assigned to it. +The addresses assigned to each controller are independent. +The root hub of a given controller always has an address of .Dv ROOT_HUB_ADDR . .Pp In general, addresses are assigned by the USBA and stored in the @@ -564,11 +598,11 @@ In general, addresses are assigned by the USBA and stored in the member of a .Xr usba_device_t 9S . However, some controllers, such as xHCI, require that they control the -device addressing themselves to facilitate their functionality. In such -a case, the USBA still assigns every device an address; however, the +device addressing themselves to facilitate their functionality. +In such a case, the USBA still assigns every device an address; however, the actual address on the bus will be different and assigned by the HCD -driver. An HCD driver that needs to address devices itself must -implement the +driver. +An HCD driver that needs to address devices itself must implement the .Xr usba_hcdi_device_address 9E entry point. .Sx Endpoint Polling @@ -576,67 +610,74 @@ more on the semantics of polling and periodic requests. .Pp Here, the device driver will need to provide data and perform a callback whenever the state of one of the ports changes on its virtual hub. -Different drivers have different ways to perform this. For example, some -hardware will provide an interrupt to indicate that a change has -occurred. Other hardware does not, so this must be simulated. +Different drivers have different ways to perform this. +For example, some hardware will provide an interrupt to indicate that a change +has occurred. +Other hardware does not, so this must be simulated. .Pp The way that the status data responses must be laid out is based in the -USB specification. Generally, there is one bit per port and the driver -sets the bit for the corresponding port that has had a change. +USB specification. +Generally, there is one bit per port and the driver sets the bit for the +corresponding port that has had a change. .It Fn usba_hcdi_pipe_isoc_xfer -The root hub does not support isochronous transfers. If for some reason -one is requested on the root hub, the driver should return +The root hub does not support isochronous transfers. +If for some reason one is requested on the root hub, the driver should return .It Fn usba_hcdi_pipe_close When a pipe to the root hub is closed, the device driver should tear -down whatever it created as part of opening the pipe. In addition, if -the pipe was an interrupt-IN pipe, if it has not already had polling -stop, it should stop the polling as part of closing the pipe. +down whatever it created as part of opening the pipe. +In addition, if the pipe was an interrupt-IN pipe, if it has not already had +polling stop, it should stop the polling as part of closing the pipe. .It Fn usba_hcdi_pipe_stop_intr_polling When a request to stop interrupt polling comes in and it is directed towards the root hub, the device driver should cease delivering -callbacks upon changes in port status being detected. However, it should -continue keeping track of what changes have occurred for the next time -that polling starts. +callbacks upon changes in port status being detected. +However, it should continue keeping track of what changes have occurred for the +next time that polling starts. .Pp The primary request that was used to start polling should be returned, as with any other request to stop interrupt polling. .It Fn usba_hcdi_pipe_stop_isoc_polling -The root hub does not support isochronous transfers. If for some reason -it calls asking to stop polling on an isochronous transfer, the device -driver should log an error and return +The root hub does not support isochronous transfers. +If for some reason it calls asking to stop polling on an isochronous transfer, +the device driver should log an error and return .Sy USB_NOT_SUPPORTED . .El .Ss Endpoint Polling Both interrupt-IN and isochronous-IN endpoints are generally periodic or -polled endpoints. interrupt-IN polling is indicated by the lack of the +polled endpoints. +interrupt-IN polling is indicated by the lack of the .Sy USB_ATTRS_ONE_XFER -flag being set. All isochronous-IN transfer requests are requests for -polling. +flag being set. +All isochronous-IN transfer requests are requests for polling. .Pp -Polling operates in a different fashion from traditional transfers. With -a traditional transfer, a single request is made and a single callback -is made for it, no more and no less. With a polling request, things are -different. A single transfer request comes in; however, the driver needs -to keep ensuring that transfers are being made within the polling bounds -until a request to stop polling comes in or a fatal error is -encountered. +Polling operates in a different fashion from traditional transfers. +With a traditional transfer, a single request is made and a single callback +is made for it, no more and no less. +With a polling request, things are different. +A single transfer request comes in; however, the driver needs to keep ensuring +that transfers are being made within the polling bounds until a request to stop +polling comes in or a fatal error is encountered. .Pp In many cases, as part of initializing the request, the driver will prepare several transfers such that there is always an active transfer, -even if there is some additional latency in the system. This ensures -that even if there is a momentary delay in the device driver processing -a given transfer, I/O data will not be lost. +even if there is some additional latency in the system. +This ensures that even if there is a momentary delay in the device driver +processing a given transfer, I/O data will not be lost. .Pp The driver must not use the original request structure until it is ready -to return due to a request to stop polling or an error. To obtain new -interrupt and isochronous request structures, the driver should use the +to return due to a request to stop polling or an error. +To obtain new interrupt and isochronous request structures, the driver should +use the .Xr usba_hcdi_dup_intr_req 9F and .Xr usba_hcdi_dup_isoc_req 9F -functions. These functions also allocate the resulting message blocks -that data should be copied into. Note, it is possible that memory will -not be available to duplicate such a request. In this case, the driver -should use the original request to return an error and stop polling. +functions. +These functions also allocate the resulting message blocks that data should be +copied into. +Note, it is possible that memory will not be available to duplicate such a +request. +In this case, the driver should use the original request to return an error and +stop polling. .Ss Request Memory and DMA Each of the four transfer operations, .Xr usba_hcdi_pipe_ctrl_xfer 9E , @@ -646,10 +687,10 @@ and .Xr usba_hcdi_pipe_isoc_xfer 9E give data to hcdi drivers in the form of .Xr mblk 9S -structures. To perform the individual transfers, most systems devices -will leverage DMA. Drivers should allocate memory suitable for DMA for -each transfer that they need to perform and copy the data to and from -the message blocks. +structures. +To perform the individual transfers, most systems devices will leverage DMA. +Drivers should allocate memory suitable for DMA for each transfer that they need +to perform and copy the data to and from the message blocks. .Pp Device drivers should not use .Xr desballoc 9F @@ -663,24 +704,26 @@ by the controller or belong to the controller outside of the boundaries of a given call to one of the transfer functions and its corresponding callback. .Ss Endpoint Timeouts -The host controller is in charge of watching I/Os for timeouts. For any -request that's not periodic (an interrupt-IN or isochronous-IN) -transfer, the host controller must set up a timeout handler. If that -timeout expires, it needs to stop the endpoint, remove that request, and +The host controller is in charge of watching I/Os for timeouts. +For any request that's not periodic (an interrupt-IN or isochronous-IN) +transfer, the host controller must set up a timeout handler. +If that timeout expires, it needs to stop the endpoint, remove that request, and return to the caller. .Pp -The timeouts are specified in seconds in the request structures. For -bulk timeouts, the request is in the +The timeouts are specified in seconds in the request structures. +For bulk timeouts, the request is in the .Sy bulk_timeout member of the .Xr usb_bulk_req 9S -structure. The interrupt and control transfers also have a similar -member in their request structures, see +structure. +The interrupt and control transfers also have a similar member in their request +structures, see .Xr usb_intr_req 9S and .Xr usb_ctrl_req 9S . If any of the times is set to zero, the default USBA timeout should be -used. In that case, drivers should set the value to the macro +used. +In that case, drivers should set the value to the macro .Sy HCDI_DEFAULT_TIMEOUT , which is a time in seconds. .Pp @@ -695,12 +738,14 @@ on those transfers. .Pp The exact means of performing the timeout is best left to the driver writer as the way that hardware exposes scheduling of different -endpoints will vary. One strategy to consider is to use the +endpoints will vary. +One strategy to consider is to use the .Xr timeout 9F function at a one second period while I/O is ongoing on a per-endpoint -basis. Because the time is measured in seconds, a driver writer can -decrement a counter for a given outstanding transfer once a second and -then if it reaches zero, interject and stop the endpoint and clean up. +basis. +Because the time is measured in seconds, a driver writer can decrement a counter +for a given outstanding transfer once a second and then if it reaches zero, +interject and stop the endpoint and clean up. .Pp This has the added benefit that when no I/O is scheduled, then there will be no timer activity, reducing overall system load. @@ -709,68 +754,82 @@ The following are data structures and types that are used throughout host controller drivers: .Bl -tag -width Vt .It Sy usb_cfg_descr -The configuration descriptor. A device may have one or more -configurations that it supports that can be switched between. The -descriptor is documented in +The configuration descriptor. +A device may have one or more configurations that it supports that can be +switched between. +The descriptor is documented in .Xr usb_cfg_descr 9S . .It Sy usb_dev_descr -The device descriptor. A device descriptor contains basic properties of -the device such as the USB version, device and vendor information, and -the maximum packet size. This will often be used when setting up a -device for the first time. It is documented in +The device descriptor. +A device descriptor contains basic properties of the device such as the USB +version, device and vendor information, and the maximum packet size. +This will often be used when setting up a device for the first time. +It is documented in .Xr usb_dev_descr 9S . .It Sy usb_ep_descr -The endpoint descriptor. An endpoint descriptor contains the basic -properties of an endpoints such as its type and packet size. Every -endpoint on a given USB device has an endpoint descriptor. It is -documented in +The endpoint descriptor. +An endpoint descriptor contains the basic properties of an endpoints such as its +type and packet size. +Every endpoint on a given USB device has an endpoint descriptor. +It is documented in .Xr usb_ep_descr 9S . .It Sy usb_xep_descr -The extended endpoint descriptor. This structure is used to contain the -endpoint descriptor, but also additional endpoint companion descriptors -which are a part of newer USB standards. It is documented in +The extended endpoint descriptor. +This structure is used to contain the endpoint descriptor, but also additional +endpoint companion descriptors which are a part of newer USB standards. +It is documented in .Xr usb_ep_xdescr 9S . .It Sy usb_bulk_req This structure is filled out by client device drivers that want to make -a bulk transfer request. Host controllers use this and act on it to -perform bulk transfers to USB devices. The structure is documented in +a bulk transfer request. +Host controllers use this and act on it to perform bulk transfers to USB +devices. +The structure is documented in .Xr usb_bulk_req 9S . .It Sy usb_ctrl_req This structure is filled out by client device drivers that want to make -a control transfer request. Host controllers use this and act on it to -perform bulk transfers to USB devices. The structure is documented in +a control transfer request. +Host controllers use this and act on it to perform bulk transfers to USB +devices. +The structure is documented in .Xr usb_ctrl_req 9S . .It Sy usb_intr_req This structure is filled out by client device drivers that want to make -an interrupt transfer request. Host controllers use this and act on it to -perform bulk transfers to USB devices. The structure is documented in +an interrupt transfer request. +Host controllers use this and act on it to perform bulk transfers to USB +devices. +The structure is documented in .Xr usb_intr_req 9S . .It Sy usb_isoc_req This structure is filled out by client device drivers that want to make -an isochronous transfer request. Host controllers use this and act on it to -perform bulk transfers to USB devices. The structure is documented in +an isochronous transfer request. +Host controllers use this and act on it to perform bulk transfers to USB +devices. +The structure is documented in .Xr usb_isoc_req 9S . .It Vt usb_flags_t -These define a set of flags that are used on certain entry points. These -generally determine whether or not the entry points should block for -memory allocation. Individual manual pages indicate the flags that -drivers should consult. +These define a set of flags that are used on certain entry points. +These generally determine whether or not the entry points should block for +memory allocation. +Individual manual pages indicate the flags that drivers should consult. .It Vt usb_port_status_t The .Sy usb_port_status_t -determines the current negotiated speed of the device. The following are -valid values that this may be: +determines the current negotiated speed of the device. +The following are valid values that this may be: .Bl -tag -width Sy .It Sy USBA_LOW_SPEED_DEV -The device is running as a low speed device. This may be a USB 1.x or -USB 2.0 device. +The device is running as a low speed device. +This may be a USB 1.x or USB 2.0 device. .It Sy USBA_FULL_SPEED_DEV -The device is running as a full speed device. This may be a USB 1.x or -USB 2.0 device. +The device is running as a full speed device. +This may be a USB 1.x or USB 2.0 device. .It Sy USBA_HIGH_SPEED_DEV -The device is running as a high speed device. This is a USB 2.x device. +The device is running as a high speed device. +This is a USB 2.x device. .It Sy USBA_SUPER_SPEED_DEV -The device is running as a super speed device. This is a USB 3.0 device. +The device is running as a super speed device. +This is a USB 3.0 device. .It Vt usb_cr_t This is a set of codes that may be returned as a part of the call to .Xr usb_hcdi_cb 9F . @@ -780,8 +839,8 @@ control headers. .El .Ss Interrupts While some hardware supports more than one interrupt queue, a single -interrupt is generally sufficient for most host controllers. If the -controller supports interrupt coalescing, then the driver should +interrupt is generally sufficient for most host controllers. +If the controller supports interrupt coalescing, then the driver should generally enable it and set it to a moderate rate. .Ss driver.conf considerations Due to the way host controller drivers need to interact with hotplug, @@ -830,7 +889,6 @@ file. .Xr usba_hubdi_ioctl 9F , .Xr usba_hubdi_open 9F , .Xr usba_hubdi_unbind_root_hub 9F , -.Xr usb_hcdi_bind_root_hub 9F. , .Xr cb_ops 9S , .Xr dev_ops 9S , .Xr mblk 9S , diff --git a/usr/src/man/man9e/usba_hcdi_cb_ops.9e b/usr/src/man/man9e/usba_hcdi_cb_ops.9e index a7ea0555aa..14bceaaae1 100644 --- a/usr/src/man/man9e/usba_hcdi_cb_ops.9e +++ b/usr/src/man/man9e/usba_hcdi_cb_ops.9e @@ -69,7 +69,8 @@ The entry points listed here are the traditional character device .Xr ioctl 9E , and .Xr close 9E -entry points. As discussed in +entry points. +As discussed in .Xr usba_hcdi 9E all HCD drivers are required to implement these functions and vector them to @@ -77,8 +78,9 @@ them to .Xr usba_hubdi_ioctl 9F , and .Xr usba_hubdi_close 9F -respectively. For background information on these functions and how they -interact in the broader operating system, please see the general manual pages +respectively. +For background information on these functions and how they interact in the +broader operating system, please see the general manual pages .Xr open 9E , .Xr ioctl 9E , and @@ -91,8 +93,8 @@ section provides a sketch for how most HCD drivers should perform those transformations. .Pp One important distinction from the traditional character routines is -that the USBA controls a bit more of the minor space. Therefore, the -driver needs to take extra care around the values encoded in the +that the USBA controls a bit more of the minor space. +Therefore, the driver needs to take extra care around the values encoded in the .Sy dev_t and it should not perform any cloning or renumbering in its .Xr open 9E @@ -100,13 +102,14 @@ entry point. .Sh EXAMPLES The following example is adapated from the .Xr xhci 7D -driver which shows how an HCD driver might arrange things. This assumes -that a driver is following the recommendations in +driver which shows how an HCD driver might arrange things. +This assumes that a driver is following the recommendations in .Xr usba_hcdi 9E and has initialized a soft state structure through the .Xr ddi_soft_state_init 9F -function. This design also requires that the soft state structure -contains a pointer to the +function. +This design also requires that the soft state structure contains a pointer to +the .Sy dev_info_t structure during its .Xr attach 9E callback. diff --git a/usr/src/man/man9e/usba_hcdi_device_address.9e b/usr/src/man/man9e/usba_hcdi_device_address.9e index 8baf679752..c39fbd2e93 100644 --- a/usr/src/man/man9e/usba_hcdi_device_address.9e +++ b/usr/src/man/man9e/usba_hcdi_device_address.9e @@ -27,12 +27,13 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ud -Pointer to a USB device structure being updated. See +Pointer to a USB device structure being updated. +See .Xr usba_device 9S for more information. .El @@ -41,10 +42,12 @@ The .Fn usba_hcdi_device_address entry point is an optional entry point for USB host controller drivers. Some USB host controllers do not allow the USB SET_ADDRESS command to be -issued to a device. Instead, they will be responsible for setting the -address in a controller-specific way. If the host controller driver -requires this behavior, then it must implement this function. Otherwise, -if the host controller does not require this functionality, it should +issued to a device. +Instead, they will be responsible for setting the address in a +controller-specific way. +If the host controller driver requires this behavior, then it must implement +this function. +Otherwise, if the host controller does not require this functionality, it should set the entry point in the .Xr usba_hcdi_ops 9S structure to @@ -52,15 +55,15 @@ structure to .Pp The USBA will always set an address for the USBA device .Fa ud -regardless of whether or not this function is implemented. If the HCD -implements this entry point and it needs the addressing information for -whatever reason, then it is the responsibility of the driver to keep +regardless of whether or not this function is implemented. +If the HCD implements this entry point and it needs the addressing information +for whatever reason, then it is the responsibility of the driver to keep track of it separately. .Pp This entry point will be called after the .Xr usba_hcdi_device_init 9E -entry point has been called. Any private data stored on the device will -be available through the +entry point has been called. +Any private data stored on the device will be available through the .Xr usba_hcdi_get_device_private 9F function. .Pp @@ -74,7 +77,8 @@ Upon successful completion, the .Fn usba_hcdi_device_address function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi_device_init 9E , diff --git a/usr/src/man/man9e/usba_hcdi_device_init.9e b/usr/src/man/man9e/usba_hcdi_device_init.9e index 932586b3c5..a7f195beb7 100644 --- a/usr/src/man/man9e/usba_hcdi_device_init.9e +++ b/usr/src/man/man9e/usba_hcdi_device_init.9e @@ -36,8 +36,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa usb_device @@ -53,33 +53,35 @@ Pointer to the HCD driver's private data for the device. .Sh DESCRIPTION The .Fn usba_hcdi_device_init -entry point is an optional entry point. It will be called when child -devices of the root hub are being initialized. A call to this entry -point will occur before any calls to open a pipe to the child device -through the +entry point is an optional entry point. +It will be called when child devices of the root hub are being initialized. +A call to this entry point will occur before any calls to open a pipe to the +child device through the .Xr usba_hcdi_pipe_open 9E entry point. .Pp During this time, the HCD driver should do any required initialization -required by the host controller. The HCD may also opt to store private -data for this device as a result of whatever initialization it -performed. The data should be stored in the +required by the host controller. +The HCD may also opt to store private data for this device as a result of +whatever initialization it performed. +The data should be stored in the .Fa hcd_privatep -pointer. Data stored this will be accessible to the HCD driver through -the +pointer. +Data stored this will be accessible to the HCD driver through the .Xr usba_hcdi_get_device_private 9F function. .Pp The .Fn usba_hcdi_device_fini -entry point is an optional entry point. It will be called when child -devices of the root hub are being removed. The HCD should perform any -necessary work with the root controller to finish tearing down the -device. In addition, if the HCD stored private data it will a pointer to -it in the +entry point is an optional entry point. +It will be called when child devices of the root hub are being removed. +The HCD should perform any necessary work with the root controller to finish +tearing down the device. +In addition, if the HCD stored private data it will a pointer to it in the .Fa hcd_private -pointer. The HCD driver must release any resources associated with its -private data. If it does not, the resources will be leaked. +pointer. +The HCD driver must release any resources associated with its private data. +If it does not, the resources will be leaked. .Pp At the time .Fn usba_hcdi_device_fini @@ -90,8 +92,9 @@ function. The HCD driver is guaranteed that no other entry points will be invoked for the USB device .Fa usb_device -while a call to either function is ongoing. However, the entry point may -be called in parallel on behalf of separate devices. +while a call to either function is ongoing. +However, the entry point may be called in parallel on behalf of separate +devices. .Sh CONTEXT This function is called from kernel context only. .Sh RETURN VALUES diff --git a/usr/src/man/man9e/usba_hcdi_hub_update.9e b/usr/src/man/man9e/usba_hcdi_hub_update.9e index 141b296580..d9dca82f9b 100644 --- a/usr/src/man/man9e/usba_hcdi_hub_update.9e +++ b/usr/src/man/man9e/usba_hcdi_hub_update.9e @@ -29,12 +29,13 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ud -Pointer to a USB device structure being updated. See +Pointer to a USB device structure being updated. +See .Xr usba_device 9S for more information. .It Fa nports @@ -49,9 +50,9 @@ The entry point is an optional entry point for USB host controller drivers. It is used by some controllers to allow them to update information about a device in the controller after a device has been determined to be a -hub during enumeration. If a host controller does not need to take any -specific action after enumerating a hub, then it should simply set this -entry point in the +hub during enumeration. +If a host controller does not need to take any specific action after enumerating +a hub, then it should simply set this entry point in the .Xr usba_hcdi_ops 9S structure to .Dv NULL . @@ -61,14 +62,14 @@ The and .Fa tt members provide relevant information from the device's hub class -descriptor which can be used to help program the host controller. Any -programming should be performed synchronously and be completed before +descriptor which can be used to help program the host controller. +Any programming should be performed synchronously and be completed before this function returns. .Pp This function will be called after .Xr usba_hcdi_device_init 9E -has been called. Any private data registered with that function will be -available. +has been called. +Any private data registered with that function will be available. .Pp If this function fails, the enumeration of this device will fail, the hub driver will not attach to this USB device, and all devices plugged @@ -80,7 +81,8 @@ Upon successful completion, the .Fn usba_hcdi_hub_update function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi_device_init 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e index 67db98717a..fe952224d1 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e @@ -29,27 +29,28 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa ubrp -A pointer to a USB bulk transfer request. The structure's members are -documented in +A pointer to a USB bulk transfer request. +The structure's members are documented in .Xr usb_bulk_req 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -69,13 +70,14 @@ For more background on transfer types, see .Xr usba_hcdi 9E . .Pp The host controller driver should first check the USB address of the -pipe handle. It may correspond to the root hub. If it does, the driver -should return +pipe handle. +It may correspond to the root hub. +If it does, the driver should return .Sy USB_NOT_SUPPORTED . .Pp -Bulk transfers may send data to the device or receive data from the -device. A given bulk endpoint is uni-directional. The direction can be -determined from the endpoint address based on the +Bulk transfers may send data to the device or receive data from the device. +A given bulk endpoint is uni-directional. +The direction can be determined from the endpoint address based on the .Sy p_ep member of .Fa ubrp . @@ -84,8 +86,8 @@ See for more information on how to determine the direction of the endpoint. .Pp The device driver should allocate memory, whether memory suitable for a -DMA transfer or otherwise, to perform the transfer. For all memory -allocated, it should honor the values in +DMA transfer or otherwise, to perform the transfer. +For all memory allocated, it should honor the values in .Fa usb_flags to determine whether or not it should block for allocations. .Pp @@ -95,7 +97,8 @@ and .Sy bulk_data members of .Fa ubrp -respectively. The +respectively. +The .Xr mblk 9S structure that should not be used directly and data should be copied to or from the data buffer that will go the controller. @@ -112,8 +115,8 @@ it still must call .Xr usba_hcdi_cb 9F and should specify an error there. .Pp -It is the driver's responsibility to time out bulk transfer -requests. If the timeout in the request as indicated in the +It is the driver's responsibility to time out bulk transfer requests. +If the timeout in the request as indicated in the .Sy bulk_timeout member of .Fa ubrp @@ -166,7 +169,8 @@ Upon successful completion, the .Fn usba_hcdi_pipe_bulk_xfer function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e index 8d4788bc51..bcff5d6fc5 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e @@ -29,27 +29,28 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa ucrp -A pointer to a USB control transfer request. The structure's members are -documented in +A pointer to a USB control transfer request. +The structure's members are documented in .Xr usb_ctrl_req 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -69,20 +70,23 @@ For more background on transfer types, see .Xr usba_hcdi 9E . .Pp The host controller driver should first check the USB address of the -pipe handle. It may correspond to the root hub. If it does, rather than -initiating an I/O transfer, the driver may need to emulate it using -available information. +pipe handle. +It may correspond to the root hub. +If it does, rather than initiating an I/O transfer, the driver may need to +emulate it using available information. .Pp -Control endpoints are always bi-directional. A given endpoint may -perform transfer data from the OS to the device, or from the device to -the OS. The driver will need to look at the control transfer request and -transform that into the appropriate format for the controller. +Control endpoints are always bi-directional. +A given endpoint may perform transfer data from the OS to the device, or from +the device to the OS. +The driver will need to look at the control transfer request and transform that +into the appropriate format for the controller. .Pp -Control transfers are made up of three parts. A setup stage, an optional -data stage, and a status stage. Depending on the controller, the driver -may need to transform the transfer request into a format that matches -this. Refer to the device's controller specification for more -information on whether this is required or not. +Control transfers are made up of three parts. +A setup stage, an optional data stage, and a status stage. +Depending on the controller, the driver may need to transform the transfer +request into a format that matches this. +Refer to the device's controller specification for more information on whether +this is required or not. .Pp The device driver should a request based on the information present in the control request @@ -92,8 +96,8 @@ If there is a non-zero length for the transfer, indicated by the member of .Fa ucrp being greater than zero, then the controller needs to allocate a -separate memory buffer for the request. The corresponding data will be -found in an +separate memory buffer for the request. +The corresponding data will be found in an .Xr mblk 9S structure as the .Sy ctrl_data @@ -103,10 +107,11 @@ member of If this transfer needs to be sent to a device through the controller and is not being handled directly by the driver, then the driver should allocate a separate region of memory (generally memory suitable for a -DMA transfer) for the transfer. If sending data to the device, the data -in the message block should be copied prior to the transfer. Otherwise, -once the transfer completes, data should be transferred into the message -block and the write pointer incremented. +DMA transfer) for the transfer. +If sending data to the device, the data in the message block should be copied +prior to the transfer. +Otherwise, once the transfer completes, data should be transferred into the +message block and the write pointer incremented. .Pp If the driver needs to allocate memory for this transfer, it should honor the values set in @@ -121,14 +126,14 @@ If the driver returns successfully, it must call .Xr usba_hcdi_cb 9F with .Fa ucrp -either before or after it returns. The only times that a driver would -call the callback before the function returns are for requests to the -root hub that it handles inline and does not need to send off -asynchronous activity to the controller. +either before or after it returns. +The only times that a driver would call the callback before the function returns +are for requests to the root hub that it handles inline and does not need to +send off asynchronous activity to the controller. .Pp For asynchronous requests, the controller is also responsible for -timing out the request if it does not complete. If the timeout in the -request as indicated in the +timing out the request if it does not complete. +If the timeout in the request as indicated in the .Sy ctrl_timeout member is set to zero, then the driver should use the USBA default timeout of @@ -179,7 +184,8 @@ Upon successful completion, the .Fn usba_hcdi_pipe_ctrl_xfer function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e index c2031d15f7..033437e0fb 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e @@ -29,27 +29,28 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa uirp -A pointer to a USB interrupt transfer request. The structure's members -are documented in +A pointer to a USB interrupt transfer request. +The structure's members are documented in .Xr usb_intr_req 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -69,24 +70,27 @@ For more background on transfer types, see .Xr usba_hcdi 9E . .Pp The host controller driver should first check the USB address of the -pipe handle. It may correspond to the root hub. If it does, rather than -initiating an I/O transfer, the driver may need to emulate it. +pipe handle. +It may correspond to the root hub. +If it does, rather than initiating an I/O transfer, the driver may need to +emulate it. .Pp -Unlike other transfers, interrupt transfers may be periodic. If the -transfer is meant to be a one-shot, then the +Unlike other transfers, interrupt transfers may be periodic. +If the transfer is meant to be a one-shot, then the .Sy USB_ATTRS_ONE_XFER flag will be set in the .Sy intr_attributes member of the .Fa uirp -structure. If the +structure. +If the .Sy USB_ATTRS_ONE_XFER -flag is not set, then the transfer begins a periodic transfer. Periodic -transfers have different handling and behavior. +flag is not set, then the transfer begins a periodic transfer. +Periodic transfers have different handling and behavior. .Pp -Interrupt transfers may send data to the device or receive data from the -device. A given interrupt endpoint is uni-directional. The direction can -be determined from the endpoint address based on the +Interrupt transfers may send data to the device or receive data from the device. +A given interrupt endpoint is uni-directional. +The direction can be determined from the endpoint address based on the .Sy p_ep member of .Fa ubrp . @@ -95,8 +99,8 @@ See for more information on how to determine the direction of the endpoint. .Pp The device driver should allocate memory, whether memory suitable for a -DMA transfer or otherwise, to perform the transfer. For all memory -allocated, it should honor the values in +DMA transfer or otherwise, to perform the transfer. +For all memory allocated, it should honor the values in .Fa usb_flags to determine whether or not it should block for allocations. .Pp @@ -114,9 +118,9 @@ or from the data buffer that will go the controller. .Pp Unlike bulk and control transfers, the .Fa intr_data -member may not be allocated for interrupt-IN transfers. In such cases, -the device driver is required to allocate the message block through -something like +member may not be allocated for interrupt-IN transfers. +In such cases, the device driver is required to allocate the message block +through something like .Xr allocb 9F and assign it to the .Sy intr_data @@ -135,7 +139,8 @@ it still must call and should specify an error there. .Pp It is the driver's responsibility to time out one-shot interrupt transfer -requests. If the timeout in the request as indicated in the +requests. +If the timeout in the request as indicated in the .Sy intr_timeout member of .Fa uirp @@ -147,16 +152,18 @@ All timeout values are in When the .Sy USB_ATTRS_ONE_XFER flag is not present, it indicates that a periodic interrupt transfer is -being initiated. Once a periodic interrupt transfer is initiated, every -time data is received the driver should call +being initiated. +Once a periodic interrupt transfer is initiated, every time data is received the +driver should call .Xr usba_hcdi_cb 9F with the updated data. .Pp When a periodic transfer is initiated, many controller drivers will -allocate multiple transfers up front and schedule them all. Many drivers -do this to ensure that data isn't lost between servicing the first -transfer and scheduling the next. The number of such transfers used -depends on the polling frequency specified in the endpoint descriptor. +allocate multiple transfers up front and schedule them all. +Many drivers do this to ensure that data isn't lost between servicing the first +transfer and scheduling the next. +The number of such transfers used depends on the polling frequency specified in +the endpoint descriptor. .Pp Unless an error occurs, the driver must not use the original interrupt request, @@ -182,7 +189,8 @@ A request to close the pipe came in from the .Xr usba_hcdi_pipe_close 9E entry point. .It -An out of memory condition occurred. The caller should call +An out of memory condition occurred. +The caller should call .Xr usba_hcdi_cb 9F with the code .Sy USB_CR_NO_RESOURCES . @@ -192,7 +200,8 @@ Some other transfer error occurred. .Pp If the periodic interrupt transfer is for the root hub, the driver will need to emulate the behavior of a hub as specified in the USB -specification. For more information, see the +specification. +For more information, see the .Sx Root Hub Management section in .Xr usba_hcdi 9E . @@ -201,7 +210,8 @@ When the interrupt transfer completes, the driver should consider the following items to determine what actions it should take on the callback: .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Bl -bullet .It @@ -247,7 +257,8 @@ Upon successful completion, the function should return function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e index 7de6946a77..a1b90640b3 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e @@ -29,27 +29,28 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa usrp -A pointer to a USB isochronous transfer request. The structure's members -are documented in +A pointer to a USB isochronous transfer request. +The structure's members are documented in .Xr usb_isoc_req 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -69,31 +70,35 @@ For more background on transfer types, see .Xr usba_hcdi 9E . .Pp The host controller driver should first check the USB address of the -pipe handle. It may correspond to the root hub. If it does, the driver -should return +pipe handle. +It may correspond to the root hub. +If it does, the driver should return .Sy USB_NOT_SUPPORTED . .Pp -Isochronous transfers happen once a period. Isochronous transfers may -just be told to start as son as possible or to line up to a specific -frame. At this time, nothing in the system uses the later behavior. It -is reasonable for a new driver to require that the +Isochronous transfers happen once a period. +Isochronous transfers may just be told to start as son as possible or to line up +to a specific frame. +At this time, nothing in the system uses the later behavior. +It is reasonable for a new driver to require that the .Sy USB_ATTRS_ISOC_XFER_ASAP flag be set in the .Sy isoc_attributes member of the .Fa usrp -argument. In the case where it's not set and the controller driver does -not support setting the frame, it should return +argument. +In the case where it's not set and the controller driver does not support +setting the frame, it should return .Sy USB_NOT_SUPPORTED . .Pp Isochronous-IN transfers are .Em always periodic . -Isochronous-OUT transfers are one shot transfers. Periodic transfers -have slightly different handling and behavior. +Isochronous-OUT transfers are one shot transfers. +Periodic transfers have slightly different handling and behavior. .Pp Isochronous transfers may send data to the device or receive data from -the device. A given isochronous endpoint is uni-directional. The -direction can be determined from the endpoint address based on the +the device. +A given isochronous endpoint is uni-directional. +The direction can be determined from the endpoint address based on the .Sy p_ep member of .Fa ubrp . @@ -105,23 +110,24 @@ Isochronous transfers are a little bit different from other transfers. While there is still a single .Xr mblk 9S structure that all the data goes to or from, the transfer may be broken -up into multiple packets. All of these packets make up a single transfer -request and each one represents the data that is transferred during a -single portion of a frame. For the description of them, see +up into multiple packets. +All of these packets make up a single transfer request and each one represents +the data that is transferred during a single portion of a frame. +For the description of them, see .Xr usb_isoc_req 9S . Because of these data structures, the way that transfers are recorded is different and will be discussed later on. .Pp The device driver should allocate memory, whether memory suitable for a -DMA transfer or otherwise, to perform the transfer. For all memory -allocated, it should honor the values in +DMA transfer or otherwise, to perform the transfer. +For all memory allocated, it should honor the values in .Fa usb_flags to determine whether or not it should block for allocations. .Pp For isochronous-out transfers which are one-shot transfers, the driver should verify that the sum of all of the individual packet counts -matches the message block length of the data. If it does not, then the -driver should return +matches the message block length of the data. +If it does not, then the driver should return .Sy USB_INVALID_ARGS . .Pp If the driver successfully schedules the I/O, then it should return @@ -141,17 +147,18 @@ As there is no timeout member in the isochronous request structure, then the timeout should be set to .Sy HCDI_DEFAULT_TIMEOUT . .Ss Periodic Transfers -All isochronous-in transfers are periodic transfers. Once a periodic -transfer is initiated, every time data is received the driver should -call the +All isochronous-in transfers are periodic transfers. +Once a periodic transfer is initiated, every time data is received the driver +should call the .Xr usba_hcdi_cb 9F function with updated data. .Pp When a periodic transfer is initiated, many controller drivers will -allocate multiple transfers up front and schedule them all. Many drivers -do this to ensure that data isn't lost between servicing the first -transfer and scheduling the next. The number of such transfers used -depends on the polling frequency specified in the endpoint descriptor. +allocate multiple transfers up front and schedule them all. +Many drivers do this to ensure that data isn't lost between servicing the first +transfer and scheduling the next. +The number of such transfers used depends on the polling frequency specified in +the endpoint descriptor. .Pp Unless an error occurs, the driver must not use the original isochronous request, @@ -177,7 +184,8 @@ A request to close the pipe came in from the .Xr usba_hcdi_pipe_close 9E entry point. .It -An out of memory condition occurred. The caller should call +An out of memory condition occurred. +The caller should call .Xr usba_hcdi_cb 9F with the code .Sy USB_CR_NO_RESOURCES . @@ -189,7 +197,8 @@ When the isochronous transfer completes, the driver should consider the following items to determine what actions it should take on the callback: .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Bl -bullet .It @@ -243,7 +252,8 @@ Upon successful completion, the function should return function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_open.9e b/usr/src/man/man9e/usba_hcdi_pipe_open.9e index 78dc276209..efe1d12520 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_open.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_open.9e @@ -34,23 +34,24 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -63,14 +64,14 @@ The and .Fn usba_hcdi_pipe_close entry points are called by the USB framework whenever a client, or the -framework itself, need to open or close a specific pipe. For additional -background see +framework itself, need to open or close a specific pipe. +For additional background see .Xr usba_hcdi 9E . .Pp When a pipe is opened, the host controller driver is responsible for -preparing the specified endpoint for performing transfers. This may -include allocating bandwidth, programming the controller, and more. When -the pipe is closed, the host controller driver is responsible for +preparing the specified endpoint for performing transfers. +This may include allocating bandwidth, programming the controller, and more. +When the pipe is closed, the host controller driver is responsible for cleaning up any resources that were allocated during the open call. .Pp The pipe handle, @@ -78,16 +79,20 @@ The pipe handle, identifies the endpoint that it the USBA is trying to open or close through its endpoint descriptor in the .Sy p_ep -member. The endpoint descriptor is described in +member. +The endpoint descriptor is described in .Xr usb_ep_descr 9S . From the endpoint descriptor the driver can determine the type of endpoint, what the address of the endpoint is, and what direction the -endpoint is in. When combined, these uniquely describe the pipe. +endpoint is in. +When combined, these uniquely describe the pipe. .Pp To open a pipe, the driver may need additional companion endpoint -descriptors. If these are available, they will be in the +descriptors. +If these are available, they will be in the .Sy p_xep -member of the pipe handle. See +member of the pipe handle. +See .Xr usb_ep_xdescr 9S for more information on how to determine which descriptors are present and get the information encoded in them. @@ -95,31 +100,34 @@ and get the information encoded in them. Host controller drviers should check the USB address of the USB device that .Fa ph -belongs to. The driver may be asked to open a pipe to the root hub. As -the root hub is often sythetic, the driver man need to take a different +belongs to. +The driver may be asked to open a pipe to the root hub. +As the root hub is often sythetic, the driver man need to take a different path than normal. .Ss Pipe open specifics -A given endpoint on a device can only be opened once. If there's a -request to open an already open endpoint, then the request to open the -pipe should be failed. +A given endpoint on a device can only be opened once. +If there's a request to open an already open endpoint, then the request to open +the pipe should be failed. .Pp By the time the call to open a pipe returns, the driver should expect that any of the pipe transfer or reset entry points will be called on the pipe. .Pp -A driver can establish private data on an endpoint. During pipe open it -may set the +A driver can establish private data on an endpoint. +During pipe open it may set the .Sy p_hcd_private -member to any value. Generally this points to an allocated structure -that contains data specific to the host controller. This value will -remain on the pipe handle. It is the responsibility of the driver to -clear the data when the pipe is closed. +member to any value. +Generally this points to an allocated structure that contains data specific to +the host controller. +This value will remain on the pipe handle. +It is the responsibility of the driver to clear the data when the pipe is +closed. .Ss Pipe close specifics When a pipe is closed, the driver must clean up all of the resources -that it allocated when opening the pipe. For non-periodic transfers, the -host controller driver may assueme that there are no outstanding -transfers that need to be cleaned up. However, the same is not true for -periodic pipes. +that it allocated when opening the pipe. +For non-periodic transfers, the host controller driver may assueme that there +are no outstanding transfers that need to be cleaned up. +However, the same is not true for periodic pipes. .Pp For pipes that have outstanding periodic transfers, the host controller driver needs to clean them up and quiesce them as though a call to @@ -144,7 +152,8 @@ and .Fn uba_hcdi_pipe_close functions should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_reset.9e b/usr/src/man/man9e/usba_hcdi_pipe_reset.9e index 7c883c86d1..0b02465039 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_reset.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_reset.9e @@ -28,23 +28,24 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -63,15 +64,17 @@ and .Xr usba_hcdi_stop_isoc_polling 9E entry points, there are some notable differences. .Pp -This entry point is synchronous. The host controller driver should take -the following steps on the pipe before returning: +This entry point is synchronous. +The host controller driver should take the following steps on the pipe before +returning: .Bl -enum .It Quiesce and stop the endpoint. .It If the endpoint has any errors they should be cleared at this time. .It -Remove any remaining, scheduled or queued transfers. For each one call +Remove any remaining, scheduled or queued transfers. +For each one call .Xr usba_hcdi_cb 9F with the code .Sy USB_CR_PIPE_RESET . @@ -87,7 +90,8 @@ Upon successful completion, the .Fn usba_hcdi_pipe_reset function should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi_pipe_open 9E , diff --git a/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e b/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e index 62e1783510..f22da89e94 100644 --- a/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e +++ b/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e @@ -34,23 +34,24 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to a USB pipe handle as defined in .Xr usba_pipe_handle_data 9S . .It Fa usb_flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -77,15 +78,16 @@ there are outstanding transfers. For interrupt transfers, .Fa ph , may refer to the root hub and so the driver may need to cease any -synthetic polling it is performing. Isochronous transfers are forbidden -on the root hub, so the +synthetic polling it is performing. +Isochronous transfers are forbidden on the root hub, so the .Fn usba_hcdi_pipe_stop_isoc_polling will only be called on a pipe that corresponds to an actual device. .Pp These functions are .Em synchronous -requests. In all cases, the driver should take the following steps -before returning from these entry points: +requests. +In all cases, the driver should take the following steps before returning from +these entry points: .Bl -enum .It Quiesce and stop the endpoint. @@ -97,8 +99,8 @@ Call on the original interrupt or isochronous request with the code .Sy USB_CR_STOPPED_POLLING . .It -Optionally, free all associated resources. If resources aren't freed -at this time, they must be freed when +Optionally, free all associated resources. +If resources aren't freed at this time, they must be freed when .Xr usba_hcdi_pipe_close 9E is called. .It @@ -109,8 +111,9 @@ transfers on this endpoint again may be enabled. It is possible that this function may be called concurrently with a call to the .Xr usba_hcdi_pipe_reset 9E -entry point. In such cases, the host controller driver is required to -perform synchronization on its data structures. +entry point. +In such cases, the host controller driver is required to perform synchronization +on its data structures. .Sh RETURN VALUES Upon successful completion, the .Fn usba_hcdi_pipe_stop_intr_polling @@ -118,7 +121,8 @@ and .Fn uba_hcdi_pipe_stop_isoc_polling functions should return .Sy USB_SUCCESS . -Otherwise, it should return the appropriate USB error. If uncertain, use +Otherwise, it should return the appropriate USB error. +If uncertain, use .Sy USB_FAILURE . .Sh SEE ALSO .Xr usba_hcdi_pipe_close 9E , diff --git a/usr/src/man/man9f/avl.9f b/usr/src/man/man9f/avl.9f index 4e7f594730..761248019a 100644 --- a/usr/src/man/man9f/avl.9f +++ b/usr/src/man/man9f/avl.9f @@ -31,7 +31,7 @@ .Nm avl_remove , .Nm avl_swap , .Nm AVL_NEXT , -.Nm AVL_PREV , +.Nm AVL_PREV .Nd AVL tree routines .Sh DESCRIPTION AVL trees are a general purpose, self-balancing binary tree that can be @@ -44,10 +44,10 @@ The AVL tree interfaces are identical in both userland and the kernel. For more general information on AVL trees, see .Xr libavl 3LIB . For more information on any of the funtions defined here, please see the -corresponding manual page in section 3AVL. Please note, that while -the descriptions in those manual pages are accurate for writers of -Device Drivers, the examples provided use scaffolding not available in -the kernel, such as the use of +corresponding manual page in section 3AVL. +Please note, that while the descriptions in those manual pages are accurate for +writers of Device Drivers, the examples provided use scaffolding not available +in the kernel, such as the use of .Fn malloc , and need to be adapated. .Sh CONTEXT @@ -62,7 +62,8 @@ in .Sy Committed .Sh MT-Safety AVL trees do not inherently have any internal locking, it is up to the -consumer to use locks as appropriate. See +consumer to use locks as appropriate. +See .Xr mutex 9F and .Xr rwlock 9F diff --git a/usr/src/man/man9f/cmn_err.9f b/usr/src/man/man9f/cmn_err.9f index e7fe3b544c..9b620c7ff4 100644 --- a/usr/src/man/man9f/cmn_err.9f +++ b/usr/src/man/man9f/cmn_err.9f @@ -296,7 +296,8 @@ The function can be called from user, kernel, interrupt, or high-level interrupt context. .Sh RETURN VALUES -None. However, if an unknown +None. +However, if an unknown .Fa level is passed to .Fn cmn_err , diff --git a/usr/src/man/man9f/id_space.9f b/usr/src/man/man9f/id_space.9f index c077fd9434..4f8f953a31 100644 --- a/usr/src/man/man9f/id_space.9f +++ b/usr/src/man/man9f/id_space.9f @@ -84,31 +84,34 @@ An identifier, a signed 32-bit integer. .It Fa name An ASCII character string to call the identifier space. .It Fa low -The lower end of an identifier space. This value is included in the -range. +The lower end of an identifier space. +This value is included in the range. .It Fa high -The upper end of an identifier space. This value is excluded from the -range. +The upper end of an identifier space. +This value is excluded from the range. .El .Sh DESCRIPTION The .Sy id_space -suite of functions is used to create and manage identifier spaces. An -identifier space allows the system to manage a range of identifiers. It -tracks what values have been used and which values have not been used +suite of functions is used to create and manage identifier spaces. +An identifier space allows the system to manage a range of identifiers. +It tracks what values have been used and which values have not been used and has different ways of allocating values from the identifier space. .Pp Identifier spaces are often used by device drivers to manage ranges of -numeric identifiers that may be disjoint. A common use case for -identifier spaces is to manage the set of allocated minor numbers for a -device driver. +numeric identifiers that may be disjoint. +A common use case for identifier spaces is to manage the set of allocated minor +numbers for a device driver. .Ss Creating, Expanding and Destroying Identifier Spaces To create an identifier space, the .Fn id_space_create -function should be used. A name for the id space must be passed in the +function should be used. +A name for the id space must be passed in the .Fa name -argument. It should be unique. For device drivers, often combining the -name of the driver and the instance from the +argument. +It should be unique. +For device drivers, often combining the name of the driver and the instance from +the .Xr ddi_get_instance 9F function results in a unique name. .Pp @@ -116,9 +119,9 @@ The values of .Fa low and .Fa high -describe the range of the identifier space. The range is inclusive on -the low end and exclusive on the high end. Mathematically, this would be -represented as +describe the range of the identifier space. +The range is inclusive on the low end and exclusive on the high end. +Mathematically, this would be represented as .Pf [ Fa low , .Fa high Ns ). .Pp @@ -128,14 +131,17 @@ function has been successfully called, the returned identifier space can be used to allocate and manage identifiers. .Pp Once an identifier space has been created, additional ranges of -identifiers can be added. This process allows for disjoint ranges of -values to be added to a single identifier space. The +identifiers can be added. +This process allows for disjoint ranges of values to be added to a single +identifier space. +The .Fn id_space_extend function is used to do this, and it adds the range .Fa low to .Fa high -to the identifier space. The range follows the same rules as with the +to the identifier space. +The range follows the same rules as with the .Fn id_space_create function. It is inclusive of @@ -154,36 +160,39 @@ All three of these functions, .Fn id_space_extend , and .Fn id_space_destroy -may block. They should only be called from a context where it's safe for -it to block. This is equivalent to performing a blocking memory allocation. +may block. +They should only be called from a context where it's safe for it to block. +This is equivalent to performing a blocking memory allocation. .Ss Allocating Identifiers Once an id space has been created with the .Fn id_space_create -function, identifiers can be allocated from the space. There are three -different strategies for allocating an identifier: +function, identifiers can be allocated from the space. +There are three different strategies for allocating an identifier: .Bl -enum .It Allocating an identifier using the standard algorithm that attempts to use the next identifier first. .It -Allocating an identifier using a first fit algorithm. These are -functions with +Allocating an identifier using a first fit algorithm. +These are functions with .Em ff -in the name. Using this will tend to keep the allocated id space more -compressed. +in the name. +Using this will tend to keep the allocated id space more compressed. .It Allocating a specific id. .El .Pp In addition, identifiers can be allocated in both a blocking and -non-blocking fashion. When functions with the +non-blocking fashion. +When functions with the .Sy _nosleep -prefix are used, they are non-blocking. If no identifier is available, -they will return an error. +prefix are used, they are non-blocking. +If no identifier is available, they will return an error. .Pp The .Fn id_alloc -function will allocate the next identifier. The +function will allocate the next identifier. +The .Fn id_alloc_nosleep function uses the same algorithm as .Fn id_alloc , @@ -191,7 +200,8 @@ but will fail rather than block. .Pp The .Fn id_allocff -function will allocate the first available identifier. The +function will allocate the first available identifier. +The .Fn id_allocff_nosleep function uses the same algorithm as .Fn id_allocff , @@ -201,12 +211,14 @@ The .Fn id_alloc_specific_nosleep function attempts to allocate the specific identifier .Fa id -from the specified identifier space. If +from the specified identifier space. +If .Fa id has already been allocated, then the function will fail. .Ss Freeing Identifiers Every allocated identifier must eventually be freed and returned to the -identifier space. To free an identifier, use the +identifier space. +To free an identifier, use the .Fn id_free function, specifying the identifier in .Fa id @@ -220,7 +232,8 @@ All of these functions may be called in .Sy user or .Sy kernel -context. The +context. +The .Fn id_alloc_nosleep , .Fn id_allocff_nosleep , and @@ -231,7 +244,8 @@ context. .Sh RETURN VALUES Upon successful completion, the .Fn id_space_create -function returns a pointer to an identifier space. Otherwise, +function returns a pointer to an identifier space. +Otherwise, .Dv NULL is returned to indicate that the identifier space could not be created. .Pp @@ -248,7 +262,8 @@ Upon successful completion, the and .Fn id_alloc_specific_nosleep functions will return an identifier that's in the range of the specified -identifier space. Otherwise, +identifier space. +Otherwise, .Sy -1 is returned to indicate that no identifier was available, or in the case of the diff --git a/usr/src/man/man9f/mac_alloc.9f b/usr/src/man/man9f/mac_alloc.9f index c3c6892b19..e777672a77 100644 --- a/usr/src/man/man9f/mac_alloc.9f +++ b/usr/src/man/man9f/mac_alloc.9f @@ -66,7 +66,7 @@ section of When the driver is done with the .Xr mac_register 9S structure, it must call the -.Xr mac_free +.Xr mac_free 9F function to release any associated memory. .Sh CONTEXT The @@ -85,10 +85,11 @@ Upon successful completion, the .Fn mac_register function will return a pointer to an allocated .Sy mac_register_t -structure that can be filled in by the driver. Otherwise, +structure that can be filled in by the driver. +Otherwise, .Dv NULL -is returned to indicate that the structure could not be allocated. The -most common cause for this is that the value of +is returned to indicate that the structure could not be allocated. +The most common cause for this is that the value of .Fa mac_version is not supported by the kernel. .Sh SEE ALSO diff --git a/usr/src/man/man9f/mac_hcksum_get.9f b/usr/src/man/man9f/mac_hcksum_get.9f index b186890fd1..d6aec5441d 100644 --- a/usr/src/man/man9f/mac_hcksum_get.9f +++ b/usr/src/man/man9f/mac_hcksum_get.9f @@ -51,9 +51,9 @@ The value or a pointer to it that contains the offset from the L3 header, generally IP, of the first byte that's covered by the checksum. .It Fa stuff The value or a pointer to it that contains the offset from the L3 header -of where the L4 checksum is. For example, if using IPv4 and TCP, this -would contain the offset from the start of the IPv4 header to the first -byte of the TCP checksum. +of where the L4 checksum is. +For example, if using IPv4 and TCP, this would contain the offset from the start +of the IPv4 header to the first byte of the TCP checksum. .It Fa end The value or a pointer to it that contains the offset from the L3 header, generally IP, of the last byte that's covered by the checksum. @@ -72,7 +72,8 @@ The and .Fn mac_hcksum_set functions are provided to device drivers to get and set checksum related -information. When a device driver indicates that it supports the +information. +When a device driver indicates that it supports the .Sy MAC_CAPAB_HCKSUM capability as part of its .Xr mc_getcapab 9E @@ -83,11 +84,12 @@ While both functions operate on an .Sy mblk_t , this function should only be called on the first .Sy mblk_t -that begins a given individual frame in a chain. In other words, it only -works on entries where it is the first of many possible entries linked -together by the +that begins a given individual frame in a chain. +In other words, it only works on entries where it is the first of many possible +entries linked together by the .Sy b_cont -member. The first +member. +The first .Sy mblk_t received from any .Xr mac 9E @@ -99,14 +101,15 @@ When a device driver is receiving data, it is its responsibility to .Em set checksum information when it has indicated that it supports the .Sy MAC_CAPAB_HCKSUM -capability. Device drivers will call the +capability. +Device drivers will call the .Fn mac_hcksum_set function to indicate what checksum information has occurred. .Pp -The proper values to set depend on the flags passed in. The following -flags are supported when receiving data, note that they may have -different meanings from when transmitting data. The driver should set -the +The proper values to set depend on the flags passed in. +The following flags are supported when receiving data, note that they may have +different meanings from when transmitting data. +The driver should set the .Fa flags argument to the bitwise inclusive OR of the following values: .Bl -tag -width Sy @@ -125,14 +128,14 @@ and arguments. .It Sy HCK_FULLCKSUM This flag indicates that the hardware has calculated the full L4 header -checksum; however, it wants the system to verify it. The checksum should -be passed in the +checksum; however, it wants the system to verify it. +The checksum should be passed in the .Fa value argument. .It Sy HCK_FULLCKSUM_OK This flag indicates that the hardware has calculated the full L4 header -checksum and verified that it is correct. The networking stack does not -need to verify it. +checksum and verified that it is correct. +The networking stack does not need to verify it. .El .Pp The @@ -140,8 +143,8 @@ The .Sy HCK_FULLCKSUM , and .Sy HCK_FULLCKSUM_OK -flags are all mutually exclusive. A device driver should only set one of -the three flags. +flags are all mutually exclusive. +A device driver should only set one of the three flags. .Pp If one of the arguments is not required based on the specified value of .Fa flags , @@ -154,27 +157,28 @@ supports the capability, then it must call the .Fn mac_hcksum_get function to determine what hardware checksumming options are required to -be performed by the hardware. While the device driver may need the other -fields, it must check the +be performed by the hardware. +While the device driver may need the other fields, it must check the .Fa flags -argument to determine what it is being requested to do. The following -values may be set in +argument to determine what it is being requested to do. +The following values may be set in .Fa flags : .Bl -tag -width Sy .It Sy HCK_IPV4_HDRCKSUM -The device driver must compute the IPv4 header checksum. No other fields -have been filled in. +The device driver must compute the IPv4 header checksum. +No other fields have been filled in. .It Sy HCK_PARTIALCKSUM The device driver needs to compute the partial ones' complement of the -checksum. The system has filled in the +checksum. +The system has filled in the .Fa start , .Fa stuff , and .Fa end arguments to assist the device driver. .It Sy HCK_FULLCKSUM -The device driver should compute the full L4 checksum. No other fields -have been filled in for the device driver. +The device driver should compute the full L4 checksum. +No other fields have been filled in for the device driver. .El .Pp The flags that the device driver will get will depend on what the device diff --git a/usr/src/man/man9f/mac_init_ops.9f b/usr/src/man/man9f/mac_init_ops.9f index a744cddbf8..c3608f89ec 100644 --- a/usr/src/man/man9f/mac_init_ops.9f +++ b/usr/src/man/man9f/mac_init_ops.9f @@ -55,7 +55,8 @@ The .Fn mac_init_ops function should be called during the driver's .Xr _init 9E -entry point. As described in more detail in the +entry point. +As described in more detail in the .Sx Initializing MAC Support section of .Xr mac 9E , @@ -71,8 +72,8 @@ entry point, after the call to .Xr mod_remove 9F has succeeded, then the driver must call the .Fn mac_fini_ops -function to finalize support and finish releasing any resources. If the -call to +function to finalize support and finish releasing any resources. +If the call to .Xr mod_remove 9F fails, then the device driver should not call .Fn mac_fini_ops @@ -105,8 +106,8 @@ The .Fn mac_init_ops and .Fn mac_fini_ops -functions will always succeed. They do not have any kind of return -value. +functions will always succeed. +They do not have any kind of return value. .Sh EXAMPLES The following example shows how a driver would call .Xr mac_init_ops 9F diff --git a/usr/src/man/man9f/mac_link_update.9f b/usr/src/man/man9f/mac_link_update.9f index a7a460dab0..f37990c3c3 100644 --- a/usr/src/man/man9f/mac_link_update.9f +++ b/usr/src/man/man9f/mac_link_update.9f @@ -32,8 +32,8 @@ illumos DDI specific The MAC handle obtained from a call to .Xr mac_register 9F . .It Fa link -The current state of the link. For valid link states see the discussion -of +The current state of the link. +For valid link states see the discussion of .Sy MAC_PROP_STATUS in the .Sx PROPERTIES @@ -44,16 +44,17 @@ section of The .Fn mac_link_update function is used by device drivers to inform the MAC layer that the -state of a link has changed. As discussed in the +state of a link has changed. +As discussed in the .Sx Link Updates section of .Xr mac 9E , the driver should call this whenever it detects that the state of the -link has changed. If the state has not changed, then the driver should -not call this function. In addition, if the device driver is powering -off the link or is transitioning to a state where it can no longer -determine the link status, then it should make sure to call this -function with the value of +link has changed. +If the state has not changed, then the driver should not call this function. +In addition, if the device driver is powering off the link or is transitioning +to a state where it can no longer determine the link status, then it should make +sure to call this function with the value of .Fa link set to .Sy LINK_STATE_UNKNOWN . diff --git a/usr/src/man/man9f/mac_lso_get.9f b/usr/src/man/man9f/mac_lso_get.9f index b8a28c770c..4fd21cf26b 100644 --- a/usr/src/man/man9f/mac_lso_get.9f +++ b/usr/src/man/man9f/mac_lso_get.9f @@ -47,19 +47,20 @@ function is used by device drivers that have indicated that they support the .Sy MAC_CAPAB_LSO capability to determine whether large send offload (also known as large -segmentation offload or LSO) is required for this frame or not. If so, -the driver should take the appropriate actions to program the hardware +segmentation offload or LSO) is required for this frame or not. +If so, the driver should take the appropriate actions to program the hardware to perform LSO. .Pp The .Fn mac_lso_get function should only be called on the first .Sy mblk_t -that begins a given individual frame in a chain. In other words, it only -works on entries where it is the first of many possible entries linked -together by the +that begins a given individual frame in a chain. +In other words, it only works on entries where it is the first of many possible +entries linked together by the .Sy b_cont -member. The first +member. +The first .Sy mblk_t received from any .Xr mac 9E @@ -75,8 +76,8 @@ may be a bitwise inclusive OR of the following: .Bl -tag -width Sy .It Sy HW_LSO This flag indicates that hardware needs to perform segmentation -offload. The maximum segment size that the driver should use is -available through the +offload. +The maximum segment size that the driver should use is available through the .Fa mss argument. .El diff --git a/usr/src/man/man9f/mac_maxsdu_update.9f b/usr/src/man/man9f/mac_maxsdu_update.9f index 297d30ef41..223a2bf608 100644 --- a/usr/src/man/man9f/mac_maxsdu_update.9f +++ b/usr/src/man/man9f/mac_maxsdu_update.9f @@ -41,8 +41,9 @@ function is used to inform the MAC layer that the device represented by the handle .Fa mh has changed the largest size frame that it can transmit, also known as -its Send Data Unit (SDU). This should be called when the device's MTU -has been requested to be changed when a driver's +its Send Data Unit (SDU). +This should be called when the device's MTU has been requested to be changed +when a driver's .Xr mac_setprop 9E entry point has been called with the property .Sy MAC_PROP_MTU @@ -51,13 +52,14 @@ or some other device-related event occurring. The .Fa sdu represents the size of the largest payload ignoring the size of its own -headers or any margin. For example, for an Ethernet-based device, this -size should not include the Ethernet header or any VLAN tags. +headers or any margin. +For example, for an Ethernet-based device, this size should not include the +Ethernet header or any VLAN tags. .Pp Through VNICs and other virtual data links, many different devices may -be using a single physical device and have their own MTUs. The system -takes care of those concerns and will not ask a device driver to update -the MTU without verifying this. +be using a single physical device and have their own MTUs. +The system takes care of those concerns and will not ask a device driver to +update the MTU without verifying this. .Sh RETURN VALUES Upon successful completion, the .Fn mac_maxsdu_update diff --git a/usr/src/man/man9f/mac_prop_info.9f b/usr/src/man/man9f/mac_prop_info.9f index 8b134ddd03..0582665ce3 100644 --- a/usr/src/man/man9f/mac_prop_info.9f +++ b/usr/src/man/man9f/mac_prop_info.9f @@ -69,7 +69,8 @@ illumos DDI specific .It Ft hdl A pointer to the MAC property information handle. .It Ft fctl -A valid link flow control entry. Valid values are documented in the +A valid link flow control entry. +Valid values are documented in the .Sy MAC_PROP_FLOWCTRL property description in the .Sx PROPERTIES @@ -117,18 +118,19 @@ The family of functions are used to fill in metadata about a given property as part of a driver's .Xr mc_propinfo 9E -entry point. These functions can be used to fill in information about -the default value that the device assigns to a property and the -permissions that a privileged user has to update the property. +entry point. +These functions can be used to fill in information about the default value that +the device assigns to a property and the permissions that a privileged user has +to update the property. .Pp The .Fn mac_prop_info_set_perm -function is used to set the permissions of a property. These permissions -indicate whether or not the property can be read or modified from the -device driver's perspective. The permissions for a given property should -generally not change for a given device and they do not need to take -into account user privileges. For the most case, properties will only -take one of two values: +function is used to set the permissions of a property. +These permissions indicate whether or not the property can be read or modified +from the device driver's perspective. +The permissions for a given property should generally not change for a given +device and they do not need to take into account user privileges. +For the most case, properties will only take one of two values: .Sy MAC_PROP_PERM_READ or .Sy MAC_PROP_PERM_RW . @@ -142,8 +144,9 @@ function will override the values stored in previous calls. The .Fn mac_prop_info_set_range_uint32 function is used to indicate a range of possible integer values that a -device may take. This range is generally inclusive, meaning the property -may be set to any value in the range of +device may take. +This range is generally inclusive, meaning the property may be set to any value +in the range of .Fa low to .Fa high . @@ -160,14 +163,16 @@ The remaining functions, .Fn mac_prop_info_set_uint32 , and .Fn mac_prop_info_set_range_uint32 -update the default value of a given property. The default value is the -initial value that the property takes after the device driver has called +update the default value of a given property. +The default value is the initial value that the property takes after the device +driver has called .Xr mac_register 9F . If these functions are called multiple times, then the default value will be replaced with each call. .Pp The different functions each support a different type of default value -and some are used for specific properties. The +and some are used for specific properties. +The .Fn mac_prop_info_set_default_link_flowctrl function works with properties that describe flow control properties. The various values of a @@ -177,8 +182,8 @@ are documented in .Pp The .Fn mac_prop_info_set_default_str -function sets the default value for properties that use strings. The -device driver should ensure that it uses alphanumeric ASCII characters +function sets the default value for properties that use strings. +The device driver should ensure that it uses alphanumeric ASCII characters only in the string to guarantee portability. .Pp The @@ -197,9 +202,9 @@ and .Sy kernel context. .Sh RETURN VALUES -All of the functions documented here do not return a value. It is not -the driver's responsibility to ensure that there is sufficient space for -permissions, ranges, or default values in the +All of the functions documented here do not return a value. +It is not the driver's responsibility to ensure that there is sufficient space +for permissions, ranges, or default values in the .Ft mac_prop_info_handle_t structures: the surrounding driver framework will transparently take care of that and ensure that errors are correctly propagated. diff --git a/usr/src/man/man9f/mac_register.9f b/usr/src/man/man9f/mac_register.9f index 05fe8fc60b..93c5662a61 100644 --- a/usr/src/man/man9f/mac_register.9f +++ b/usr/src/man/man9f/mac_register.9f @@ -49,15 +49,16 @@ The .Fn mac_register function is used to register an instance of a device driver with the .Xr mac 9E -framework. Upon successfully calling the +framework. +Upon successfully calling the .Fn mac_register function, the device will start having its .Xr mac_callbacks 9S -entry points called. The device driver should call this function -during it's +entry points called. +The device driver should call this function during it's .Xr attach 9E -entry point after the device has been configured and is set up. For a -more detailed explanation of the exact steps that the device driver +entry point after the device has been configured and is set up. +For a more detailed explanation of the exact steps that the device driver should take and where in the sequence of a driver's .Xr attach 9E entry point this function should be called, see the @@ -69,14 +70,16 @@ The driver should provide a pointer to a .Ft mac_handle_t structure as the second argument to the .Fn mac_register -function. This handle will be used when the device driver needs to -interact with the framework in various ways throughout its life. It is -also where the driver gets the +function. +This handle will be used when the device driver needs to interact with the +framework in various ways throughout its life. +It is also where the driver gets the .Fa mh argument for calling the .Fn mac_unregister -function. It is recommended that the device driver keep the handle -around in its soft state structure for a given instance. +function. +It is recommended that the device driver keep the handle around in its soft +state structure for a given instance. .Pp If the call to the .Fn mac_register @@ -101,15 +104,18 @@ entry point, it should call the .Fn mac_unregister function immediately after draining any of its transmit and receive resources that might have been given to the rest of the operating system -through DMA binding. See the +through DMA binding. +See the .Sx MBLKS AND DMA section of .Xr mac 9E -for more information. This should be done before the driver does any -tearing down. The call to the +for more information. +This should be done before the driver does any tearing down. +The call to the .Fn mac_unregister -function may fail. This may happen because the networking stack is still -using the device. In such a case, the driver should fail the call to +function may fail. +This may happen because the networking stack is still using the device. +In such a case, the driver should fail the call to .Xr detach 9E and return .Sy DDI_FAILURE . @@ -118,13 +124,15 @@ The .Fn mac_register function is generally only called from a driver's .Xr attach 9E -entry point. The +entry point. +The .Fn mac_unregister function is generally only called from a driver's .Xr attach 9E and .Xr detach 9E -entry point. However, both functions may be called from either +entry point. +However, both functions may be called from either .Sy user or .Sy kernel diff --git a/usr/src/man/man9f/mac_rx.9f b/usr/src/man/man9f/mac_rx.9f index 74ce834a9a..19067c1838 100644 --- a/usr/src/man/man9f/mac_rx.9f +++ b/usr/src/man/man9f/mac_rx.9f @@ -46,12 +46,13 @@ member. The .Fn mac_rx function is used by device drivers to deliver frames that a device -driver has received to the rest of the operating system. This will -generally be called at the end of a device driver's interrupt handler +driver has received to the rest of the operating system. +This will generally be called at the end of a device driver's interrupt handler after it is has converted all of the incoming data into a chain of .Xr mblk 9S -structures. For a full description of the process that the device driver -should take as part of receiving data, see the +structures. +For a full description of the process that the device driver should take as part +of receiving data, see the .Sx Receiving Data section of .Xr mac 9E . @@ -63,9 +64,9 @@ function. .Pp Device drivers should not call the .Fn mac_rx -function after each individual mblk_t is assembled. Rather, the device -driver should batch up as many frames as it is willing to process in a -given interrupt or otherwise. +function after each individual mblk_t is assembled. +Rather, the device driver should batch up as many frames as it is willing to +process in a given interrupt or otherwise. .Sh CONTEXT The .Fn mac_rx diff --git a/usr/src/man/man9f/mac_tx_update.9f b/usr/src/man/man9f/mac_tx_update.9f index 11f6ac475d..331fcbe983 100644 --- a/usr/src/man/man9f/mac_tx_update.9f +++ b/usr/src/man/man9f/mac_tx_update.9f @@ -37,10 +37,11 @@ The function is used by device drivers to indicate that the device represented by the handle .Fa mh -can transmit data again. It should only be called after the device -driver has returned data from its +can transmit data again. +It should only be called after the device driver has returned data from its .Xr mc_tx 9E -endpoint. For more information on when this should be called, see both +endpoint. +For more information on when this should be called, see both .Xr mc_tx 9E and the .Sx Transmitting Data and Back Pressure @@ -48,7 +49,8 @@ section of .Xr mac 9E . .Pp Device drivers should not hold any of their own locks when calling into -this function. See the +this function. +See the .Sx MAC Callbacks section of .Xr mac 9E diff --git a/usr/src/man/man9f/usb_ep_xdescr_fill.9f b/usr/src/man/man9f/usb_ep_xdescr_fill.9f index 0a11dcac93..94947c7860 100644 --- a/usr/src/man/man9f/usb_ep_xdescr_fill.9f +++ b/usr/src/man/man9f/usb_ep_xdescr_fill.9f @@ -33,7 +33,8 @@ illumos DDI specific .It Fa version Indicates the current version of the .Ft usb_ep_xdescr_t -structure the driver is using. Callers should always specify +structure the driver is using. +Callers should always specify .Sy USB_EP_XDESCR_CURRENT_VERSION . .It Fa dip Pointer to the device's @@ -60,10 +61,11 @@ can be used to open a pipe by calling .Pp Prior to USB 3.0, only one descriptor, the .Xr usb_ep_descr 9S , -was needed to describe an endpoint. However, with USB 3.0, additional -companion descriptors have been added and are required to successfully -open an endpoint. After calling this, all descriptors needed -to successfully open a pipe will be placed into +was needed to describe an endpoint. +However, with USB 3.0, additional companion descriptors have been added and are +required to successfully open an endpoint. +After calling this, all descriptors needed to successfully open a pipe will be +placed into .Fa ep_xdescr and the endpoint data, .Fa ep_data , diff --git a/usr/src/man/man9f/usb_pipe_xopen.9f b/usr/src/man/man9f/usb_pipe_xopen.9f index b9a2406252..4d403a786e 100644 --- a/usr/src/man/man9f/usb_pipe_xopen.9f +++ b/usr/src/man/man9f/usb_pipe_xopen.9f @@ -48,13 +48,15 @@ Pointer to provides hints on pipe usage. .It Fa flags .Sy USB_FLAGS_SLEEP -is only flag that is recognized. Wait for memory resources if -not immediately available. +is only flag that is recognized. +Wait for memory resources if not immediately available. .It Fa pipe_handle -Address to where new pipe handle is returned. (The handle is opaque.) +Address to where new pipe handle is returned. +(The handle is opaque.) .El .Sh DESCRIPTION -A pipe is a logical connection to an endpoint on a USB device. The +A pipe is a logical connection to an endpoint on a USB device. +The .Fn usb_pipe_xopen function creates such a logical connection and returns an initialized handle which refers to that connection. @@ -62,26 +64,34 @@ initialized handle which refers to that connection. The .Em USB 3.0 specification defines four endpoint types, each with a -corresponding type of pipe. Each of the four types of pipes uses its physical -connection resource differently. They are: +corresponding type of pipe. +Each of the four types of pipes uses its physical connection resource +differently. +They are: .Bl -tag -width Sy .It Sy Control Pipe Used for bursty, non-periodic, reliable, host-initiated request/response -communication, such as for command/status operations. These are guaranteed to -get approximately 10% of frame time and will get more if needed and if -available, but there is no guarantee on transfer promptness. Bidirectional. +communication, such as for command/status operations. +These are guaranteed to get approximately 10% of frame time and will get more if +needed and if available, but there is no guarantee on transfer promptness. +Bidirectional. .It Sy Bulk Pipe -Used for large, reliable, non-time-critical data transfers. These get the bus -on a bandwidth-available basis. Unidirectional. Sample uses include printer -data. +Used for large, reliable, non-time-critical data transfers. +These get the bus on a bandwidth-available basis. +Unidirectional. +Sample uses include printer data. .It Sy Interrupt Pipe Used for sending or receiving small amounts of reliable data infrequently but -with bounded service periods, as for interrupt handling. Unidirectional. +with bounded service periods, as for interrupt handling. +Unidirectional. .It Sy Isochronous Pipe -Used for large, unreliable, time-critical data transfers. Boasts a guaranteed -constant data rate as long as there is data, but there are no retries of failed -transfers. Interrupt and isochronous data are together guaranteed 90% of frame -time as needed. Unidirectional. Sample uses include audio. +Used for large, unreliable, time-critical data transfers. +Boasts a guaranteed constant data rate as long as there is data, but there are +no retries of failed transfers. +Interrupt and isochronous data are together guaranteed 90% of frame time as +needed. +Unidirectional. +Sample uses include audio. .El .Pp The type of endpoint to which a pipe connects (and therefore the pipe type) is @@ -97,26 +107,28 @@ Prior to the .Em USB 3.0 specification, only the .Xr usb_ep_descr 9S -was required to identify all of the attributes of a given pipe. Starting -with +was required to identify all of the attributes of a given pipe. +Starting with .Em USB 3.0 there are additional endpoint companion descriptors required to open a -pipe. To support SuperSpeed devices, the new +pipe. +To support SuperSpeed devices, the new .Fn usb_pipe_xopen function must be used rather than the older .Fn usb_pipe_open -function. The +function. +The .Xr usb_ep_xdescr 9S structure can be automatically filled out and obtained by calling the .Xr usb_ep_xdescr_fill 9F function. .Pp -Opens to interrupt and isochronous pipes can fail -if the required bandwidth cannot be guaranteed. +Opens to interrupt and isochronous pipes can fail if the required bandwidth +cannot be guaranteed. .Pp The polling interval for periodic (interrupt or isochronous) pipes, carried by -the endpoint argument's bInterval field, must be within range. Valid ranges -are: +the endpoint argument's bInterval field, must be within range. +Valid ranges are: .Pp Full speed: range of 1-255 maps to 1-255 ms. .Pp @@ -127,11 +139,11 @@ High speed: range of 1-16 maps to (2**(bInterval-1)) * 125us. Super speed: range of 1-16 maps to (2**(bInterval-1)) * 125us. .Pp Adequate bandwidth during transfers is guaranteed for all periodic pipes which -are opened successfully. Interrupt and isochronous pipes have guaranteed -latency times, so bandwidth for them is allocated when they are opened. +are opened successfully. +Interrupt and isochronous pipes have guaranteed latency times, so bandwidth for +them is allocated when they are opened. .Po -Please -refer to Sections +Please refer to Sections .Em 4.4.7 and .Em 4.4.8 @@ -141,21 +153,21 @@ specification which address isochronous and interrupt transfers. .Pc Opens of interrupt and isochronous pipes fail if inadequate bandwidth is -available to support their guaranteed latency time. Because periodic -pipe bandwidth is allocated on pipe open, open periodic pipes only when -needed. +available to support their guaranteed latency time. +Because periodic pipe bandwidth is allocated on pipe open, open periodic pipes +only when needed. .Pp The bandwidth required by a device varies based on polling interval, the maximum packet size .Pq Sy wMaxPacketSize -and the device speed. Unallocated -bandwidth remaining for new devices depends on the bandwidth already allocated -for previously opened periodic pipes. +and the device speed. +Unallocated bandwidth remaining for new devices depends on the bandwidth already +allocated for previously opened periodic pipes. .Pp The .Em pipe_policy -parameter provides a hint as to pipe usage and must be -specified. It is a +parameter provides a hint as to pipe usage and must be specified. +It is a .Em usb_pipe_policy_t which contains the following fields: .Bd -literal -offset indent @@ -166,10 +178,10 @@ The .Sy pp_max_async_reqs member is a hint indicating how many asynchronous operations requiring their own kernel thread will be concurrently in progress, the highest -number of threads ever needed at one time. Allow at least one for -synchronous callback handling and as many as are needed to accommodate -the anticipated parallelism of asynchronous* calls to the following -functions: +number of threads ever needed at one time. +Allow at least one for synchronous callback handling and as many as are needed +to accommodate the anticipated parallelism of asynchronous* calls to the +following functions: .Xr usb_pipe_close 9F , .Xr usb_set_cfg 9F , .Xr usb_set_alt_if 9F , @@ -180,30 +192,31 @@ functions: and .Xr usb_pipe_stop_isoc_polling 9F . .Pp -Setting to too small a value can deadlock the pipe. Asynchronous calls -are calls made without the +Setting to too small a value can deadlock the pipe. +Asynchronous calls are calls made without the .Sy USB_FLAGS_SLEEP -flag being passed. Note that -a large number of callbacks becomes an issue mainly when blocking +flag being passed. +Note that a large number of callbacks becomes an issue mainly when blocking functions are called from callback handlers. .Pp The control pipe to the default endpoints (endpoints for both directions with addr 0, sometimes called the default control pipe or default pipe) comes -pre-opened by the hub. A client driver receives the default control pipe handle -through +pre-opened by the hub. +A client driver receives the default control pipe handle through .Xr usb_get_dev_data 9F . A client driver cannot open the default -control pipe manually. Note that the same control pipe may be shared among -several drivers when a device has multiple interfaces and each interface is -operated by its own driver. +control pipe manually. +Note that the same control pipe may be shared among several drivers when a +device has multiple interfaces and each interface is operated by its own driver. .Pp All explicit pipe opens are exclusive; attempts to open an opened pipe fail. .Pp On success, the pipe_handle argument points to an opaque handle of the opened -pipe. On failure, it is set to NULL. +pipe. +On failure, it is set to NULL. .Sh CONTEXT -May be called from user or kernel context regardless of arguments. May also be -called from interrupt context if the +May be called from user or kernel context regardless of arguments. +May also be called from interrupt context if the .Sy USB_FLAGS_SLEEP option is not set. .Sh RETURN VALUES @@ -213,22 +226,25 @@ Open succeeded. .It Sy USB_NO_RESOURCES Insufficient resources were available. .It Sy USB_NO_BANDWIDTH -Insufficient bandwidth available. (isochronous and interrupt pipes). +Insufficient bandwidth available. +(isochronous and interrupt pipes). .It Sy USB_INVALID_CONTEXT Called from interrupt handler with USB_FLAGS_SLEEP set. .It Sy USB_INVALID_ARGS -dip and/or pipe_handle is NULL. Pipe_policy is NULL. +dip and/or pipe_handle is NULL. +Pipe_policy is NULL. .It Sy USB_INVALID_PERM -Endpoint is NULL, signifying the default control pipe. A client driver cannot -open the default control pipe. +Endpoint is NULL, signifying the default control pipe. +A client driver cannot open the default control pipe. .It Sy USB_NOT_SUPPORTED Isochronous or interrupt endpoint with maximum packet size of zero is not supported. .It Sy USB_HC_HARDWARE_ERROR Host controller is in an error state. .It Sy USB_FAILURE -Pipe is already open. Host controller not in an operational state. Polling -interval +Pipe is already open. +Host controller not in an operational state. +Polling interval .Pq Sy Bep_descr bInterval No field is out of range (intr or isoc pipes). .Pp diff --git a/usr/src/man/man9f/usba_alloc_hcdi_ops.9f b/usr/src/man/man9f/usba_alloc_hcdi_ops.9f index 9f355ef031..ba5a202dbe 100644 --- a/usr/src/man/man9f/usba_alloc_hcdi_ops.9f +++ b/usr/src/man/man9f/usba_alloc_hcdi_ops.9f @@ -32,8 +32,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMATERS .Bl -tag -width Fa .It Fa ops @@ -44,10 +44,10 @@ The .Fn usba_alloc_hcdi_ops function allocates a .Xr usba_hcdi_ops_t 9S -structure for use for a USB HCD driver. As part of initialization, a USB -HCD driver will allocate this and fill it in. For more information on -the full lifetime of the object and when a USB HCD driver should release -the structure, see +structure for use for a USB HCD driver. +As part of initialization, a USB HCD driver will allocate this and fill it in. +For more information on the full lifetime of the object and when a USB HCD +driver should release the structure, see .Xr usba_hcdi 9E . .Pp The @@ -65,8 +65,9 @@ HCD driver's .Xr attach 9E and .Xr detach 9E -entry points. While it is safe to call this function from user context, -it would be quite unusal to do so. +entry points. +While it is safe to call this function from user context, it would be quite +unusal to do so. .Sh RETURN VALUES The .Fn usba_alloc_hcdi_ops diff --git a/usr/src/man/man9f/usba_hcdi_cb.9f b/usr/src/man/man9f/usba_hcdi_cb.9f index 62cdc062ee..81c498aa8b 100644 --- a/usr/src/man/man9f/usba_hcdi_cb.9f +++ b/usr/src/man/man9f/usba_hcdi_cb.9f @@ -29,14 +29,14 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa ph A pointer to the USBA pipe handle that was passed to the HCD driver during a call to the -.Xr usba_hcdi_pipe_open +.Xr usba_hcdi_pipe_open 9E entry point. .It Fa req A pointer to the request structure that is being completed. @@ -63,14 +63,15 @@ performed over the life of the transfer. This function must not be used if the HCD driver returned a value other than .Sy USB_SUCCESS -to one of the transfer initialization functions listed above. For more -information on transfer request handling, see +to one of the transfer initialization functions listed above. +For more information on transfer request handling, see .Xr usba_hcdi 9E . .Pp The .Fa ph argument corresponds to the USBA framework's pipe handle that was given -to the HCDI when the pipe was opened. See +to the HCDI when the pipe was opened. +See .Xr usba_hcdi_pipe_open 9E and .Xr usba_hcdi 9E @@ -87,9 +88,9 @@ or which have been cast to the type .Ft usb_oapque_t . The caller should ensure that all appropriate members of the request -structure have been filled in. For example, if expecting data from the -device and the request has completed successfully, then that data -should be copied into the request structure's +structure have been filled in. +For example, if expecting data from the device and the request has completed +successfully, then that data should be copied into the request structure's .Xr mblk 9S prior to handing the request structure to the .Fn usb_hcdi_cb @@ -102,8 +103,8 @@ member should be filled in with the appropriate data. .Pp Once the request structure has been passed to the .Fn usba_hcdi_cb -function, the HCD driver must not access the structure ever again. It -should be treated as freed memory. +function, the HCD driver must not access the structure ever again. +It should be treated as freed memory. .Pp The .Fa cr @@ -112,14 +113,15 @@ If .Fa cr is set to .Sy USB_CR_OK -that indicates that the transfer completed successfully. This should -also be used when a permitted short transfer has occurred. Otherwise, it -should be set to one of the completion reasons. +that indicates that the transfer completed successfully. +This should also be used when a permitted short transfer has occurred. +Otherwise, it should be set to one of the completion reasons. .Ss Locking The HCD driver should not hold its own internal locks across a call to the .Fn usba_hcdi_cb -function. It is possible that the driver will have once of its +function. +It is possible that the driver will have once of its .Xr usba_hcdi 9E entry points called based on the return value specified. .Sh CONTEXT diff --git a/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f b/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f index 976c8c8d37..e3ec12d55d 100644 --- a/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f +++ b/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f @@ -30,8 +30,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa dip @@ -44,15 +44,16 @@ A pointer to the USB interrupt request which will be duplicated. The number of bytes in the allocated data block .Sy mblk_t . .It Fa flags -Flags which describe how allocations should be performed. Valid flags -are: +Flags which describe how allocations should be performed. +Valid flags are: .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -67,28 +68,34 @@ function is used to duplicate an existing interrupt request, .Pp The USBA framework initiates interrupt operations through the .Xr usba_hcdi_pipe_intr_xfer 9E -entry point. It provides an initial USB interrupt request as an argument. +entry point. +It provides an initial USB interrupt request as an argument. When the HCD driver has interrupt data to return, it needs to duplicate that initial interrupt request each time that it submits data through the .Xr usba_hcdi_cb 9F -function. In addition to duplicating the request, callers may also need -to increase the pipe handle's request count. For more information, see +function. +In addition to duplicating the request, callers may also need to increase the +pipe handle's request count. +For more information, see .Xr usba_hcdi_pipe_intr_xfer 9E . .Pp The .Fa dip argument should correspond to the HCD driver's .Sy dev_info_t -structure. The +structure. +The .Fa irqp -pointer should correspond to the initial interrupt request. The +pointer should correspond to the initial interrupt request. +The .Fa size -argument should describe the maximum amount of data needed for this -request. The amount of data will be dependent on the endpoint and -device. The value of +argument should describe the maximum amount of data needed for this request. +The amount of data will be dependent on the endpoint and device. +The value of .Fa flags -should depend on the caller's context. If +should depend on the caller's context. +If .Dv USB_FLAGS_SLEEP is passed while in interrupt context, then this function will fail. .Sh CONTEXT @@ -106,7 +113,8 @@ must be .Sh RETURN VALUES Upon successful completion, the .Fn usba_hcdi_dup_intr_req -function returns a pointer to a duplicated interrupt request. Otherwise, +function returns a pointer to a duplicated interrupt request. +Otherwise, .Sy NULL is returned to indicate that the request could not be duplicated. .Sh SEE ALSO diff --git a/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f b/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f index f8f881aa5b..22951b0e2b 100644 --- a/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f +++ b/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f @@ -29,8 +29,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa dip @@ -42,11 +42,12 @@ A pointer to the USB isochronous request which will be duplicated. .It Fa flags .Bl -tag -width Sy .It Sy USB_FLAGS_NOSLEEP -Do not block waiting for memory. If memory is not available the allocation -will fail. +Do not block waiting for memory. +If memory is not available the allocation will fail. .It Sy USB_FLAGS_SLEEP -Perform a blocking allocation. If memory is not available, the function -will wait until memory is made available. +Perform a blocking allocation. +If memory is not available, the function will wait until memory is made +available. .Pp Note, the request may still fail even if .Sy USB_FLAGS_SLEEP @@ -62,9 +63,9 @@ function is used to duplicate an existing isochronous request, When the USBA framework initiates an isochronous in transfer with the .Xr usba_hcdi_pipe_isoc_xfer 9E entry point, it is the HCD driver's responsibility to receive the -periodic data from the pipe. When there is data available, the HCD must -duplicate the original isochronous request and copy the available data -into the request structure's +periodic data from the pipe. +When there is data available, the HCD must duplicate the original isochronous +request and copy the available data into the request structure's .Fa isoc_data member, before handing over the request structure to the USBA framework by calling the @@ -72,18 +73,22 @@ by calling the function. .Pp In addition to duplicating the request, it is the callers responsibility -to increase the pipe handle's request count. For more information, see +to increase the pipe handle's request count. +For more information, see .Xr usba_hcdi_pipe_isoc_xfer 9E . .Pp The .Fa dip argument should correspond to the HCD driver's .Sy dev_info_t -structure. The +structure. +The .Fa usrp -pointer should correspond to the initial isochronous request. The +pointer should correspond to the initial isochronous request. +The .Fa flags -member must be appropriate for the context. If +member must be appropriate for the context. +If .Dv USB_FLAGS_SLEEP is passed while in interrupt context, then this function may fail. .Sh CONTEXT diff --git a/usr/src/man/man9f/usba_hcdi_get_device_private.9f b/usr/src/man/man9f/usba_hcdi_get_device_private.9f index 05cf3b8ebe..4649fcb814 100644 --- a/usr/src/man/man9f/usba_hcdi_get_device_private.9f +++ b/usr/src/man/man9f/usba_hcdi_get_device_private.9f @@ -27,8 +27,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa usb_device @@ -37,8 +37,8 @@ Pointer to a USB device. .Sh DESCRIPTION The .Fn usba_hcdi_get_device_private -function obtains the private data set by a HCD driver. This private data -is created by the HCD driver's optional entry point +function obtains the private data set by a HCD driver. +This private data is created by the HCD driver's optional entry point .Xr usba_hcdi_device_init 9E and is removed during the HCD driver's optional entry point .Xr usba_hcdi_device_fini 9E . @@ -56,8 +56,8 @@ function is generally called from the context of a .Xr usba_hcdi 9E entry point, but may be called from user, kernel, or interrupt context. .Sh RETURN VALUES -The private data set by an HCD driver is always returned. If no such -value has been set, then +The private data set by an HCD driver is always returned. +If no such value has been set, then .Dv NULL is returned. .Sh SEE ALSO diff --git a/usr/src/man/man9f/usba_hcdi_register.9f b/usr/src/man/man9f/usba_hcdi_register.9f index a2bdbdb97f..45bbba86de 100644 --- a/usr/src/man/man9f/usba_hcdi_register.9f +++ b/usr/src/man/man9f/usba_hcdi_register.9f @@ -33,12 +33,13 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa args -A pointer to a filled out registration structure. See +A pointer to a filled out registration structure. +See .Xr usba_hcdi_register_args_t 9S for the members to fill in. .It Fa flags @@ -61,8 +62,8 @@ The .Fn usba_hcdi_register function is called during a device driver's .Xr attach 9E -entry point after it has finished initializing the device. After this -function successfuly returns, device drivers should assume that the +entry point after it has finished initializing the device. +After this function successfuly returns, device drivers should assume that the .Xr usba_hcdi_ops 9S functions may be called at any time. .Pp @@ -71,7 +72,8 @@ The function should be called during a driver's .Xr detach 9E entry point after it has unbound its root hub, but before the remainder -of the device's state is torn down. After calling the +of the device's state is torn down. +After calling the .Fn usba_hcdi_unregister function, the driver will receive no more function calls to its .Xr usba_hcdi_ops 9S diff --git a/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f b/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f index 03b3b4a1a5..b9106cbb41 100644 --- a/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f +++ b/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f @@ -35,8 +35,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS .Bl -tag -width Fa .It Fa dip @@ -59,7 +59,8 @@ The and .Fn usba_hubdi_unbind_root_hub functions are used to bind and unbind the root USB hub that is a part of -every HCD driver. See +every HCD driver. +See .Xr usba_hcdi 9E for more information on this relationship. .Pp @@ -76,19 +77,19 @@ responsible for making it appear to the system as a normal USB hub. .Pp The contents of the .Fa hub_descr -should be the standard USB Hub class-specific descriptor. This hub -descriptor should match a hub of a similar class of speed. For example, -with the xhci controller, a USB 3.x Hub class-specific descriptor is -used, where as for the ehci controller, a USB 2.x Hub class-specific -descriptor is used. For more information, see the USB 3.1 -specification, section 10.15.2 +should be the standard USB Hub class-specific descriptor. +This hub descriptor should match a hub of a similar class of speed. +For example, with the xhci controller, a USB 3.x Hub class-specific descriptor +is used, where as for the ehci controller, a USB 2.x Hub class-specific +descriptor is used. +For more information, see the USB 3.1 specification, section 10.15.2 .Em Class-specific Descriptors . .Pp Similarly, the contents of the .Fa dev_descr need to be a filled in USB device descriptor that indicates that the -root hub corresponds to the appropriate USB generation. For more -information on the contents, see +root hub corresponds to the appropriate USB generation. +For more information on the contents, see .Xr usb_dev_descr 9S and the USB 3.1 specification, section 10.15.1 .Em Standard Descriptors for Hub Class . @@ -99,7 +100,7 @@ function is used to detach the root hub associated with the HCD driver. This should be called during a device's .Xr detach 9E routine before calling -.Xr usba_hcdi_unregister . +.Xr usba_hcdi_unregister 9F . .Pp If a call to the .Fn usba_hubdi_unbind_root_hub diff --git a/usr/src/man/man9f/usba_hubdi_cb_ops.9f b/usr/src/man/man9f/usba_hubdi_cb_ops.9f index 196874ad8f..01525a8391 100644 --- a/usr/src/man/man9f/usba_hubdi_cb_ops.9f +++ b/usr/src/man/man9f/usba_hubdi_cb_ops.9f @@ -52,8 +52,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMATERS .Bl -tag -width Fa .It Fa dip @@ -74,14 +74,16 @@ The and .Fn usba_hubdi_close functions are functions provided for the implementation of USB HCD -drivers. USB HCD drivers are required to implemnt the +drivers. +USB HCD drivers are required to implemnt the .Xr open 9E , .Xr ioctl 9E , and .Xr close 9E .Xr cb_ops 9S -functions. In each of those functions, they should use the device number -to determine number in +functions. +In each of those functions, they should use the device number to determine +number in .Fa devp or .Fa dev diff --git a/usr/src/man/man9f/usba_hubdi_dev_ops.9f b/usr/src/man/man9f/usba_hubdi_dev_ops.9f index a0a9530e8e..8d85fa9ee7 100644 --- a/usr/src/man/man9f/usba_hubdi_dev_ops.9f +++ b/usr/src/man/man9f/usba_hubdi_dev_ops.9f @@ -15,7 +15,7 @@ .Dt USBA_HCDI_DEV_OPS 9F .Os .Sh NAME -.Nm usba_hubdi_bus_ops +.Nm usba_hubdi_bus_ops , .Nm usba_hubdi_root_hub_power .Nd device operations utility functions for HCD drivers .Sh SYNOPSIS @@ -29,8 +29,8 @@ .Sy Volatile - illumos USB HCD private function .Pp -This is a private function that is not part of the stable DDI. It may be -removed or changed at any time. +This is a private function that is not part of the stable DDI. +It may be removed or changed at any time. .Sh PARAMETERS For the parameters of the .Fn usba_hubdi_root_hub_power @@ -40,14 +40,15 @@ function, see The .Fn usba_hubdi_root_hub_power function is a utility function for the implementation of USB HCD -drivers. USB HCD drivers that support power management, should use set -the +drivers. +USB HCD drivers that support power management, should use set the .Sy devo_power member of their .Xr dev_ops 9S structure to the .Fn usba_hubdi_root_hub_power -function. They should not implement their own +function. +They should not implement their own .Xr power 9E function. .Pp @@ -55,7 +56,8 @@ In addition, drivers should pass the symbol .Sy usba_hubdi_busops as the .Sy devo_bus_ops -member. It contains a properly formatted bus operations structure. +member. +It contains a properly formatted bus operations structure. .Sh CONTEXT This function should not be called directly, it should only be used as a member of a device's diff --git a/usr/src/man/man9f/vmem_alloc.9f b/usr/src/man/man9f/vmem_alloc.9f index 02d74f68e9..07a65b3aab 100644 --- a/usr/src/man/man9f/vmem_alloc.9f +++ b/usr/src/man/man9f/vmem_alloc.9f @@ -65,19 +65,22 @@ There are two meaningful groups of flags. .Dv VM_SLEEP or .Dv VM_NOSLEEP -must be specified, and indicate whether the allocation may block. A +must be specified, and indicate whether the allocation may block. +A .Dv VM_SLEEP allocation can never fail but may block indefinitely. .Pp The allocation policy may be specified by one of the following flags: .Bl -tag -width Ds .It Dv VM_BESTFIT -Take the segment from the smallest free segment that could satisfy this allocation. +Take the segment from the smallest free segment that could satisfy this +allocation. .It Dv VM_FIRSTFIT Take the segment from the first free segment found that could satisfy this allocation. .It Dv VM_NEXTFIT -Take the segment from the segment after the one previously allocated. This +Take the segment from the segment after the one previously allocated. +This provides sequential behaviour useful when allocating identifiers from a .Dv VMC_IDENTIFIER arena. @@ -95,8 +98,8 @@ an approximation of .Dv VM_BESTFIT in guaranteed constant time. .It Fa align_arg -The minimum alignment of the allocation. If 0, -the allocated segment will be aligned as the arena's quantum. +The minimum alignment of the allocation. +If 0, the allocated segment will be aligned as the arena's quantum. .It Fa phase The allocated segment must be .Fa phase @@ -150,8 +153,8 @@ Upon successful completion the .Fn vmem_alloc and .Fn vmem_xalloc -functions return a pointer to the beginning of the allocated segment. In the -case of a +functions return a pointer to the beginning of the allocated segment. +In the case of a .Dv VMC_IDENTIFIER arena, the address of this pointer is the meaningful component, not the value to which it points. diff --git a/usr/src/man/man9f/vmem_create.9f b/usr/src/man/man9f/vmem_create.9f index eb2ae6b37c..17f4ac3d07 100644 --- a/usr/src/man/man9f/vmem_create.9f +++ b/usr/src/man/man9f/vmem_create.9f @@ -67,8 +67,9 @@ The size of the arena to create. .It Fa quantum The arena's .Dq quantum . -The granularity of the arena. The amount allocated at minimum by each -request. Must be a power of 2. +The granularity of the arena. +The amount allocated at minimum by each request. +Must be a power of 2. .It Fa afunc A function which is called to import new spans from .Fa source , @@ -85,7 +86,8 @@ a function taking three parameters and returning a pointer to (the imported space): .Bl -tag -width Ds .It Fa "vmem_t *" -The source arena from which we'll import. The +The source arena from which we'll import. +The .Fa source argument to .Fn vmem_create . @@ -107,7 +109,8 @@ a function taking four parameters and returning a pointer to (the imported space): .Bl -tag -width Ds .It Fa "vmem_t *" -The source arena from which we'll import. The +The source arena from which we'll import. +The .Fa source argument to .Fn vmem_xcreate . @@ -135,7 +138,8 @@ This is a a function taking three parameters and returning void: .Bl -tag -width Ds .It Fa "vmem_t" -The arena to which space is being returned. The +The arena to which space is being returned. +The .Fa source argument to .Fn vmem_create @@ -172,7 +176,8 @@ A .Em vmem arena is a section of an arbitrary address space (a range of integer addresses). This commonly represents virtual memory, but can in fact be an arbitrary set -of integers. The +of integers. +The .Dv VMC_IDENTIFIER flag set at arena creation time differentiates between these two cases. .Pp @@ -201,7 +206,8 @@ Upon successful completion the .Fn vmem_create and .Fn vmem_xcreate -functions return a pointer to a vmem arena. Otherwise, +functions return a pointer to a vmem arena. +Otherwise, .Dv NULL is returned to indicate the arena could not be created. .Sh SEE ALSO diff --git a/usr/src/man/man9s/mac_callbacks.9s b/usr/src/man/man9s/mac_callbacks.9s index a12d5ba230..9ab382d65e 100644 --- a/usr/src/man/man9s/mac_callbacks.9s +++ b/usr/src/man/man9s/mac_callbacks.9s @@ -30,7 +30,8 @@ structure is used by GLDv3 networking device drivers implementing the interface. .Pp The structure is normally allocated statically by drivers as a single -global entry. A pointer to it is passed as the +global entry. +A pointer to it is passed as the .Sy m_callbacks member of the .Sy mac_register_t @@ -81,10 +82,11 @@ mac_prop_info_t mc_propinfo; /* Get property information */ The .Sy mc_callbacks member is used to denote which of a series of optional callbacks are -present. This method allows additional members to be added to the +present. +This method allows additional members to be added to the .Sy mac_callbacks_t -structure while maintaining ABI compatibility with existing modules. If -a member is not mentioned below, then it is a part of the base version +structure while maintaining ABI compatibility with existing modules. +If a member is not mentioned below, then it is a part of the base version of the structure and device drivers do not need to set anything to indicate that it is present. The @@ -132,36 +134,38 @@ structure members have been set. The .Sy mc_getstat function defines an entry point used to receive statistics about the -device. A list of statistics that it is required to support is available -in +device. +A list of statistics that it is required to support is available in .Xr mac 9E . For more information on the requirements of the function, see .Xr mc_getstat 9E . .Pp The .Sy mc_start -member defines an entry point that is used to start the device. For more -information on the requirements of the function, see +member defines an entry point that is used to start the device. +For more information on the requirements of the function, see .Xr mc_start 9E . .Pp The .Sy mc_stop -member defines an entry point that is used to stop the device. It is the -opposite of the +member defines an entry point that is used to stop the device. +It is the opposite of the .Sy mc_start -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_stop 9E . .Pp The .Sy mc_setpromisc -member is used to enable and disable promiscuous mode on the device. For -more information on the requirements of the function, see +member is used to enable and disable promiscuous mode on the device. +For more information on the requirements of the function, see .Xr mc_setpromisc 9E . .Pp The .Sy mc_multicst member is used to enable or disable multicast addresses in the device's -filters. For more information on the requirements of the function, see +filters. +For more information on the requirements of the function, see .Xr mc_multicst 9E . .Pp The @@ -172,99 +176,114 @@ For more information on the requirements of the function, see .Pp The .Sy mc_tx -member is used to transmit a single message on the wire. For more -information on the requirements of the function, see +member is used to transmit a single message on the wire. +For more information on the requirements of the function, see .Xr mc_tx 9E . .Pp The .Sy mc_ioctl -member is used to process device specific ioctls. The GLDv3 does not -define any ioctls that devices should handle; however, there may be -private ioctls for this device. This entry point is optional. For it to -be considered, the +member is used to process device specific ioctls. +The GLDv3 does not define any ioctls that devices should handle; however, there +may be private ioctls for this device. +This entry point is optional. +For it to be considered, the .Sy MC_IOCTL value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_ioctl 9E . .Pp The .Sy mc_getcapab -member is used to determine device capabilities. Each capability has its -own data and semantics associated with it. A list of capabilities is -provided in +member is used to determine device capabilities. +Each capability has its own data and semantics associated with it. +A list of capabilities is provided in .Xr mac 9E . -This entry point is optional. For it to be used, the +This entry point is optional. +For it to be used, the .Sy MC_GETCAPAB value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_getcapab 9E . .Pp The .Sy mc_open member is used to provide specific actions to take when the device is -opened. Note that most device drivers will not have a need to implement -this. It is not required for this function to be implemented for this -device to be used with +opened. +Note that most device drivers will not have a need to implement this. +It is not required for this function to be implemented for this device to be +used with .Xr dlpi 7P . -This entry point is optional. For it to be used, the +This entry point is optional. +For it to be used, the .Sy MC_OPEN value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_open 9E . .Pp The .Sy mc_close member is used to provide specific actions to take when the device is -closed. Note that most device drivers will not have a need to implement -this. It is not required for this function to be implemented for this -device to be used with +closed. +Note that most device drivers will not have a need to implement this. +It is not required for this function to be implemented for this device to be +used with .Xr dlpi 7P . -This entry point is optional. For it to be used, the +This entry point is optional. +For it to be used, the .Sy MC_CLOSE value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_close 9E . .Pp The .Sy mc_getprop -member is used to get the current value of a property from the device. A -list of properties, their sizes, and their interpretation is available -in +member is used to get the current value of a property from the device. +A list of properties, their sizes, and their interpretation is available in .Xr mac 9E . -This entry point is optional. For it to be used, the +This entry point is optional. +For it to be used, the .Sy MC_GETPROP value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_getprop 9E . .Pp The .Sy mc_setprop -member is used to set the value of a device property. A list of -properties, their sizes, and their interpretation is available in +member is used to set the value of a device property. +A list of properties, their sizes, and their interpretation is available in .Xr mac 9E . -This entry point is optional. For it to be used, the +This entry point is optional. +For it to be used, the .Sy MC_SETPROP value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_setprop 9E . .Pp The .Sy mc_propinfo member is used to obtain metadata about a property such as its default -value, whether or not it is writable, and more. A list of properties, -their sizes, and their interpretation is available in +value, whether or not it is writable, and more. +A list of properties, their sizes, and their interpretation is available in .Xr mac 9E . -This entry point is optional. For it to be used, the +This entry point is optional. +For it to be used, the .Sy MC_PROPINFO value must be present in the .Sy mc_callbacks -member. For more information on the requirements of the function, see +member. +For more information on the requirements of the function, see .Xr mc_propinfo 9E . .Pp .Ss Required Members @@ -280,7 +299,7 @@ will fail. .It .Sy mc_stop .It -. Sy mc_setpromisc +.Sy mc_setpromisc .It .Sy mc_multicst .It @@ -294,8 +313,8 @@ implement the .Sy mc_unicst and .Sy mc_tx -functions. However, the ring capabilities are still private and evolving -at this time. +functions. +However, the ring capabilities are still private and evolving at this time. .Pp Generally, a device that implements one of .Sy mc_getprop , diff --git a/usr/src/man/man9s/mac_register.9s b/usr/src/man/man9s/mac_register.9s index 469a11693c..6f648e3348 100644 --- a/usr/src/man/man9s/mac_register.9s +++ b/usr/src/man/man9s/mac_register.9s @@ -32,11 +32,12 @@ interface. .Pp The structure is allocated by a call to .Xr mac_alloc 9F -after which the various structure members should be set. Once they have -been set, the structure can be used by a GLDv3 device driver to register -with the MAC framework by calling the +after which the various structure members should be set. +Once they have been set, the structure can be used by a GLDv3 device driver to +register with the MAC framework by calling the .Xr mac_register 9F -function. Once +function. +Once .Xr mac_register 9F has been called, the structure can be freed through a call to .Xr mac_free 9F . @@ -67,8 +68,8 @@ Device drivers should not modify this field. The .Sy m_type_ident member identifies the kind of networking device that this driver -represents. The following constants should be used to identify the -device type: +represents. +The following constants should be used to identify the device type: .Bl -tag -width Dv .It Sy MAC_PLUGIN_IDENT_ETHER The device driver implements IEEE 802.3 Ethernet. @@ -79,69 +80,74 @@ The value is a private value that the device driver may set and will be provided as an argument in many of the .Xr mac 9E -callbacks. Most often this is set to the driver's soft state for a -specific instance. +callbacks. +Most often this is set to the driver's soft state for a specific instance. .Pp The .Sy m_dip member should point to the device driver's .Sy dev_info -structure for that specific instance. This structure is provided during -the driver's +structure for that specific instance. +This structure is provided during the driver's .Xr attach 9E entry point. .Pp The .Sy m_instance -member should be set to zero. The GLDv3 framework will determine the -appropriate instance. +member should be set to zero. +The GLDv3 framework will determine the appropriate instance. .Pp The .Sy m_src_addr member should be set to a byte array that describes the source MAC -address of the device. This is usually the default MAC address as -programmed by the device manufacturer in that instance of the device. +address of the device. +This is usually the default MAC address as programmed by the device manufacturer +in that instance of the device. .Pp The .Sy m_dst_addr member is an optional property and should be set to .Dv NULL -by most device drivers. If set, this address will be the destination for -outgoing frames. +by most device drivers. +If set, this address will be the destination for outgoing frames. .Pp The .Sy m_callbacks member contains the GLDv3 entry points implemented by the device driver. -.Xr mac See .Xr mac_callbacks 9S for a full explanation of the structure, its members, and their -responsibilities. See +responsibilities. +See .Xr mac 9E for a broader picture of how the entry points are used. .Pp The .Sy m_min_sdu -property is the minimum service data unit. It represents the minimum -size packet that the device can transmit, ignoring its own headers. Thus -for an Ethernet device, this value would exclude the Ethernet header and -any VLAN headers. If this is set to zero, then that means that either -the MAC protocol does not require a minimum size or that the device -driver and hardware will ensure that any minimum size is taken care of. +property is the minimum service data unit. +It represents the minimum size packet that the device can transmit, ignoring its +own headers. +Thus for an Ethernet device, this value would exclude the Ethernet header and +any VLAN headers. +If this is set to zero, then that means that either the MAC protocol does not +require a minimum size or that the device driver and hardware will ensure that +any minimum size is taken care of. .Pp The .Sy m_max_sdu -property is the maximum service data unit. It represents the maximum -size packet that the device can transmit, ignoring its own headers. For -an Ethernet based device, this would exclude the size of the Ethernet -header and a VLAN headers. This value is often called the maximum -transmission unit (MTU). +property is the maximum service data unit. +It represents the maximum size packet that the device can transmit, ignoring its +own headers. +For an Ethernet based device, this would exclude the size of the Ethernet +header and a VLAN headers. +This value is often called the maximum transmission unit (MTU). .Pp The .Sy m_pdata member is used for data specific to the type specified in the .Sy m_type_ident -member. For all devices of type +member. +For all devices of type .Sy MAC_PLUGIN_IDENT_ETHER , this should be set to .Dv NULL . @@ -165,7 +171,8 @@ and If the driver does not have any private properties, it should be set to .Dv NULL . Otherwise, it should be set to a NULL-terminated array of character -strings where each entry is the name of a distinct property. See +strings where each entry is the name of a distinct property. +See .Xr mac 9E for more information on private properties. .Pp @@ -173,10 +180,11 @@ The .Sy m_margin property indicates the amount of additional bytes of information that may be -included beyond the basic MAC header. For example, with an Ethernet -device, if the hardware supports a VLAN tag, then this property would be -set to the size of a VLAN tag, indicating that it supported the -additional bytes in a single packet beyond the Ethernet header and the +included beyond the basic MAC header. +For example, with an Ethernet device, if the hardware supports a VLAN tag, then +this property would be set to the size of a VLAN tag, indicating that it +supported the additional bytes in a single packet beyond the Ethernet header and +the .Sy m_max_sdu . .Sh SEE ALSO .Xr attach 9E , diff --git a/usr/src/man/man9s/usb_ep_ss_comp_descr.9s b/usr/src/man/man9s/usb_ep_ss_comp_descr.9s index b94b7f576b..ba3f4e06b0 100644 --- a/usr/src/man/man9s/usb_ep_ss_comp_descr.9s +++ b/usr/src/man/man9s/usb_ep_ss_comp_descr.9s @@ -26,10 +26,12 @@ illumos DDI Specific The .Sy usb_ep_ss_comp_descr_t structure defines additional endpoint attributes for USB 3.0 and newer -devices. This structure is considered a +devices. +This structure is considered a .Em companion descriptor . -On its own, it does not uniquely define an endpoint. A standard USB -descriptor is still required. See +On its own, it does not uniquely define an endpoint. +A standard USB descriptor is still required. +See .Xr usb_ep_descr 9S for the definition of the standard descriptor. .Pp @@ -37,7 +39,8 @@ If available, the SuperSpeed companion descriptor can be accessed by getting the endpoint data through a call to .Xr usb_lookup_ep_data 9F . These descriptors are required to open pipes for USB 3.0 and newer -devices. They can be assembled into the proper format for +devices. +They can be assembled into the proper format for .Xr usb_pipe_xopen 9F by calling .Xr usb_ep_xdescr_fill 9F . @@ -67,15 +70,16 @@ whose value is 0x30. The .Sy bMaxBurst member indicates the maximum number of packets that the endpoint can -send in one 'burst'. Valid values range from 0 to 15 and the values are -one less than the number of packets. A value of 0 indicates that 1 -packet can be sent in a burst. A value of 15 indicates that 16 packets -can be sent in a burst. +send in one 'burst'. +Valid values range from 0 to 15 and the values are one less than the number of +packets. +A value of 0 indicates that 1 packet can be sent in a burst. +A value of 15 indicates that 16 packets can be sent in a burst. .Pp The .Sy bmAttributes -member indicates different attributes of the endpoint. This member is -reserved and should be zero for +member indicates different attributes of the endpoint. +This member is reserved and should be zero for .Sy control and .Sy interrupt @@ -86,11 +90,14 @@ For a endpoint, the .Sy bmAttributes member is used to indicate the maximum number of streams that the device -supports. The first five bits (4:0) are used, the remaining 3 bits are -reserved and should be zero. Values range from 0 to 16. A value of zero -indicates that streams are not supported. Otherwise, it indicates that -the device supports 2 raised to the value number of streams. A value of -3, indicates 2^3 streams are supported. +supports. +The first five bits (4:0) are used, the remaining 3 bits are reserved and should +be zero. +Values range from 0 to 16. +A value of zero indicates that streams are not supported. +Otherwise, it indicates that the device supports 2 raised to the value number of +streams. +A value of 3, indicates 2^3 streams are supported. .Pp For an .Sy isochronous @@ -99,14 +106,15 @@ endpoint, the member is used to indicate the value of the .Sy Mult property, a value used to calculate the maximum number of packets the -device and receive in a service interval. The first two bits (1:0) are -used to determine the mult. The remaining 6 bits (7:2) are reserved and -should be set to zero. +device and receive in a service interval. +The first two bits (1:0) are used to determine the mult. +The remaining 6 bits (7:2) are reserved and should be set to zero. .Pp The .Sy wBytesPerInterval member is used to indicate the total number of bytes that can be -transferred in one service interval. Note, this is only valid for +transferred in one service interval. +Note, this is only valid for .Sy Isochronous and .Sy Interrupt IN diff --git a/usr/src/man/man9s/usb_ep_xdescr.9s b/usr/src/man/man9s/usb_ep_xdescr.9s index bb7a86120e..44ce12793e 100644 --- a/usr/src/man/man9s/usb_ep_xdescr.9s +++ b/usr/src/man/man9s/usb_ep_xdescr.9s @@ -32,9 +32,11 @@ Starting with the .Em USB 3.0 specification, .Em USB 3.0 -endpoints have an endpoint SuperSpeed companion descriptor. See +endpoints have an endpoint SuperSpeed companion descriptor. +See .Xr usb_ep_ss_comp_descr 9S -for a description of the descriptor. In the +for a description of the descriptor. +In the .Em USB 3.1 specification, certain endpoints will have additional companion descriptors. @@ -54,7 +56,8 @@ After looking up endpoint data, through the .Xr usb_lookup_ep_data 9F , device drivers should call the .Xr usb_ep_xdescr_fill 9F -function. After that, the +function. +After that, the .Sy usb_ep_xdescr_t structure will be filled in. .Sh STRUCTURE MEMBERS @@ -70,32 +73,34 @@ usb_ep_ss_comp_descr_t uex_ep_ss; .Pp The .Sy uex_version -member is used to describe the current version of this structure. This -member will be set to the value passed in by the device driver to +member is used to describe the current version of this structure. +This member will be set to the value passed in by the device driver to .Xr usb_ep_xdescr_fil 9F . Device drivers should ignore this field and should not modify the value placed there or modify it. .Pp The .Sy uex_flags -member is an enumeration that defines a number of flags. Each flag -indicates whether or not a given member is present or valid. Before -accessing any member other than +member is an enumeration that defines a number of flags. +Each flag indicates whether or not a given member is present or valid. +Before accessing any member other than .Sy uex_ep , the device driver should check the flag here, otherwise its contents may -be undefined. Currently the following flags are defined: +be undefined. +Currently the following flags are defined: .Bl -tag -width Sy -offset indent .It Sy USB_EP_XFLAGS_SS_COMP Indicates that a SuperSpeed endpoint companion descriptor is present and -has been filled in. The member +has been filled in. +The member .Sy uex_ep_ss is valid. .El .Pp The .Sy uex_ep -member contains a traditional USB endpoint descriptor. Its contents are -defined in +member contains a traditional USB endpoint descriptor. +Its contents are defined in .Xr usb_ep_descr 9S . There is no flag for this member in .Sy uex_flags , diff --git a/usr/src/man/man9s/usba_device.9s b/usr/src/man/man9s/usba_device.9s index cb1fa5453f..036e50feed 100644 --- a/usr/src/man/man9s/usba_device.9s +++ b/usr/src/man/man9s/usba_device.9s @@ -24,30 +24,33 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_device_t structure is used by the illumos USB Architecture (USBA) to represent a -physical USB device. While a given USB device may be a composite device, -a USB device that implements two or more classes, there will still only -be a single device structure. A USB device is always plugged into a -port on some hub, excepting the root hub, and has an address on the USB -fabric. +physical USB device. +While a given USB device may be a composite device, a USB device that implements +two or more classes, there will still only be a single device structure. +A USB device is always plugged into a port on some hub, excepting the root hub, +and has an address on the USB fabric. .Pp Many of the USB HCD driver operations pass a .Sy usba_device_t -to the HCD driver. The +to the HCD driver. +The .Sy usba_device_t should be used by an HCD driver in a .Em read-only -fashion. A subset of the structure's fields that are useful for HCD -drivers to read are listed below. +fashion. +A subset of the structure's fields that are useful for HCD drivers to read are +listed below. .Pp In addition, there are two optional HCD entry points that interact with this structure and give the change for a driver to store per-device -state. If the driver implements the +state. +If the driver implements the .Xr usba_hcdi_device_init 9E and .Xr usba_hcdi_device_fini 9E @@ -77,9 +80,11 @@ The .Sy usb_dip member is a pointer to the device's .Sy dev_info_t -structure. This generally is used if the HCD driver wants to get naming -information for diagnostic purposes. When duplicating requests for -isochronous and interrupt requests, HCD drivers should use the +structure. +This generally is used if the HCD driver wants to get naming information for +diagnostic purposes. +When duplicating requests for isochronous and interrupt requests, HCD drivers +should use the .Sy dev_info_t from the .Xr usba_pipe_handle_data_t 9S . @@ -88,7 +93,8 @@ The .Sy usb_hubdi member can be used to determine whether or not the .Sy usba_device_t -in question is a hub or not. HCD drivers should compare this member to +in question is a hub or not. +HCD drivers should compare this member to .Dv NULL . If the member is not .Dv NULL , @@ -100,7 +106,8 @@ member indicates the address of the USB device on the broader USB bus. Note, that the actual address assigned to the device may be different, especially if the HCD driver implements the optional .Xr usba_hcdi_device_address 9E -entry point. See the section +entry point. +See the section .Sy USB addressing in .Xr usba_hcdi 9E @@ -108,13 +115,14 @@ for more information. .Pp The .Sy usb_dev_descr -member points to the device descriptor for a given device. This -structure is documented in +member points to the device descriptor for a given device. +This structure is documented in .Xr usb_dev_descr 9S . This member may be .Dv NULL as it may not have been populated during device -attachment. This member may be +attachment. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL @@ -123,7 +131,8 @@ before dereferencing it. The .Sy usb_mfg_str member may contain a pointer to a character string with the name of the -manufacturer as retrieved from the device. This member may be +manufacturer as retrieved from the device. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL @@ -132,7 +141,8 @@ before dereferencing it. The .Sy usb_product_str member may contain a pointer to a character string with the name of the -product as retrieved from the device. This member may be +product as retrieved from the device. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL @@ -141,43 +151,47 @@ before dereferencing it. The .Sy usb_serialno_str member may contain a pointer to a character string with the serial -number of the device as retrieved from the device. This member may be +number of the device as retrieved from the device. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL before dereferencing it. .Pp The -.Sy usb_port_status_t +.Sy usb_port_status contains a -.Xr usb_port_status_t -entry, which describes the current negotiated speed of the device. See +.Xr usb_port_status_t 9T +entry, which describes the current negotiated speed of the device. +See .Xr usb_port_status_t 9T for more information on the values and types. .Pp The .Sy usb_port -member contains the port on a hub that the device is plugged into. Ports -are always numbered starting at 1. +member contains the port on a hub that the device is plugged into. +Ports are always numbered starting at 1. .Pp The .Sy usb_hs_hub_usba_dev -member is set when there is a parent high-speed hub. This is most -notable for low- and full- speed devices which require split -transaction support. This points to the +member is set when there is a parent high-speed hub. +This is most notable for low- and full- speed devices which require split +transaction support. +This points to the .Sy usb_device_t -structure that is the closest high-speed parent hub. This member should +structure that is the closest high-speed parent hub. +This member should always be set to .Dv NULL -for super-speed devices. A device operating a super-speed can never be -plugged into a high-speed hub. +for super-speed devices. +A device operating a super-speed can never be plugged into a high-speed hub. .Pp The .Sy usb_parent_hub member points to the .Sy usba_device_t -structure that the device in question is plugged into. If the device -represents the root hub, then this field will be +structure that the device in question is plugged into. +If the device represents the root hub, then this field will be .Dv NULL . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9s/usba_hcdi_ops.9s b/usr/src/man/man9s/usba_hcdi_ops.9s index c1b8df0423..87e2ac3a8b 100644 --- a/usr/src/man/man9s/usba_hcdi_ops.9s +++ b/usr/src/man/man9s/usba_hcdi_ops.9s @@ -24,13 +24,14 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_hcdi_ops structure is usbed HCD drivers to register operations vectors and -callbacks from the USBA HCD interface. See +callbacks from the USBA HCD interface. +See .Xr usba_hcdi 9E for more information on USB HCD device drivers. .Pp @@ -100,8 +101,8 @@ int (*usba_hcdi_hub_update)(usba_device_t *, uint8_t, uint8_t); .Pp The .Sy usba_hcdi_ops_version -member is used to indicate the revision of the operations vector. HCD -drivers should generally set this to +member is used to indicate the revision of the operations vector. +HCD drivers should generally set this to .Dv HCDI_OPS_VERSION . .Pp The @@ -113,7 +114,8 @@ structure of the HCD driver that was received in .Pp The .Sy usba_hcdi_pm_support -member is vestigial. If may be set to +member is vestigial. +If may be set to .Dv NULL or to a function which only returns .Sy USB_FAILURE . @@ -122,7 +124,8 @@ The .Sy usba_hcdi_pipe_open member should be set to a function which takes care of the all of the controller-specific actions of opening up an endpoint on a device and -associating it with the pipe. See +associating it with the pipe. +See .Xr usba_hcdi_pipe_open 9E for more information. .Pp @@ -130,8 +133,10 @@ The .Sy usba_hcdi_pipe_close member should be set to a function which takes care of releasing all of the controller-specific resources and actions taken when the pipe was -opened. This function also has the responsibility to clean up any -outstanding polling on the endpoint. See +opened. +This function also has the responsibility to clean up any outstanding polling on +the endpoint. +See .Xr usba_hcdi_pipe_close 9E for more information. .Pp @@ -139,7 +144,8 @@ The .Sy usba_hcdi_pipe_reset member should be set to a function that takes care of resetting a pipe. A pipe reset not only performs controller-specific functionality, but it -also cleans up any outstanding requests and terminates polling. See +also cleans up any outstanding requests and terminates polling. +See .Xr usba_hcdi_pipe_reset 9E for more information. .Pp @@ -151,7 +157,8 @@ toggle, if the controller exposes this functionality to the host. The .Sy usba_hcdi_pipe_ctrl_xfer member should be set to a function that handles control transfers for any -device, including the root hub. See +device, including the root hub. +See .Xr usba_hcdi_pipe_ctrl_xfer 9E for more information. .Pp @@ -171,38 +178,42 @@ for more information. The .Sy usba_hcdi_pipe_intr_xfer member should be set to a function which performs interrupt transfers. -These may be both periodic and one-shot transfers. In addition, this may -need to handle requests for the root hub. See +These may be both periodic and one-shot transfers. +In addition, this may need to handle requests for the root hub. +See .Xr usba_hcdi_pipe_intr_xfer 9E for more information. .Pp The .Sy usba_hcdi_pipe_stop_intr_polling member should be set to a function which is used to terminate interrupt -polling and return the original interrupt request. See +polling and return the original interrupt request. +See .Xr usba_hcdi_pipe_stop_intr_polling 9E for more information. .Pp The .Sy usba_hcdi_pipe_isoc_xfer member should be set to a function which performs isochronous transfers. -These may be both periodic and one-shot transfers. See +These may be both periodic and one-shot transfers. +See .Xr usba_hcdi_pipe_isoc_xfer 9E for more information. .Pp The .Sy usba_hcdi_pipe_stop_isoc_polling member should be set to a function which is used to terminate isochronous -polling and return the original isochronous request. See +polling and return the original isochronous request. +See .Xr usba_hcdi_pipe_stop_isoc_polling 9E for more information. .Pp The .Sy usba_hcdi_get_current_frame_number member should be set to a function which returns the current virtual -frame number. While this entry point is required, at this time, nothing -uses this functionality in illumos, so having a dummy function which -just returns +frame number. +While this entry point is required, at this time, nothing uses this +functionality in illumos, so having a dummy function which just returns .Sy USB_FAILURE is acceptable. .Pp @@ -219,9 +230,10 @@ The and .Sy usba_hcdi_console_input_exit members are used to facilitate a USB device acting as the system console -and reading input from it. Support for this is optional in an HCD -driver. HCD drivers which do not support this functionality should have -functions which return +and reading input from it. +Support for this is optional in an HCD driver. +HCD drivers which do not support this functionality should have functions which +return .Sy USB_FAILURE . .Pp The @@ -232,9 +244,10 @@ The and .Sy usba_hcdi_console_output_exit members are used to facilitate a USB device acting as the system console -and outputting data to it. Support for this is optional in an HCD -driver. HCD drivers which do not support this functionality should have -functions which return +and outputting data to it. +Support for this is optional in an HCD driver. +HCD drivers which do not support this functionality should have functions which +return .Sy USB_FAILURE . .Pp The @@ -242,8 +255,8 @@ The member is an .Em optional entry point that will be called every time a new device is initialized -and detected by the system. If an HCD does not need this functionality, -the member should be set to +and detected by the system. +If an HCD does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_device_init 9E @@ -256,8 +269,8 @@ member is an entry point that will be called every time a device is removed from the system, whether through it being unplugged or a .Xr cfgadm 1M -action. If an HCD does not need this functionality, -the member should be set to +action. +If an HCD does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_device_fini 9E @@ -268,8 +281,8 @@ The member is an .Em optional entry point that will be called every time a USB device needs to be -addressed. If an HCD driver does not need this functionality, the member -should be set to +addressed. +If an HCD driver does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_device_address 9E @@ -280,10 +293,10 @@ The member is an .Em optional entry point that will be called every time a device descriptor is read -that turns out to be a hub. This gives HCD drivers a chance to perform -any needed controller-specific functionality before the device is -used. If an HCD driver does not need this functionality, the member -should be set to +that turns out to be a hub. +This gives HCD drivers a chance to perform any needed controller-specific +functionality before the device is used. +If an HCD driver does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_hub_update 9E diff --git a/usr/src/man/man9s/usba_hcdi_register_args.9s b/usr/src/man/man9s/usba_hcdi_register_args.9s index bdb564d07d..068e826103 100644 --- a/usr/src/man/man9s/usba_hcdi_register_args.9s +++ b/usr/src/man/man9s/usba_hcdi_register_args.9s @@ -24,8 +24,8 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_hcdi_register_args_t @@ -34,9 +34,9 @@ framework. .Pp The structure is used with the .Xr usba_hcdi_register 9F -function. Device drivers may statically allocate this structure on the -stack. It does not need to be allocated on the heap or used beyond the -call to +function. +Device drivers may statically allocate this structure on the stack. +It does not need to be allocated on the heap or used beyond the call to .Xr usba_hcdi_register 9F . .Pp For more information on the HCD device driver initialization process, @@ -59,8 +59,8 @@ The function should be set to the value of the pre-processor macro .Sy HCDI_REGISTER_VERSION . This ensures that if future revisions to this structure are made, -existing drivers should continue to function. Note, that this structure -is +existing drivers should continue to function. +Note, that this structure is .Sy Volatile . Support for older versions or drastic changes may occur at any time and this should not be relied on nor construed as a guarantee against such @@ -75,7 +75,8 @@ of the device driver instance that is registering with the USBA. The .Sy usba_hcdi_register_ops member is a structure of entry points for the USBA framework to call -into the USB framework. It should be allocated with a call to +into the USB framework. +It should be allocated with a call to .Xr usba_alloc_hcdi_ops 9F and released with a call to .Xr usba_free_hcdi_ops 9F , @@ -89,17 +90,17 @@ information on how they should be filled in. .Pp The .Sy usba_hcdi_register_dma_attr -member should be a pointer to a set of DMA attributes. These DMA -attributes will be used by a subset of client device drivers to perform -allocations, in particular scsa2usb. In general, try to make sure that -these DMA attributes are valid for more transforms, though these will -generally be used for bulk transfers. +member should be a pointer to a set of DMA attributes. +These DMA attributes will be used by a subset of client device drivers to +perform allocations, in particular scsa2usb. +In general, try to make sure that these DMA attributes are valid for more +transforms, though these will generally be used for bulk transfers. .Pp The .Sy usba_hcdi_register_iblock_cookie members should be filed in with the general interrupt priority of the -device driver after it has allocated interrupts. Device drivers may -obtain the priority by calling +device driver after it has allocated interrupts. +Device drivers may obtain the priority by calling .Xr ddi_intr_get_pri 9F and then casting the obtained interrupt priority to the .Sy ddi_iblock_cookie_t . diff --git a/usr/src/man/man9s/usba_pipe_handle_data.9s b/usr/src/man/man9s/usba_pipe_handle_data.9s index aed8e36fb6..57d98441fd 100644 --- a/usr/src/man/man9s/usba_pipe_handle_data.9s +++ b/usr/src/man/man9s/usba_pipe_handle_data.9s @@ -15,7 +15,7 @@ .Dt USBA_PIPE_HANDLE_DATA 9S .Os .Sh NAME -.Nm usba_pipe_handle_data +.Nm usba_pipe_handle_data , .Nm usba_pipe_handle_data_t .Nd USBA Pipe Handle Data Structure .Sh SYNOPSIS @@ -24,24 +24,26 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_pipe_handle_data structure is the USB architecture's (USBA) way of representing a pipe. -Every pipe is a part of a USB device. Pipe's may be shared between -client drivers or be exclusive to one. For more background on pipe's -see the +Every pipe is a part of a USB device. +Pipe's may be shared between client drivers or be exclusive to one. +For more background on pipe's see the .Sy USB Endpoint Background section of .Xr usba_hcdi 9E . .Pp This structure is provided to HCD driver's when performing requests of -various kinds. The majority of the structures listed here are +various kinds. +The majority of the structures listed here are .Em read-only ; however, HCD drivers are allowed to update a single member, listed -below. All of the writable members are protected by a lock, the member +below. +All of the writable members are protected by a lock, the member .Sy p_mutex . See the .Sy Locking @@ -50,13 +52,13 @@ section in for more information on lock ordering and when HCD drivers should enter this lock. .Pp -A pipe handle has an explicit life cycle wih a device driver. The driver -first sees the pipe handle when its +A pipe handle has an explicit life cycle wih a device driver. +The driver first sees the pipe handle when its .Xr usba_hcdi_pipe_open 9E -entry point is called. At that time, the HCD driver has the change to -store private data on the handle. This pipe handle will be used in -subsequent requests until the handle is closed, through a call to the -HCD driver's +entry point is called. +At that time, the HCD driver has the change to store private data on the handle. +This pipe handle will be used in subsequent requests until the handle is closed, +through a call to the HCD driver's .Xr usba_hcdi_pipe_close 9E entry point. .Sh STRUCTURE MEMBERS @@ -77,19 +79,21 @@ The .Sy p_usba_device member points to the .Xr usba_device 9S -structure that this pipe belongs to. This member should always be set -for an endpoint handed to an HCD driver. +structure that this pipe belongs to. +This member should always be set for an endpoint handed to an HCD driver. .Pp The .Sy p_ep member is filled in with the endpoint descriptor that represents this -device. The endpoint structure is documented in +device. +The endpoint structure is documented in .Xr usb_ep_descr 9S . .Pp The .Sy p_xep member is filled in with the endpoint descriptor and any additional -endpoint descriptors that may exist. The structure is documented in +endpoint descriptors that may exist. +The structure is documented in .Xr usb_ep_xdescr 9S . The endpoint descriptor is the same in both .Sy p_ep @@ -98,11 +102,12 @@ and .Pp The .Sy p_hcd_private -member is reserved for use with HCD drivers. An HCD driver may set -this member during +member is reserved for use with HCD drivers. +An HCD driver may set this member during .Xr usba_hcdi_pipe_open 9E . If set, it can reference this member throughout the life time of the -pipe. The driver should ensure to clean it up when its +pipe. +The driver should ensure to clean it up when its .Xr usba_hcdi_pipe_close 9E entry point is called. .Pp @@ -114,8 +119,8 @@ The mutex should be entered whenever the value is being manipulated. .Pp The .Sy p_req_count -member indicates the number of outstanding requests on the pipe. When -performing +member indicates the number of outstanding requests on the pipe. +When performing .Em periodic interrupt or isochronous transfers, it is the responsibility of the HCD driver to increment the value of @@ -131,9 +136,10 @@ member. .Pp The HCD driver should take special care to ensure that the value of .Sy p_req_count -is always greater than one. There should always be an outstanding -request that an HCD driver has for the pipe, especially if it is a -periodic endpoint. It should only manipulate this member while it owns +is always greater than one. +There should always be an outstanding request that an HCD driver has for the +pipe, especially if it is a periodic endpoint. +It should only manipulate this member while it owns .Sy p_mutex . .Sh SEE ALSO .Xr usba_hcdi_pipe_close 9E , diff --git a/usr/src/pkg/manifests/system-dtrace-tests.mf b/usr/src/pkg/manifests/system-dtrace-tests.mf index 6fb623704e..3e0c300ea8 100644 --- a/usr/src/pkg/manifests/system-dtrace-tests.mf +++ b/usr/src/pkg/manifests/system-dtrace-tests.mf @@ -358,6 +358,8 @@ file path=opt/SUNWdtrt/tst/common/aggs/tst.sizedkeys.d mode=0444 file path=opt/SUNWdtrt/tst/common/aggs/tst.sizedkeys.d.out mode=0444 file path=opt/SUNWdtrt/tst/common/aggs/tst.stddev.d mode=0444 file path=opt/SUNWdtrt/tst/common/aggs/tst.stddev.d.out mode=0444 +file path=opt/SUNWdtrt/tst/common/aggs/tst.stddev.normalize.d mode=0444 +file path=opt/SUNWdtrt/tst/common/aggs/tst.stddev.normalize.d.out mode=0444 file path=opt/SUNWdtrt/tst/common/aggs/tst.subr.d mode=0444 file path=opt/SUNWdtrt/tst/common/aggs/tst.sum.d mode=0444 file path=opt/SUNWdtrt/tst/common/aggs/tst.sum.d.out mode=0444 diff --git a/usr/src/uts/common/fs/dnlc.c b/usr/src/uts/common/fs/dnlc.c index 32ac33c879..0ec57ff7f7 100644 --- a/usr/src/uts/common/fs/dnlc.c +++ b/usr/src/uts/common/fs/dnlc.c @@ -20,6 +20,7 @@ */ /* * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, Joyent, Inc. * Copyright (c) 2017 by Delphix. All rights reserved. */ @@ -67,12 +68,12 @@ /* * We want to be able to identify files that are referenced only by the DNLC. * When adding a reference from the DNLC, call VN_HOLD_DNLC instead of VN_HOLD, - * since multiple DNLC references should only be counted once in v_count. This - * file contains only two(2) calls to VN_HOLD, renamed VN_HOLD_CALLER in the - * hope that no one will mistakenly add a VN_HOLD to this file. (Unfortunately - * it is not possible to #undef VN_HOLD and retain VN_HOLD_CALLER. Ideally a - * Makefile rule would grep uncommented C tokens to check that VN_HOLD is - * referenced only once in this file, to define VN_HOLD_CALLER.) + * since multiple DNLC references should only be counted once in v_count. The + * VN_HOLD macro itself is aliased to VN_HOLD_CALLER in this file to help + * differentiate the behaviors. (Unfortunately it is not possible to #undef + * VN_HOLD and retain VN_HOLD_CALLER. Ideally a Makefile rule would grep + * uncommented C tokens to check that VN_HOLD is referenced only once in this + * file, to define VN_HOLD_CALLER.) */ #define VN_HOLD_CALLER VN_HOLD #define VN_HOLD_DNLC(vp) { \ @@ -634,7 +635,7 @@ dnlc_lookup(vnode_t *dp, const char *name) * put a hold on it. */ vp = ncp->vp; - VN_HOLD_CALLER(vp); /* VN_HOLD 1 of 2 in this file */ + VN_HOLD_CALLER(vp); mutex_exit(&hp->hash_lock); ncstats.hits++; ncs.ncs_hits.value.ui64++; diff --git a/usr/src/uts/common/fs/lookup.c b/usr/src/uts/common/fs/lookup.c index 7dc83ff8d5..789509ecfb 100644 --- a/usr/src/uts/common/fs/lookup.c +++ b/usr/src/uts/common/fs/lookup.c @@ -23,6 +23,7 @@ * Copyright 2015 Nexenta Systems, Inc. All rights reserved. * Copyright 2016 Joyent, Inc. * Copyright (c) 1988, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, Joyent, Inc. */ /* Copyright (c) 1983, 1984, 1985, 1986, 1987, 1988, 1989 AT&T */ diff --git a/usr/src/uts/common/fs/zfs/dbuf.c b/usr/src/uts/common/fs/zfs/dbuf.c index b2e6595190..7168e848ca 100644 --- a/usr/src/uts/common/fs/zfs/dbuf.c +++ b/usr/src/uts/common/fs/zfs/dbuf.c @@ -561,19 +561,15 @@ dbuf_evict_notify(void) if (tsd_get(zfs_dbuf_evict_key) != NULL) return; + /* + * We check if we should evict without holding the dbuf_evict_lock, + * because it's OK to occasionally make the wrong decision here, + * and grabbing the lock results in massive lock contention. + */ if (refcount_count(&dbuf_cache_size) > dbuf_cache_max_bytes) { - boolean_t evict_now = B_FALSE; - - mutex_enter(&dbuf_evict_lock); - if (refcount_count(&dbuf_cache_size) > dbuf_cache_max_bytes) { - evict_now = dbuf_cache_above_hiwater(); - cv_signal(&dbuf_evict_cv); - } - mutex_exit(&dbuf_evict_lock); - - if (evict_now) { + if (dbuf_cache_above_hiwater()) dbuf_evict_one(); - } + cv_signal(&dbuf_evict_cv); } } diff --git a/usr/src/uts/common/fs/zfs/dmu_send.c b/usr/src/uts/common/fs/zfs/dmu_send.c index c9a79b94e8..92f24cd7f2 100644 --- a/usr/src/uts/common/fs/zfs/dmu_send.c +++ b/usr/src/uts/common/fs/zfs/dmu_send.c @@ -1102,10 +1102,17 @@ dmu_adjust_send_estimate_for_indirects(dsl_dataset_t *ds, uint64_t uncompressed, */ uint64_t recordsize; uint64_t record_count; + objset_t *os; + VERIFY0(dmu_objset_from_ds(ds, &os)); /* Assume all (uncompressed) blocks are recordsize. */ - err = dsl_prop_get_int_ds(ds, zfs_prop_to_name(ZFS_PROP_RECORDSIZE), - &recordsize); + if (os->os_phys->os_type == DMU_OST_ZVOL) { + err = dsl_prop_get_int_ds(ds, + zfs_prop_to_name(ZFS_PROP_VOLBLOCKSIZE), &recordsize); + } else { + err = dsl_prop_get_int_ds(ds, + zfs_prop_to_name(ZFS_PROP_RECORDSIZE), &recordsize); + } if (err != 0) return (err); record_count = uncompressed / recordsize; @@ -1174,6 +1181,10 @@ dmu_send_estimate(dsl_dataset_t *ds, dsl_dataset_t *fromds, err = dmu_adjust_send_estimate_for_indirects(ds, uncomp, comp, stream_compressed, sizep); + /* + * Add the size of the BEGIN and END records to the estimate. + */ + *sizep += 2 * sizeof (dmu_replay_record_t); return (err); } diff --git a/usr/src/uts/common/sys/dnlc.h b/usr/src/uts/common/sys/dnlc.h index 070506ee31..26f1f1dc0c 100644 --- a/usr/src/uts/common/sys/dnlc.h +++ b/usr/src/uts/common/sys/dnlc.h @@ -187,7 +187,6 @@ void dnlc_purge_vp(vnode_t *); int dnlc_purge_vfsp(vfs_t *, int); void dnlc_remove(vnode_t *, const char *); int dnlc_fs_purge1(struct vnodeops *); -vnode_t *dnlc_reverse_lookup(vnode_t *, char *, size_t); void dnlc_reduce_cache(void *); #endif /* defined(_KERNEL) */ |