zfsadm fsinfo

Purpose

Displays detailed information about a zFS file system, which is also known as a zFS aggregate.

Options

-aggregate name

Specifies the name of the aggregate to be displayed. The aggregate name is not case-sensitive and is translated to uppercase. To specify multiple aggregates with similar names, use an asterisk (*) at the beginning, at the end, or both at the beginning and the end of name as a wildcard. If -aggregate name is specified with wildcards, the default display is -basic. Otherwise, the default display is -owner. See Usage notes for zfsadm fsinfo for more information.

-all

Displays information for all aggregates in the sysplex. It is the default when -aggregate and -path are not specified. The default information display will be as if -basic were specified.

-basic

Displays a line of basic file system information for each specified file system. This option is the default in the following situations:

• The -all option is specified but -full, -owner, and -reset are not specified.
• None of -aggregate, -all, -path, -full, -owner, and -reset options are specified.
• The -sort and -exceptions options are specified and neither -full nor -owner is specified.
• The -aggregate option is specified with one or more wildcards.

See Usage notes for zfsadm fsinfo for more information.

-exceptions

Displays information about any specified aggregate that is quiesced, disabled, had grow failures, is low on space or damaged. Any specified aggregate is also displayed if it has had XCF communication failures or an error because it ran out of space or when doing an I/O operation. This option cannot be specified with -reset, -path, -select and -aggregate with no wildcard in name. Information is displayed by default as if the -basic option were specified. See Usage notes for zfsadm fsinfo for more information.

-full

Displays information that is maintained by the system owning each specified file system. See Table 3 for a description of the information displayed for the owner. It also displays information that is locally maintained by each system in the sysplex that has each specified file system locally mounted. For information about local statistics that are displayed when the -full option is specified, see Table 5.

-help

Prints the online help for this command. All other valid options that are specified with this option are ignored.

-level

Prints the level of the zfsadm command. This information is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level are ignored.

-owner

Displays only information that is maintained by the system owning each specified file system. This option is the default when -aggregate without wildcards is specified. See Usage notes for zfsadm fsinfo for more information.

-path path

Specifies the path name of a file or directory that is contained in the file system for which information is to be displayed. The path name is case-sensitive and can start with or without a slash (/). The default information display will be as if -owner were specified.

-reset

Resets zFS statistics that are related to each specified file system.

-select criteria

Displays each specified file system that matches the criteria. Information is displayed by default as if the -basic option were specified. The information that is displayed can also be sorted by using the -sort option.

To use this option, specify a selection criteria from Table 1.

This option cannot be specified with -exceptions, -reset, -path, and -aggregate with no wildcard in name. See Usage notes for zfsadm fsinfo for more information.

-sort sort_name

Specifies that the information displayed is to be sorted as specified by the value of sort_name. The default is sort by Name. This option cannot be specified with -reset. The valid sorting options are listed in Table 4.

Usage notes for zfsadm fsinfo

1. The zfsadm fsinfo command displays detailed information about the specified file systems. Normally, file systems must be attached before this command can be used to display their information. However, when a specific aggregate name (with no wildcards) is specified, the file system does not need to be attached. You can use several methods to specify aggregates, based on their names, as follows:
   • -aggregate with an exact aggregate name. The aggregate name is not case-sensitive and is translated to uppercase.
   • -aggregate using a wildcard ('*') at the beginning of the name value to select aggregates with a common suffix.
   • -aggregate using a wildcard ('*') at the end of the name value to select aggregates with a common prefix.
   • -aggregate using a wildcard ('*') at the beginning and the end of the name value to select aggregates with both a common prefix and a common suffix.
   • -path with the path name of a file or directory in a zFS file system. Information for the file system that contains the file or directory is displayed.
   Note: To ensure proper processing by the z/OS UNIX shell, put single quotation marks around the wildcard (*).

   The -all option selects all file systems that are attached in the sysplex. It is the default.

2. The -owner option displays all available information for each specified file system from the zFS-owning system. The information is obtained via XCF communication with the owning system if the owning system is not the local system.
3. Aggregates can be selected by use of the -select option. To use this option, specify a criteria from the following table. You can specify more than one criteria by using a comma to separate them. Table 1 lists the criteria that you can use.

   Table 1. Criteria for selecting aggregates

   Criteria	Shows aggregates that meet the criteria
   CE	Had XCF communication failures between client systems and owning systems. This typically means that applications have gotten timeout errors.
   DA	Are marked damaged by the zFS salvager.
   DI	Are disabled for reading and writing.
   GD	Are disabled for dynamic grow.
   GF	Had failed dynamic grow attempts.
   GR	Are currently being grown.
   IE	Have had disk I/0 errors.
   L	Have less than 1 MB of free space, which means that increased XCF traffic is required for writing files.
   NS	Are mounted NORWSHARE.
   OV	Contain extended (v5) directories that are using overflow pages.
   Q	Are currently quiesced.
   RO	Are mounted read-only.
   RQ	Had application activity.
   RW	Are mounted read/write.
   RS	Are mounted RWSHARE.
   SE	Have returned ENOSPC errors to applications.
   TH	Have sysplex thrashing objects in them.
   V4	Are version 1.4.
   V5	Are version 1.5.
   V5D	Are disabled for conversion to version 1.5.
   WR	Had application write activity.

