lspath command

Purpose

Displays information about paths to a MultiPath I/O (MPIO) capable device.

Syntax

lspath [ -dev DeviceName ] [ -pdev Parent ] [ -status Status ] [ -conn Connection ] [ -field FieldName ... ] [ -fmt Delimiter ]

lspath -dev DeviceName -pdev Parent [ -conn Connection ] -lsattr [ -attr Attribute... ] [ -field FieldName ... ] [ -fmt Delimiter ]

lspath -dev DeviceName -pdev Parent [ -conn Connection ] -range Attribute [ -field FieldName ... ] [ -fmt Delimiter ]

Description

The lspath command displays one of three types of information about paths to an MPIO capable device. It either displays the operational status for one or more paths to a single device, or it displays one or more attributes for a single path to a single MPIO capable device. The first syntax shown above displays the operational status for one or more paths to a particular MPIO capable device. The second syntax displays one or more attributes for a single path to a particular MPIO capable device. Finally, the third syntax displays the possible range of values for an attribute for a single path to a particular MPIO capable device.

Displaying Path Status with the lspath Command

When displaying path status, the set of paths to display is obtained by searching the device configuration database for paths that match the following criteria:

The target device name matches the device specified with the -dev flag. If the -dev flag is not present, then the target device is not used in the criteria.
The parent device name matches the device specified with the -pdev flag. If the -pdev flag is not present, then parent is not used in the criteria.
The connection matches the connection specified with the -conn flag. If the -conn flag is not present, then connection is not used in the criteria.
The path status matches status specified with the -status flag. If the -status flag is not present, the path status is not used in the criteria.

If none of the -dev, -pdev, -conn, or -status flags are specified, then all paths known to the system are displayed.

By default, this command will display the information in columnar form. When no flags are specified that qualify the paths to display, the format of the output is:

status device  parent

Possible values that can appear for the status column are:

enabled: Indicates that the path is configured and operational. It will be considered when paths are selected for IO.
disabled: Indicates that the path is configured, but not currently operational. It has been manually disabled and will not be considered when paths are selected for IO.
failed: Indicates that the path is configured, but it has had IO failures that have rendered it unusable. It will not be considered when paths are selected for IO.
defined: Indicates that the path has not been configured into the device driver.
missing: Indicates that the path was defined in a previous boot, but it was not detected in the most recent boot of the system.
detected: Indicates that the path was detected in the most recent boot of the system, but for some reason it was not configured. A path should only have this status during boot and so this status should never appear as a result of the lspath command.

Displaying Path Attributes with the lspath Command

When displaying attributes for a path, the path must be fully qualified. Multiple attributes for a path can be displayed, but attributes belonging to multiple paths cannot be displayed in a single invocation of the lspath command. Therefore, in addition to the -lsattr, -dev, and -pdev flags, the -conn flags are required to uniquely identify a single path. For example:

if only one path between a device and a specific parent, the -conn flag is not required
if there are multiple paths between a device and a specific parent, the -conn flag is required

Furthermore, the -status flag is not allowed.

By default, this command will display the information in columnar form.

attribute   value    description         user_settable

Flags

Flag name	Description
-attr Attribute	Identifies the specific attribute to list. The 'Attribute' is the name of a path specific attribute. When this flag is provided, only the identified attribute is displayed. Multiple instances of this flag may be used to list multiple attributes. If this flag is not specified at all, all attributes associated with the identified path will be listed.
-lsattr	Displays the attribute names, current values, descriptions, and user-settable flag values for a specific path.
-dev Name	Specifies the logical device name of the target device whose path information is to be displayed.
-field FieldNames	Specifies the list of fields to display. The following fields are supported: status Status of the path name Name of the device parent Name of the parent device conn Path connection.
-fmt Delimiter	Specifies a delimiter character to separate output fields.
-pdev Parent	Indicates the logical device name of the parent device of the path(s) to be displayed.
-range	Displays the legal values for an attribute name. The -range flag displays the list attribute values in a vertical column as follows: `Value1 Value2 . . ValueN` The -range flag displays the range attribute values as x...n(+i) where x is the start of the range, n is the end of the range, and i is the increment.
-status Status	The -status Status flag indicates the status to use in qualifying the paths to be displayed. When displaying path information, the allowable values for this flag are: enabled Display paths that are enabled for MPIO path selection. disabled Display paths that are disabled from MPIO path selection. failed Display paths that are failed due to IO errors. available Display paths whose path_status is PATH_AVAILABLE (that is, paths that are configured in the system, includes enabled, disabled, and failed paths). defined Display paths whose path_status is PATH_DEFINED. missing Display paths whose path_status is PATH_MISSING.
-conn Connection	Indicates the connection information to use in qualifying the paths to be displayed.

Exit Status

Return code	Description
1	Invalid status value.

Examples

To display, without column headers, the set of paths whose operational status is disabled, enter:
```
lspath -status disabled
```
The system will display a message similar to the following:
```
 disabled  hdisk1   scsi1 
disabled  hdisk2   scsi1 
disabled  hdisk23  scsi8 
disabled  hdisk25  scsi8
```
To display the set of paths whose operational status is failed, enter:
```
 lspath -status failed
```
The system will display a message similar to the following:
```
  failed  hdisk1   scsi1 
failed  hdisk2   scsi1 
failed  hdisk23  scsi8 
failed  hdisk25  scsi8
```
If the target device is a SCSI disk, to display all attributes for the path to parent scsi0 at connection 5,0, use the command:
```
 lspath -dev hdisk10 -pdev scsi0 -conn "5,0" -lsattr
```
The system will display a message similar to the following:
```
weight     1      Order of path failover selection  true
```

Related Information

The lsmap command, the mkpath command, the chpath command, and the rmpath command.

Last updated: Wed, November 18, 2020