livedumpstart Command

Purpose

Initiates a live dump.

Syntax

livedumpstart [ -e ] [ -h ] [ -p pseudo-component ] [ -q ] [ -r ] [ -u ] [ -c component_path ] [ -l logical_alias ] [ -t type ] [ -C component_path | -L logical_alias | -T type ] attribute [ ... ]

Description

The livedumpstart command is used to start a live dump. The dump can include one or more components. Only serialized dumps are used. It can be limited to one pass. The data acquired is dumped to the file system, and the dump is placed in a directory. The dump can be designated as informational or critical.

Components are dumped in the order that you specify. Specify the failing component with either the -C, -L, or -T flag. You cannot specify the name of a pseudo-component.

The data is dumped at the detail level that you set for that component, see the dumpctrl command for more information about managing system and live dumps.

If you do not specify the -q flag, the livedumpstart command displays a message containing the name of the dump.

Flags

Item	Description
-c [+] component_path[+] [:parameter_list]	Specifies a component by component path name. You can specify the -c flag more than once. If you precede a component name with a plus sign (+), the data from that component and its ancestors are dumped. If you follow a component name with a plus sign (+), the data from that component and its descendents are dumped. You can pass parameters to the component. Follow the component name and the optional "+" :parameter_list. A parameter_list consists of parameters separated by commas. It can also be groups separated by blanks. If a component and its ancestors or descendents are specified, parameters are passed only to the component, not to the ancestors or descendents.
-C [+] component_path[+] [:parameter_list]	Specifies a failing component by component path name. At most one failing component can be specified. Thus, only one of the -C, -L, and -T flags is allowed, and that component specification must refer to a single component. If -C basecomp+ is specified, and basecomp is not live dump aware, then only one component among basecomp and its descendents can be live dump aware. However, if basecomp is live dump aware, basecomp is the failing component, and it might have multiple live-dump-aware descendents. Tip: These rules also apply to a component and its ancestors. If a component is preceded with a plus sign, "+", then that component and its ancestors are dumped. If a component is followed with a plus sign, "+", then that component and its descendents are dumped. If parameters are passed to the component, the component and the optional "+" are followed with :parameter_list. A parameter_list consists of parameters separated by commas, or keyword=parm_list pairs separated by blanks. See the section on specifying parameters from the command line for more information. Note that if a component and its ancestors and/or descendents are specified, parameters are passed only to the component, not to the ancestors or descendents.
-e	Displays an estimate for the size of the dump, which contains the specified components or pseudo-components. This flag obtains a size estimate for the dump without starting the dump. To get an accurate estimate, use the same components, parameters, and detail level that you intend to use for the dump. The estimate takes into account the compression factor.
-h	Shows help text. If the -h flag is specified with other components or pseudo-components, the help text for those components is shown.
-l [+] logical_alias[+] [:parameter_list]	Specifies a component by component logical alias. You can specify multiple -c, -l, and -t flags. If a logical alias is preceded with a plus sign "+", then that alias and its ancestors are dumped. If a logical alias is followed with a plus sign "+", then that alias and its descendents are dumped. If parameters are passed to the component, the component and the optional "+" are followed with :parameter_list. A parameter_list consists of parameters separated by commas, or keyword=parm_list pairs separated by blanks. See the section on specifying parameters from the command line for more information. Note that if a component and its ancestors, descendents, or both are specified, parameters are passed only to the component, not to the ancestors or descendents.
-L [+] logical_alias[+] [:parameter_list]	Specifies a failing component by component logical alias. At most one failing component can be specified. Thus, only one of the -C, -L, and -T flags is allowed, and that component specification must refer to a single component. If -L basecomp+ is specified, and basecomp is not live dump aware, then only one component among basecomp and its descendents can be live dump aware. However, if basecomp is live dump aware, basecomp is the failing component, and it might have multiple live-dump-aware descendents. Tip: These rules also apply to a component and its ancestors. If a logical alias is preceded with a plus sign "+", then that alias and its ancestors are dumped. If a logical alias is followed with a plus sign "+", then that alias and its descendents are dumped. If parameters are passed to the component, the component and the optional "+" are followed with :parameter_list. A parameter_list consists of parameters separated by commas, or keyword=parm_list pairs separated by blanks. See the section on specifying parameters from the command line for more information. Note that if a component and its ancestors and/or descendents are specified, parameters are passed only to the component, not to the ancestors or descendents.
-p pseudo-component [:parameter_list]	Specifies a pseudo-component. Note: A pseudo-component (-p) cannot be a failing component. If parameters are to be passed to the pseudo-component, the pseudo-component must be followed by a :parameter_list. A parameter_list consists of parameters separated by commas, or keyword=parm_list pairs separated by blanks. See the section on specifying parameters from the command line for more information. The following table is the description of pseudo-components.
	Specification	Parameters	Description
	eaddr:hex,hex	address and length, hexadecimal values	Dumps memory by kernel effective address.
	context:addr=hex-eaddr \| tid_t=hex-tid_t \| cpu=dec-lcpu \| bid=dec-bid	hex-eaddr - context (MST) effective address, hex-tid_t - kernel thread id, dec-lcpu - logical cpu, dec-bid - cpu bind id	Dumps a kernel context. This includes lightweight memory trace data, stack and thread state information.
	tid_t:hex-tid	hexadecimal kernel thread id	Dumps a kernel thread by kernel thread ID.
	tid:dec-tid	decimal kernel thread id	Dumps a kernel thread by kernel thread ID, and the ID is decimal.
	tslot:dec-slot	decimal kernel thread slot number	Dumps a kernel thread by kernel thread ID, and the thread is specified by decimal slot number.
	pid_t:hex-pid	hexadecimal kernel process id	Dumps a process by process ID.
	pid:dec-pid	decimal process id	Dumps a process by process ID, and the ID is decimal.
	pslot:dec-slot	decimal process slot number	Dumps a process by process ID, and the process is specified by decimal slot number.
	errbuf	no parameters	Dumps kernel error logging data.
	mtrc:common-size, rare-size	common and rare decimal buffer sizes	Dumps lightweight memory trace data.
	systrace:dec-size	decimal buffer size	Dump system trace data. If the buffer size is 0, the entire buffer is dumped.
	comptrace:component, dec-length	component name and decimal amount of data. The component can be an alias, and the length can be zero to dump the entire buffer.	Dumps component trace data.
	kernext:pathname	extension's full path name	Allows symbol resolution for this extension.