4. Aggregates can be selected using the -exceptions option. This option can be useful for identifying file systems that have encountered unexpected conditions, and might need attention. Unexpected conditions include I/O errors, XCF communication failures or being low on space. An aggregate can also be damaged, quiesced, or disabled.
5. The -basic option displays the file system name, the zFS-owning system name, and file system status. Table 2 lists the values of the file system status. A Legend string is also displayed at the end of the output as a quick reference to show the definitions of the abbreviated status values.
6. When you use the -owner option, the displayed information has the file system status as part of the output. The status field contains abbreviated values. For quick reference, these values are defined in a Legend string at the end of the output. The full definitions of these abbreviations are listed in Table 2.

   Table 2. Definitions of abbreviated values when the -basic or -owner options are specified

   Values	Definition
   CE	The aggregate had XCF communication failures (timeout errors) since the last statistics reset.
   DA	Salvage considered the aggregate damaged and it has not been repaired yet.
   DI	The aggregate is disabled for access.
   GD	Dynamic grow was disabled. This is set if an aggregate has the AGGRGROW attribute assigned to it but due to a dynamic grow failure will not attempt future dynamic grows until an explicit administrator grow command is issued against that file system.
   GF	Had failed dynamic grow attempts.
   GR	The aggregate is being grown.
   IE	The aggregate had disk I/O errors since the last statistics reset.
   L	The aggregate is low on space as defined by the zFS distributed bitmap reservation algorithms (less than 1 MB of free space left).
   NM	The aggregate is attached, but not mounted.
   NS	The aggregate is mounted NORWSHARE, or the aggregate is attached.
   OV	The aggregate has directories with overflow pages.
   Q	The aggregate is quiesced.
   RO	The aggregate is mounted in R/O mode.
   RQ	Had application activity.
   RW	The aggregate is mounted R/W.
   RS	The aggregate is mounted RWSHARE.
   SE	The aggregate ran out of space at some time since the last statistics reset.
   TH	The aggregate has sysplex thrashing objects.

7. The -owner option displays the statistics that are shown in Table 3.

   Table 3. Statistics displayed when the -owner option is specified

   Statistics	Description
   Owner	The name of the system that currently owns the aggregate.
   Status	The status of the aggregate as known by the owning system. The display is a subset of the information that is available in the -basic display because it shows only what the owner knows. The -basic display is a one-line summary for all chosen sysplex members.
   Converttov5	Indicates whether the file system has the CONVERTTOV5 attribute assigned to it. If the aggregate is version 1.4, or is version 1.5 and does not have the CONVERTTOV5 attribute assigned to it, the second value will be n/a. If the aggregate has the CONVERTTOV5 attribute assigned to it, the second value will indicate whether automatic conversion is ENABLED or DISABLED. One possible reason it could be DISABLED is that the aggregate was quiesced after this system assumed ownership of the file system.
   Size	Size of the aggregate in kilobytes.
   Free 8K Blocks	Number of free 8 K blocks.
   Free 1K Fragments	Number of free fragments in partially allocated blocks.
   Log File Size	Total space in kilobytes occupied by the log file, including indirect blocks.
   Bitmap Size	Size of the bitmap file in kilobytes, including indirect blocks.
   Anode Table Size	Total space occupied by the anode table in kilobytes, including indirect blocks.
   File System Objects	The number of objects in the file system. This includes files, directories, symbolic links, ACLs and z/OS UNIX special files.
   Version	The version of the aggregate. For example, 1.4 or 1.5.
   Overflow Pages	The number of overflow pages that are allocated to extended (v5) directories.
   Overflow HighWater	The highest number of overflow pages that were ever allocated on disk in extended (v5) directories.
   Thrashing Objects	The current number of sysplex thrashing objects in the file system at one time.
   Thrash Resolutions	The number of times the owner invoked the thrash resolution protocol (as opposed to the normal direct I/O protocol) to resolve sysplex contention of objects in the file system.
   Token Revocations	The number of times the owner revoked tokens from other sysplex members, which means there was contention on an object and a callback had to be made to one or more clients.
   Revocation Wait Time	The average time that it took to revoke tokens from clients.
   Space Monitoring	The threshold and increment for space monitoring. 0,0 is used to mean that there is no space monitoring in use for the file system.
   Devno	z/OS UNIX device number for the mounted file system.
   Quiesce Jobname	Name of job that quiesced the aggregate.
   Quiesce System	Name of the system where the application was running that quiesced the aggregate.
   Quiesce ASID	ASID of the job that quiesced the aggregate.
   File System Grow	Shows whether the Aggrgrow attribute is enabled (ON or OFF). It also shows the number of grows that were performed since this system assumed ownership of the file system.
   Audit Fid	The audit fid that is used to represent the file system for SAF auditing.
   File System Creation Time	Time that the file system was last formatted.
   Time of Ownership	Time that the current owning system assumed ownership of the file system. That is, the time of its primary mount or when it last assumed ownership due to aggregate movement.
   Statistics Reset Time	Time that the owner statistics were last reset.
   Quiesce Time	The time that the file system was last quiesced.For critical I/O operations, zFS will send I/O operations in parallel, up to the maximum number that the parallel access volume (PAV) device can handle concurrently.
   Last Grow Time	The time that the file system was last grown (by command or dynamically) since this system assumed ownership of the file system.
   Connected Clients	This lists all client systems in the sysplex that have local mounts for a file system that is mounted RWSHARE.

