zfsadm fsinfo

Purpose

zfsadm fsinfo 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 that owns each specified file system. See Table 3 for a description of the information that is 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 that owns 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.

-trace file_name

Specifies the name of the file that will have the trace records written into it. The trace file can be a z/OS UNIX file, an existing MVS sequential data set, or a member of either an existing partitioned data set (PDS) or partitioned data set extended (PDSE). Use this option only at the direction of IBM Support.

For information about preallocation instructions for debugging, see Step 5 (Optional) Preallocate data sets for debugging in zFS installation and configuration steps.

Because MVS data set names must be fully qualified, z/OS UNIX has special rules for specifying MVS data set names in the shell environment. For more information, see Specifying MVS data set names in the shell environment in z/OS UNIX System Services Command Reference.

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.
   Tip: 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 Table 1. You can specify more than one criteria by using a comma to separate them.

   Table 1. Criteria for selecting aggregates

   Value	Shows aggregates that ...
   BK	Contain files currently being backed up.
   CE	Had XCF communication failures between client systems and owning systems. This result typically means that applications have gotten timeout errors.
   CO	Are compressed or partially compressed.
   DA	Are marked damaged by the zFS salvager.
   DI	Are disabled for reading and writing.
   EN	Are encrypted or partially encrypted.
   EP	Are partially encrypted or partially compressed.
   GD	Are disabled for dynamic grow.
   GF	Have 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.
   NC	Are not compressed.
   NE	Are not encrypted.
   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.
   SH	Are currently being shrunk.
   SL	Are currently being salvaged.
   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 by 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	Explanation
   BK	The aggregate contains files that are currently being backed up.
   CE	The aggregate had XCF communication failures (timeout errors) since the last statistics reset.
   CI	The aggregate is partially compressed.
   CO	The aggregate is compressed.
   DA	The salvage operation considered the aggregate damaged and it has not been repaired yet.
   DC	The aggregate is partially decompressed.
   DE	The aggregate is partially decrypted.
   DI	The aggregate is disabled for access.
   EI	The aggregate is partially encrypted.
   EN	The aggregate is encrypted.
   GD	Dynamic grow was disabled. This value 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	The aggregate 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).
   NC	The aggregate is not compressed.
   NE	The aggregate is not encrypted.
   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	The aggregate 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.
   SH	The aggregate is currently being shrunk.
   SL	The aggregate is currently being salvaged.
   TH	The aggregate has objects in the sysplex that are undergoing thrashing.

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
   Anode Table Size	Total space that is occupied by the anode table in kilobytes, including indirect blocks.
   Audit Fid	The auditfid that is used to represent the file system for SAF auditing.
   Backups	Number of files that are being backed up.
   Backup File Space	Space that is pinned on disk for files being backed up. These are blocks that have been freed but cannot be used for new files until the backup is complete.
   Bitmap Size	Size of the bitmap file in kilobytes, including indirect blocks.
   Compress Progress	Indicates whether the compress operation is running or stopped with the percentage completion. If the compress operation is running, it also shows the time of the day when the long-running compress command was started and its task ID.
   Connected Clients	All client systems in the sysplex that have local mounts for a file system that is mounted RWSHARE.
   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 is n/a. If the aggregate has the CONVERTTOV5 attribute assigned to it, the second value indicates 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.
   Decompress Progress	Indicates whether the decompress operation is running or stopped with the percentage completion. If the decompress operation is running, it also shows the time of the day when the long-running decompress command was started and its task ID.
   Devno	The z/OS UNIX device number for the mounted file system.
   Decrypt Progress	Indicates whether the decrypt operation is running or stopped with the percentage completion. If the decrypt operation is running, it also shows the time of the day when the long-running decrypt command was started and its task ID.
   Encrypt Progress	Indicates whether the encrypt operation is running or stopped with the percentage completion. If the encrypt operation is running, it also shows the time of the day when the long-running encrypt command was started and its task ID.
   Encrypt-Scrubbing Progress	Indicates whether the scrubbing phases (clearing of unused disk space) is running or stopped with the percentage completion. If the encrypt operation is running, it also shows the time of the day when the long-running encrypt command was started and its task ID.
   File System Creation Time	Time that the file system was last formatted.
   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.
   File System Objects	The number of objects in the file system. The number includes files, directories, symbolic links, ACLs, and z/OS UNIX special files.
   Free 8K Blocks	Number of free 8 K blocks.
   Free 1K Fragments	Number of free fragments in partially allocated blocks.
   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.
   Log File Size	Total space in kilobytes occupied by the log file, including indirect blocks.
   Overflow HighWater	The highest number of overflow pages that were ever allocated on disk in extended (v5) directories.
   Overflow Pages	The number of overflow pages that are allocated to extended (v5) directories.
   Owner	The name of the system that currently owns the aggregate.
   Quiesce ASID	ASID of the job that quiesced the aggregate.
   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 Time	The time that the file system was last quiesced. For critical I/O operations, zFS sends I/O operations in parallel, up to the maximum number that the parallel access volume (PAV) device can handle concurrently.
   Revocation Wait Time	The average time that it took to revoke tokens from clients.
   Salvage Progress	Indicates that a salvage operation is running. It also shows the time of the day when the long-running salvage operation was started, its task ID, and which step of the salvage process is currently being performed.
   Shrink Progress	Indicates that a shrink operation is running. It also shows the time of the day when the long-running shrink operation was started, its task ID, and which step of the shrink process is currently being performed.
   Size	Size of the aggregate in kilobytes.
   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.
   Statistics Reset Time	Time that the owner statistics were last reset.
   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.
   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.
   Thrashing Objects	The current number of sysplex thrashing objects in the file system at one time.
   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.
   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.
   Version	The version of the aggregate. For example, 1.4 or 1.5.

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.

11. When you use the -owner option, the displayed file system status will indicate whether a long-running administrative operation is running on the aggregate. The statistics and legend sections will display status information about the current progress of the long operation. Also, you will see percentage complete indicators for certain steps of the long operation that are expected to occupy the bulk of the time in the operation. For more information about the overall processing of the long option, refer to the appropriate zfsadm command.

Privilege required

To use the -reset option, the issuer must be a root user (UID=0) or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS® UNIXPRIV class.Otherwise, the issuer does not need special authorization.

Related information