-q	Specifies quiet mode. No messages are displayed.
-r	Dumps data for any subcomponents of the specified components. Specifying this flag is equivalent to specifying every component followed by a "+".
-t [+] type[+] [:parameter_list]	Specifies a component by its type or subtype. You can specify multiple -c, -l, and -t flags. If a type or subtype is preceded with a plus sign (+), then that component and its ancestors are dumped. If a type or subtype is followed with a plus sign (+), then that component and its descendents are dumped. If parameters are passed to the component, the component and the optional "+" are followed with :parameter_list. A parameter_list consists of parameters separated by commas, or keyword=parm_list pairs separated by blanks. See the section on specifying parameters from the command line for more information. Note that if a component and its ancestors and/or descendents are specified, parameters are passed only to the component, not to the ancestors or descendents.
-T [+] type[+] [:parameter_list]	Specifies a failing component by component type or subtype. At most one failing component can be specified. Thus, only one of the -C, -L, and -T flags is allowed, and that component specification must refer to a single component. If -T type+ is specified, and type is not live dump aware, then only one component among type and its descendents can be live dump aware. However, if a component of the type type is live dump aware, it is the failing component, and it might have multiple live-dump-aware descendents. Tip: These rules also apply to a component and its ancestors. If a type or subtype is preceded with a plus sign (+), then that component and its ancestors are dumped. If a type is followed with a plus sign (+), then that component and its descendents are dumped. If parameters are passed to the component, the component and the optional "+" are followed with :parameter_list. A parameter_list consists of parameters separated by commas, or keyword=parm_list pairs separated by blanks. See the section on specifying parameters from the command line for more information. Note that if a component and its ancestors, descendents, or both are specified, parameters are passed only to the component, not to the ancestors or descendents.
-u	Dumps the data for the components that are "above" the specified components in the component hierarchy. This is equivalent to specifying every component preceded by a "+".

You can use wildcard when you specify component names and aliases. Remember that any parameters that you specify are passed to all matching components. You cannot use all or an asterisk (*).

Restriction: You can only specify one failing component, so -C comp* can resolve to only one component.

Attributes

The dump attributes are specified with keyword=value pairs. They are used to configure dump parameters, construct dump headers and edit symptom information. You change attributes by specifying an Attribute=Value parameter. If you have the proper authority you can set the following required attribute:

