List File Information
Purpose
Lists detailed file or directory information. This API is an w_pioctl (BPX1PIO) call specifying a path name rather than a pfsctl (BPX1PCT) call specifying a file system name.
Format
PX1PIO parameter list
Pathname_length int
Pathname char[1025]
Command int 0x0000A901
Argument_length int sizeof(FOBJ_INFO)
Argument ptr to FOBJ_INFO
Return_value ptr to int 0
Return_code ptr to int 0
Reason_code ptr to int 0
FOBJ_TIME
fo_seconds hyper Second since last epoch
fo_mircoseconds int Micro seconds since last epoch
fo_unused int Reserved
FOBJ_ACLINFO
fo_index int Location of ACL
fo_length int Length of ACL
FOBJ_AUDIT
fo_read char Read information
fo_write char Write information
fo_exec char Exec information
fo_res1 char 1 - No auditing
2 - Success auditing
3 - Failure auditing
FOBJ_SYSINFO
fo_vnode hyper Address of zFS vnode
fo_vntok hyper Address of z/OS UNIX vnode
fo_openwaiters unsigned int Number of tasks waiting to open a
file blocked by deny-mode opens
fo_internalopens unsigned int Number of internal opens
fo_readopens unsigned int Number of opens for read
fo_writeopens unsigned int Number of opens for write
fo_denyreads unsigned short Number of deny-read opens
fo_denywrites unsigned short Number of deny-write opens
fo_advdenyreads unsigned short Number of advisory deny-read opens
fo_advdenywrites unsigned short Number of advisory deny-write opens
fo_sysflags char Miscellaneous information:
0x01 - file being read sequentially
0x02 - file written sequentially
0x04 - security information cached
0x08 - file location information
cached
0x10 - symlink information cached
0x20 - metadata updates sent to
server, can not directly
read without a server sync
0x40 - tokens are being revoked
0x80 - file is undergoing thrashing
fo_sysflags2 char More miscellaneous information
0x01 - file system owned locally
fo_unused char[2] Reserved
fo_unscheduled int Number of 4K pages in user file
cache that need to be written
fo_pending int Number of 4K pages being written
fo_segments int Number of 64K segments in user cache
fo_dirtysegment int Number of segments with pages that
need to be written
fo_metaissued int Number of I/Os in progress that will
require a metadata update
fo_metapending int Number of queued metadata updates
fo_rights int Token rights held by object
fo_xmits short Number of XCF messages client has
sent server for this object
fo_fwd short Number of in-progress operations
for object using thrashing protocol
fo_metabuffers int Number of buffers in metadata cache
for this object, only client systems
fo_dirtybuffers int Number of metadata buffers updated
for object that are on server and
need writing
fo_owner char[9] Name of owning system
fo_localsys char[9] Name of local system
fo_pad char[2] Reserved
fo_sysres int[9] Reserved
FOBJ_INFO
fo_eye char[4] "FOIN"
fo_len short Size of(FOBJ_INFO)
fo_ver char 1
2 for returning information
introduced in z/OS V2R3
fo_inflags char 1- Only in-memory system information
is being requested.
fo_inode int Object inode
fo_unique int Object uniquifier
fo_length hyper POSIX length of object (in bytes)
fo_mtime FOBJ_TIME Last modification time
fo_atime FOBJ_TIME Last access time
fo_ctime FOBJ_TIME Last change time
fo_reftime FOBJ_TIME Last reference time
fo_create FOBJ_TIME Create time
fo_allocation char How object stored on disk:
1 - Object is stored inline
2 - Object is stored fragmented
3 - Object is stored blocked
fo_owner_perms char Permissions for owner of file:
0x01 - Execute permission
0x02 - Write permission
0x04 - Read permission
fo_group_perms char Permissions for the group:access
to the file:
0x01 - Execute permission
0x02 - Write permission
0x04 - Read permission
fo_other_perms char Permissions of other users of file:
0x01 - Execute permission
0x02 - Write permission
0x04 - Read permission
fo_allocated unsigned int Number of allocated bytes
fo_locinfo union Location of object's data
fo_direct unsigned int[8] Location of first 8 logical blocks
fo_indirect unsigned int[4] Location of indirect tree roots
-- or --
fo_block unsigned int Block with object's data
fo_start unsigned short Starting fragment in block
fo_len unsigned short Number of fragments
fo_uid int UID of owner
fo_gid int GID of owner
fo_access FOBJ_ACLINFO Access acl
fo_dmodel FOBJ_ACLINFO Directory model acl
fo_fmodel FOBJ_ACLINFO File model acl
fo_user FOBJ_AUDIT User audit information
fo_auditor FOBJ_AUDIT Auditor audit information
fo_permbits char Sticky bit and other bits:
0x01 - setgid
0x02 - setuid
0x04 - Sticky bit on
<some bits> int Miscellaneous bits in an integer
fo_txtflag bit 0 Context are pure text
fo_deferflag bit 1 Defer tag set until first write
fo_filefmt bits 2-7 File format attribute:
0=NA
1=BIN
2=NL
3=CR
4=LF
5=CRLF
6=LFCR
7=CRNL
8=REC
bits 8-31 Reserved
fo_ccsid unsigned short Hex CCSID
fo_seclabel char[8] Seclabel of object
fo_entrycount unsigned int If object a directory, the number
of names it contains.
fo_linkcount unsigned int POSIX linkcount for object
fo_dataversion unsigned int Data version for directory updates
fo_genvalue unsigned int USS attribute flags of object
fo_cver char[8] Creation verifier
fo_majorminor char[8] If object a character special file,
major/minor number.
fo_type char Object type:
0x01 - directory
0x02 - regular file
0x03 - symlink
0x04 - FIFO
0x05 - character special file
fo_flags char Additional object flags:
0x01 - object is a v5 directory
0x02 - v5 directory tree structure
is broken
0x04 - automatic conversion to v5
failed
0x08 - contents are logged
fo_offset short Offset of anode
fo_anodeblock unsigned int Physical block that contains anode
fo_status_level char Directory status byte
0x80 - directory is v5
0x1F - max depth of v5 tree
fo_res char[3] Reserved
fo_res3 int[3] Reserved
fo_CEprogress unsigned_int Next block to process for a blocked file
that is undergoing encryption or decryption.
fo_compBlocks unsigned_int Number of 8k blocks that were saved based on
compression of file data.
fo_CEFlag char Encryption and compression indicator flags:
0x03 Encryption bits in fo_CEFlag
0x00 Not-encrypted
0x01 Decrypting
0x02 Encrypting
0x03 Encrypted
0x0C Compression bits in fo_CEFlag
0x00 Not-compressed
0x04 Decompressing
0x08 Compressing
0x0C Compressed
fo_res4 char[3] Reserved
fo_res5 int[8] Reserved
fo_info FOBJ_SYSINFO System based transient information
Return_value 0 if request is successful, -1 if it is not successful
Return_code
EBUSY Aggregate containing file system is quiesced
EINTR ZFS is shutting down
EINVAL Invalid parameter list
EMVSERR Internal error using an osi service
ENOENT No such file or directory exists
Reason_code
0xEFnnxxxx See z/OS Distributed File Service Messages and CodesUsage notes
Privilege required
The issuer must have lookup authority (x) to the directory and READ authority
(r) to the file.
Related services
- List Aggregate Status (Version 2)
Restrictions
None.
Examples
#pragma linkage(BPX1GCW, OS)
#pragma linkage(BPX1PIO, OS)
#pragma LANGLVL(EXTENDED)
extern void BPX1GCW(int, char *, int *, int *, int *);
extern void BPX1PIO(int, char *, int, int, void *, int *, int *, int *);
#include <stdio.h>
#include <time.h>
#define ZFSIOCTL_FILEINFO 0x0000A901 /* zFS ioctl command to */
/* return detailed fileinfo */
/* for a zFS file or directory */
#define hiszero(a) ((a).low == 0 && (a).high == 0)
#define hcmp(a,b) ((a).high<(b).high? -1 : ((a).high > (b).high? 1 : \
((a).low <(b).low? -1 : ((a).low > (b).low? 1 : 0))))
#define u_int unsigned int
#define uint16_t unsigned short
typedef struct hyper { /* This is a 64 bit integer to zFS */
unsigned int high;
unsigned int low;
} hyper;
/*****************************************************************************/
/* The FOBJ_INFO structure is used to contain the output of the fileinfo */
/* ioctl query to provide detailed information for a singular object in a */
/* zFS file system. */
/*****************************************************************************/
typedef struct FOBJ_ACLINFO_t {
int fo_index; /* Index into the anode table of */
/* the location of the ACL */
int fo_length; /* Length of the ACL */
} FOBJ_ACLINFO;
typedef struct FOBJ_AUDIT_t {
char fo_read; /* read auditing information */
char fo_write; /* write auditing information */
char fo_exec; /* exec auditing information */
char fo_res1;
#define FO_NONE 0 /* no auditing */
#define FO_SUCC 1 /* success auditing */
#define FO_FAIL 2 /* fail auditing */
} FOBJ_AUDIT;
typedef struct FOBJ_TIME_t {
hyper fo_seconds; /* number of seconds since epoch */
int fo_microseconds; /* number of microseconds since epoch*/
int fo_tres1; /* unused */
} FOBJ_TIME;
typedef struct FOBJ_SYSINFO_t { /* HEX displacement into FOBJ_INFO */
hyper fo_vnode; /* 138 - Address of vnode in zFS
kernel memory */
hyper fo_vntok; /* 140 - Address of USS vnode in
z/OS Unix address space */
unsigned int fo_openwaiters; /* 148 - Number of tasks waiting to open
file because blocked
by current deny-mode opens */
unsigned int fo_internalopens; /* 14C - Number of internal
opens on the file */
unsigned int fo_readopens; /* 150 - Number of opens for
read on the file */
unsigned int fo_writeopens; /* 154 - Number of write opens */
unsigned short fo_denyreads; /* 158 - Number of deny-read opens */
unsigned short fo_denywrites; /* 15A - Number of deny-write opens */
unsigned short fo_advdenyreads; /* 15C - Number of adv. deny read opens */
unsigned short fo_advdenywrites;/* 15E - Number of adv. deny write opens */
char fo_sysflags; /* 160 - Misc. information */
#define FO_SEQREAD 1 /* Object is a file that zFS determined
is being read sequentially */
#define FO_SEQWRITE 2 /* Object is a file that zFS is
being written sequentially */
#define FO_FSPVALID 4 /* System has security information
cached for anode */
#define FO_ANODEVALID 8 /* System has posix attribute and
disk location information cached */
#define FO_SYMLINKVALID 16 /* System has the symbolic link contents
cached for the object */
#define FO_METAUPDATES 32 /* Client has sent metadata updates to the
server, and cannot directly read without
a server sync */
#define FO_REVOKE 64 /* Revoke in progress */
#define FO_THRASH 128 /* Object is considered sysplex-thrashing
and thrash resolution is in
effect for file */
char fo_sysflags2; /* 161 - Misc. information 2 */
#define FO_OWNER 1 /* This system is the owner of
the file system */
#define FO_BACKUP 2 /* There is an incremental backup in */
/* progress on this system for this file */
char fo_unused[2]; /* 162 - reserved */
int fo_unscheduled; /* 164 - Number of dirty 4K pages in the
user file cache that have not yet been
written to disk */
int fo_pending; /* 168 - Number of pending 4K pages
in transit to disk */
int fo_segments; /* 16C - Number of 64K segment structures
in the user file cache for the file */
int fo_dirtysegments; /* 170 - Number of 64K segment structures
that have dirty pages in the
user file cache */
int fo_metaissued; /* 174 - Number of in-progress IOs to disk
that will require a metadata
update to reflect new data in the file*/
int fo_metapending; /* 178 - Number of queued metadata updates
for file, for IOs completed to new data
for the file */
int fo_rights; /* 17C - Token rights held for object */
short fo_xmits; /* 180 - Number of in-progress
transmissions from client to
server for this file */
short fo_fwd; /* 182 - Number of in-progress forwarded
operations due to thrashing object */
int fo_metabuffers; /* 184 - Number of buffers for file in the
metadata cache - client only */
int fo_dirtybuffers; /* 188 - Number of dirty metadata buffers
in the metadata cache for
object - server only */
char fo_owner[9]; /* 18C - the name of the owner */
char fo_localsys[9]; /* 195 - the name of the local system */
char fo_pad; /* 19E - pad */
char fo_backpct; /* 19F - The percentage complete of an */
/* incremental backup, if one is in */
/* progress, else 0 */
#define FO_SYSRES_NUM 9
int fo_sysres[FO_SYSRES_NUM]; /* 1A0 - Reserved for future use */
} FOBJ_SYSINFO;
typedef struct fobj_info_t { /* HEX displacement into FOBJ_INFO */
char fo_eye[4]; /* 000 - Eye catcher */
#define FO_EYE "FOIN"
short fo_len; /* 004 - Length of this structure */
char fo_ver; /* 006 - Version */
#define FO_VER_INITIAL 1 /* Initial version */
char fo_inflags; /* 007 - Input flag bits indicating
requested function */
#define FO_SYSINFO_ONLY 1 /* Only the in-memory system information
is being requested */
int fo_inode; /* 008 - Inode of the object */
int fo_unique; /* 00C - Uniquifier of the object */
hyper fo_length; /* 010 - Posix length of object in bytes */
FOBJ_TIME fo_mtime; /* 018 - Modification time */
FOBJ_TIME fo_atime; /* 028 - access time */
FOBJ_TIME fo_ctime; /* 038 - change time */
FOBJ_TIME fo_reftime; /* 048 - referenct time */
FOBJ_TIME fo_create; /* 058 - creation time of object */
char fo_allocation; /* 068 - How the object is stored on disk */
#define FO_INLINE 1 /* Object is stored inline */
#define FO_FRAGMENTED 2 /* Object is stored fragmented */
#define FO_BLOCKED 3 /* Object is stored in the blocked
method, or is empty */
char fo_owner_perms; /* 069 - Permissions for the owner
of this file */
#define FO_READ 4 /* has read permission */
#define FO_WRITE 2 /* has write permission */
#define FO_EXEC 1 /* has execute permission */
char fo_group_perms; /* 06A -Permissions for the group
associated with this file */
char fo_other_perms; /* 06B - Permissions for other.. */
unsigned int fo_allocated; /* 06C - Number of allocated bytes to
object, including internal control
structures, in kilobyte units */
union
{
struct {
unsigned int fo_direct[8]; /* 070 - Physical location of first 8
logical blocks of object */
unsigned int fo_indirect[4]; /* 090 - Physical location of indirect
tree roots, trees 0 - 3 */
#define FO_UNALLOCATED 0xFFFFFFFF /* This value means block is not
allocated in fo_direct or
fo_indirect slot */
} fo_blockinfo;
struct {
unsigned int fo_block; /* 070 - Block that contains the
object data */
unsigned short fo_start; /* 074 - Start fragment in the block */
unsigned short fo_len; /* 076 - Number of fragments
in the block */
} fo_fraginfo;
} fo_locinfo; /* Location of objects data */
int fo_uid; /* 0A0 - UID of the owner of object */
int fo_gid; /* 0A4 - group id of owner of object */
FOBJ_ACLINFO fo_access; /* 0A8 - ACL information for access
acl of object */
FOBJ_ACLINFO fo_dmodel; /* 0B0 - ACL information for directory
model acl */
FOBJ_ACLINFO fo_fmodel; /* 0B8 - ACL information for file
model acl */
FOBJ_AUDIT fo_user; /* 0C0 - User auditing information */
FOBJ_AUDIT fo_auditor; /* 0C4 - Auditor auditing information*/
char fo_permbits; /* 0C8 - Sticky and other bits */
#define FO_ISVTX 4 /* sticky bit on */
#define FO_ISUID 2 /* setuid */
#define FO_ISGID 1 /* setgid */
int fo_txtflag : 1; /* 0C9 - contents are pure
text indicator */
int fo_defertag : 1; /* 0C9 - Defer tag set until
first write */
int fo_filefmt : 6; /* 0C9 - File format attribute */
/* 0=NA 1=BIN 2=NL 3=CR 4= LF */
/* 5=CRLF 6=LFCR 7=CRNL 8=REC */
short fo_ccsid; /* 0CA - hex ccsid */
char fo_seclabel[8]; /* 0CC - seclabel of the object */
unsigned int fo_entrycount; /* 0D4 - Number of names in the
directory, if this is a directory */
unsigned int fo_linkcount; /* 0D8 - Posix linkcount for object */
unsigned int fo_dataversion; /* 0DC - Data version for
directory updates */
unsigned int fo_genvalue; /* 0E0 - USS attribute flags
of object */
char fo_cver[8]; /* 0E4 - Creation verifier */
char fo_majorminor[8]; /* 0EC - Major/minor number if object
is a char special file */
char fo_type; /* 0F4 - Object type */
#define FO_DIR 1 /* object is directory */
#define FO_FILE 2 /* object is a regular file */
#define FO_LINK 3 /* object is a symlink */
#define FO_FIFO 4 /* object is a fifo */
#define FO_CHARSPEC 5 /* object is a char special file */
char fo_flags; /* 0F5 - Additional flag bits of
object */
#define FO_VER5 1 /* Object is a directory stored in
new-fast format */
#define FO_BROKEN 2 /* The tree structure of this new-fast
format dir is broken */
#define FO_CONVERT_FAIL 4 /* Automatic conversion of the
directory failed */
short fo_offset; /* 0F6 - Offset into the physical block
that contains the anode for object*/
unsigned int fo_anodeblock; /* 0F8 - Physical block in aggregate
that contains the anode */
char fo_statuslevel; /* 0FC - directory status byte */
char fo_res[3]; /* 0FD - reserved */
int fo_res3[3]; /* 100 - For future use */
unsigned int fo_CEprogress; /* 10C - Next logical block to process
for encrypt/decrypt/compress/
decompress */
unsigned int fo_compBlocks; /* 110 - Number of 8K blocks saved
based on compressions of file data*/
char fo_CEFlag; /* 114 - Encrypt/compress indicator flags */
#define FOBJ_ENC_BITS 0x03
#define FOBJ_NOT_ENC 0x00
#define FOBJ_DECRYPTING 0x01
#define FOBJ_ENCRYPTING 0x02
#define FOBJ_ENCRYPTED 0x03
#define FOBJ_COMP_BITS 0x0C
#define FOBJ_NOT_COMP 0x00
#define FOBJ_DECOMPRESSING 0x04
#define FOBJ_COMPRESSING 0x08
#define FOBJ_COMPRESSED 0x0C
char fo_res4[3]; /* 115 - For future use */
int fo_res5[8]; /* 118 - For future use */
FOBJ_SYSINFO fo_info; /* 138 - System based transient
information */
} FOBJ_INFO; /* 1C4 total length */
int main(int argc, char **argv)
{
int bpxrv;
int bpxrc;
int bpxrs;
char parm_pathname[1024];
char pathname[1024];
char *pathp = NULL;
FOBJ_INFO fobj;
FOBJ_INFO *fo = &fobj;
void *arg = (void *)fo;
int arglen = sizeof(fobj);
char buffer1[80];
char buffer2[80];
hyper bogusSignedTime;
char *p;
char *timep;
char time1_string[30];
char time2_string[30];
char seclabel[9];
char temp;
if (argc < 2)
{
printf("Please specify a file or directory path name as a parameter\n");
exit(1);
}
strncpy(parm_pathname, argv[1], sizeof(pathname));
if (parm_pathname[0] == '/') /* if absolute pathname */
pathp = parm_pathname; /* put ptr to pathname in pathp */
else
{ /* if relative pathname */
pathname[0] = 0;
bpxrc = 0;
bpxrv = 0;
bpxrs = 0;
/* get current working directory path */
BPX1GCW(sizeof(pathname), pathname, &bpxrv, &bpxrc, &bpxrs);
if (bpxrv == -1)
{
printf("BPX1GCW call failed rc %u rsn %8.8X\n", bpxrc, bpxrs);
return bpxrc;
}
if ((strlen(pathname) + strlen(parm_pathname) + 1) > sizeof(pathname))
{ /* if name longer than maximum pathname */
printf("directory path name too long - input name len "
"%d plus cwd len %d for buffer size %d\n",
strlen(parm_pathname), strlen(pathname), sizeof(pathname));
return 121; /* EINVAL */
}
/* take the current working directory and append slash */
strcat(pathname, "/");
/* then append the input relative path name */
strcat(pathname, parm_pathname);
/* put ptr to result in pathp */
pathp = pathname;
}
bpxrc = 0;
bpxrv = 0;
bpxrs = 0;
memset((char *)&fobj, 0x00, sizeof(fobj));
memcpy(&fobj.fo_eye, FO_EYE, 4);
fobj.fo_len = sizeof(fobj);
fobj.fo_ver = FO_VER_INITIAL;
BPX1PIO(strlen(pathp), pathp, ZFSIOCTL_FILEINFO,
arglen, arg, &bpxrv, &bpxrc, &bpxrs);
if (bpxrv < 0)
{
printf("Error getting fileinfo for pathname %s\n", pathp);
printf("BPXRV = %d BPXRC = %d BPXRS = %x\n", bpxrv, bpxrc, bpxrs);
return bpxrc;
}
else
{ /* Return from fileinfo was successful */
printf(" Object path: %s\n", pathp);
printf(" Inode is %lu\n", fo->fo_inode);
printf(" Length is %llu\n", fo->fo_length);
/* Some common object information */
printf(" Object type is %s\n",
fo->fo_type == FO_DIR ? "DIR" :
fo->fo_type == FO_FILE ? "FILE" :
fo->fo_type == FO_LINK ? "LINK" :
fo->fo_type == FO_CHARSPEC ? "CHARSPEC" : "??");
/* Some directory object information */
if (fo->fo_type == FO_DIR)
printf(" Directory version %u\n",
fo->fo_flags & FO_VER5 ? 5 : 4);
}
printf("\n");
return 0;
}