8. Table 4 lists the sorting options when the -sort option is specified.

   Table 4. Sorting options when the -sort option is specified

   Sorting option	Function
   Name	Sort by file system name, in ascending order. This sorting option is the default.
   Requests	Sort by the number of external requests that are made to the file system by user applications, in descending order. The most actively requested file systems are listed first.
   Response	Sort by response time of requests to the file system, in descending order. The slower responding file systems are listed first.

9. The -full option displays statistics for each specified file system from the zFS owning system and from each system in the sysplex that has it locally mounted. This is obtained via XCF communication with each system in the sysplex. The owning system statistics are described in Table 3. The local statistics are described in Table 5.

   Table 5. Local statistics displayed when the full option is specified

   Statistics	Description
   Application Reads	The number of read requests that were made by applications for files and directories in this file system.
   Application Writes	The number of write requests that were made by applications for files or directories in this file system.
   Average	The average task wait time when it had to wait for an I/O operation. This is the full wait time, including any queue wait time and device response time.
   Avg. Rd XCF Resp. Time	The average response time for XCF read requests for objects on the owning system.
   Avg. Read Resp. Time	The average response time for read requests that were made by applications for files or directories in this file system.
   Avg. Wr XCF Resp. Time	The average response time for XCF write requests for objects on the owning system.
   Avg. Write Resp. Time	The average response time for write requests that were made by applications for files or directories in this file system.
   Canceled Operations	The number of times a task was asynchronously abended (forced or canceled) while accessing this file system.
   DDNAME	The DDNAME for the data set allocation on this system.
   Disk IO Errors	The number of disk I/O errors for disk I/O operations performed on this system.
   ENOSPC Errors	The number of out of space (ENOSPC) errors that were seen by applications for this file system on this system.
   Kbytes	The number of kilobytes read from the DASD volume for this system.
   LFS Held Vnodes	The number of vnodes that the z/OS UNIX logical file system has allocated for the file system.
   Metadata Cache 8K Pages	The number of 8 K pages in the metadata cache for this file system.
   Mount Time	The time the file system was mounted on this system.
   Open objects	Number of files or directories that are open.
   PAV	The number of noncritical concurrent I/O operations that zFS will send to the DASD at one time for this DASD volume. For critical I/O operations, zFS will send I/O operations in parallel, up to the maximum number that the parallel access volume (PAV) device can handle concurrently. An I/O operation is deemed critical if a task is, or will be waiting on that I/O operation to complete.
   Quiesce Waiters	YES if there are tasks that are waiting for the file system to be unquiesced. Otherwise, NO.
   Reads	The number of disk reads to the DASD volume for this system.
   Read XCF Calls	The number of XCF requests to read objects from the system that owns the file system. This will be zero (0) on the owning system.
   Statistics Reset Time	The time that the statistics for the local file system were last reset.
   Tokens	The number of tokens that are held for objects in the file system by the token manager.
   TOTALS	The totals for all DASD volumes for the file system on this system.
   User Cache 4K Pages	The number of 4 K pages in the user file cache for this file system.
   Vnodes	Number of vnodes in memory for the file system.
   VOLSER	The DASD VOLSER that the file system resides on.
   Waits	The number of times a task had to wait for an I/O operation to complete for disk I/O operations on this system.
   Writes	The number of disk writes to the DASD volume for this system.
   Write XCF Calls	The number of XCF requests to write objects to the system that owns the file system. This will be zero (0) on the owning system.
   XCF Comm. Failures	The number of XCF communication failures (for example, timeouts) on XCF requests made for this file system on this system.

10. All times are in milliseconds. Large numbers are displayed using the following suffixes:

    t

    Multiply the shown value by 1,000,000,000.

    m

    Multiply the shown value by 1000000.

    t

    Multiply the shown value by 1000.

    tr

    Multiply the shown value by 1,000,000,000,000.

    K

    Multiply the shown value by 1024.

    M

    Multiply the shown value by 1048576.

Privilege required

If you are using an IOEFSPRM file in your startup proc, the issuer must have READ authority to the data set that contains the IOEFSPRM file. If you are using parmlib (IOEPRMxx), the issuer does not need special authorization.

Related information