Item	Description
symptom=string	Provides symptom string details that must be supplied to further qualify the dump. The maximum length of this string is 2047 characters.

If you have the proper authority you can set the following optional group attributes:

Item	Description
errcode=code	Specifies the error code for the symptom string. If it begins with 0x, the value is in hex; if it begins with 0, the value is octal; otherwise it is decimal.
force=yes\|no	If yes, overrides duplicate checking, dumps the data regardless of whether it duplicates a previous dump. The default is yes, because any dump taken from the command line should not be treated as a duplicate.
log=yes\|no	Specifies whether a log entry should be written when the dump completes. If you specify yes, a message is written to the error log. The default is yes.
noforce	For software initiated live dumps. Specifies whether to initiate the dump if it duplicates a previous dump that was initiated within the last day. The noforce attribute makes the dump subject to duplicate elimination.
nolog	Specifies whether to a message should be written to the error log when the dump is complete. If it is not specified, dump completion and errors are logged.
prefix=prefix	Specifies the file name prefix. The name can be no more than 63 characters.
priority=priority	Specifies the priority of the dump. You can specify info or critical. The default is critical. If you specify the value info, it indicates the dump is for informational purposes, while critical indicates the dump is necessary to debug a problem.
title=string	Specifies an optional dump title, which can be up to 127 characters.
type=type	Specifies whether data should be collected without freezing the system. serialized\|ser The dump data is gathered when the system is frozen. It might be necessary to use multiple freezes to dump all the data. This is the default. unserialized\|unser Data is gathered without freezing the system. It might be necessary to use multiple freezes to dump all the data. If you specify unserialized, the system is not frozen when gathering the data.
onepass	All data is gathered under one pass. The dump is truncated if all data does not fit in available memory. The default is to use multiple passes if required.

Exit Status

Item	Description
0 (zero)	The livedumpstart command completes successfully and produces a message containing the name of the dump.
nonzero	The livedumpstart command fails and produces an error message. This command fails under the following conditions: One or more parameters are not valid. One or more components are not valid. None of these components can be specified for a live dump. A component attempts to take a live dump from within a live dump. Live dumps are disabled. A dump already exists. This can occur when you specify the force=no attribute. There is insufficient memory. All the data cannot be buffered in this single-pass dump. Too much time is spent while processors are disabled, and this dump is truncated.

Item

Description

0 (zero)

The livedumpstart command completes successfully and produces a message containing the name of the dump.

nonzero

The livedumpstart command fails and produces an error message. This command fails under the following conditions:

One or more parameters are not valid.
One or more components are not valid.
None of these components can be specified for a live dump.
A component attempts to take a live dump from within a live dump.
Live dumps are disabled.
A dump already exists. This can occur when you specify the force=no attribute.
There is insufficient memory.
All the data cannot be buffered in this single-pass dump.
Too much time is spent while processors are disabled, and this dump is truncated.

Security

Only the root user can run this command.

Examples

To dump data for device ent0, and components above it in the component hierarchy, enter the following command:
```
livedumpstart -L +ent0 symptom=foo
```
The failing component is ent0. This creates a dump named ent0.yymmddhhmm.00.DZ. It is a serialized, critical dump.
Tip: According to the rules for specifying the failing component, if ent0 is not live dump aware, but multiple ancestors are, then this command fails. If ent0 is not live dump aware, and only one ancestor is, this ancestor is used as the failing component.
To create an informational dump of the process management data for processes 856 and 10272, enter the following command:
```
livedumpstart -p pid:856 -p pid:10272 \
              info prefix=mydump title="process dump" symptom="foo"
```
The dump is named mydump.nocomp.yymmddhhmm.00.DZ. Note there is no failing component.
To create a serialized, one-pass dump where foo is the failing component, enter the following command:
```
livedumpstart -C foo+:block=45ab8 -pcontext:tid_t=57B29 onepass symptom=bar
```
This command dumps foo, its descendents, and the context for kernel thread 57B29. The dump is named foo.yymmddhhmm.00.DZ.
A subsystem has the parent component with alias subsyst. It has only one live-dump-aware component. To create a serialized live dump of this subsystem, you might use the following command:
```
livedumpstart -L subsyst+ title="Dump of subsystem subsyst" symptom=foo
```
To specify that process 1234 is dumped along with 0x400 bytes starting at 0x45928, enter the following command:
```
livedumpstart -p tid:1234 -p eadder:45928,400 symptom=foo
```
In this example, there is no failing component.