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.

Security

Only the root user can run this command.

Examples

  1. 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.
  2. 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.

  3. 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.

  4. 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

  5. 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.