MIO_close Subroutine

Purpose

Close a file descriptor through the MIO library.

Library

Modular I/O library (libmio.a)

Syntax

#include <libmio.h>

int MIO_close (FileDescriptor)

int FileDescriptor;

Description

This subroutine is an entry point of the MIO library. Use this subroutine to instrument your application with the MIO library. You can replace the close kernel I/O subroutine with this equivalent MIO subroutine. See the Modular I/O in AIX® Version 7.1 Performance management for the MIO library implementation.

Use this subroutine to close a file with the FileDescriptor parameter through the Modular I/O (MIO) library. The FileDescriptor parameter results from the MIO_open64 subroutine.

Parameters

The parameters are those of the corresponding standard POSIX system call close.

Return Values

The return values are those of the corresponding standard POSIX system call close.

Error Codes

The error codes are those of the corresponding standard POSIX system call close.

Standard Output

MIO library outputs are flushed on the MIO_close subroutine call in the stats file.

The following is the information found in the diagnostic output file. It contains debug information:

If you set the stats option of the trace module (trace/stats), it runs diagnostics from the trace module.
If you set the stats option of the pf module (pf/stats), it runs diagnostics from the pf module.
If you set the stats option of the recov module (recov/stats), it runs diagnostics from the recovery trace.
If you set the nostats option of the trace or the pf module, these diagnostics are suppressed.

The diagnostic file name is defined in the MIO_STATS environment variable if the stats option is set to the default value of mioout.

To separate the trace, pf or recov module diagnostics from other outputs, set the stats options to the following other file names:

trace/stats=<tracefile>
pf/stats=<pffile>
recov/stats=<recovfile>

The tracefile, pffile and recovfile are templates for the file names of module diagnostics output. You can give file names for the output of the trace, pf or recov module diagnostics.

Standard output includes the following information:

Header, which contains the following information:

Date
Hostname
Enabled or disabled AIO
Program name
MIO library version
Environment variables

Debug, which contains the following information:

The list of all the debug options
The table of all of the modules' definitions if the DEF debug option is set
Open request made to the MIO_open64 subroutine if the OPEN debug option is set
The modules invoked if the MODULES debug option is set

Trace module diagnostic, which contains the following information:

Time if the TIMESTAMP debug option is set
Trace on close or on intermediate interrupt
Trace module position in module_list
Processed file name
Rate, which is the amount of data divided by the total time. The total time here means the cumulative amount of time spent beneath the trace module
Demand rate, which is the amount of data divided by the length of time when the file is opened (including the time of opening and closing the file)
The current (when tracing) file size and the maximum size of the file during this file processing
File system information: file type and sector size
Open mode and flags of the file
For each subroutine, the following information is displayed:
name of the subroutine
count of calling of this subroutine
time of processing for this subroutine
For read or write subroutines, the following information is displayed:
requested (requested size to read or write) total (real size read or write: returned by AIX(r) system call) min (minimum size to read or write) max (maximum size to read or write)
For the seek subroutine, the following information is displayed:
the average seek delta (total seek delta/seek count)
For the aread or awrite subroutine:
count, time and rate of transfer time including suspend, and read or write time
For the fcntl subroutine, the number of pages is returned.

The following is an example of a trace diagnostic:

date

Trace oncloseor intermediate: 
previous module or calling program<->next module:file name:
(total transferred bytes/total time)=rate
  demand rate=rate/s=total transferred bytes/(close time-open time)
  current size=actual size of the filemax_size=max size of the file
mode=file open mode
FileSystemType=file system type given by fststat(stat_b.f_vfstype)
sector size=Minimum direct i/o transfer size
oflags=file open flags
open    open count     open time
fcntl   fcntl count    fcntl time
read    read count     read time  requested size    total size   minimum    maximum 
aread   aread count    aread time requested size    total size   minimum    maximum
suspend count time rate
write   write count    write time  requested size   total size   minimum    maximum
seek    seek count     seek time   average seek delta
size
page    fcntl page_info count

The following is a sample of a trace diagnostic:

MIO statistics file : Tue May 10 14:14:08 2005 
hostname=host1  : with Legacy aio available 
Program=example 
MIO library libmio.a 3.0.0.60  AIX(r) 5.1 32 bit addressing built 
Apr 19 2005 15:08:17 
MIO_INSTALL_PATH= 
MIO_STATS       =example.stats 
MIO_DEBUG       =OPEN 
MIO_FILES       = *.dat [ trace/stats ] 
MIO_DEFAULTS    = trace/kbytes  

MIO_DEBUG OPEN =T  

Opening file file.dat
    modules[11]=trace/stats 
============================================================================  
Trace close : program <-> aix : file.dat : (4800/0.04)=111538.02 kbytes/s
      demand rate=42280.91 kbytes/s=4800/(0.12-0.01))
      current size=0   max_size=1600
   mode =0640  FileSystemType=JFS sector size=4096
   oflags =0x302=RDWR  CREAT  TRUNC
   open              1     0.00
   write           100     0.02      1600     1600     16384     16384
   read            200     0.02      3200     3200     16384     16384
   seek            101     0.01 average seek delta=-48503
   fcntl             1     0.00
   trunc             1     0.01
   close             1     0.00
   size            100 
============================================================================

The following is a template of the pf module diagnostic:

pf close for<name of the file in the cache>
pf close for global or private cache <global cache number>
<nb_pg_compute>page of<page-size> <sector_size> bytes per sector
<nb_real_pg_not_pf>/<nb_pg_not_pf> pages not preread for write
<nb_unused_pf>unused prefetches out of<nb_start_pf>
prefetch=<nb_pg_to_pf>
<number> of write behind
<number> of page syncs forced by ill formed writes
<number> of pages retained over close
<unit> transferred / Number of requests
program --> <bytes written into the cache by parent>/
<number of write from parent>--> pf -->
<written out of the cache from the child>/<number of partial page written>
program --> <bytes read out of the cache by parent>/
<number of read from parent><– pf <–
<bytes read in from child of the cache>/<number of page read from child>

The following is explanation of the terms in the pf module template:

nb_pg_compute= number of page compute by cache_size/ page size
nb_real_pg_not_pf= real number page not prefetch because of pffw option (suppress number of page prefetch because sector not valid)
nb_pg_not_pf= page of unused prefetch
nb_unused_pf= number of started prefetch
nb_pg_to_pf= number of page to prefetch

The following is a sample of the pf module diagnostic:

pf close for /home/user1/pthread/258/SM20182_0.SCR300
50 pages of 2097152 bytes 131072 bytes per sector
133/133 pages not preread for write
23 unused prefetches out of 242 : prefetch=2
95 write behinds
mbytes transferred / Number of requests
program --> 257/257 --> pf --> 257/131 --> aix
program <-- 269/269 <-- pf <-- 265/133 <-- aix

The following is the recov module output:

If open or write routine failed, the recov module, if set, is called. The recov module adds the following comments in the output file:

The value of the open_command option
The value of the command option
The errno
The index of retry

The following is a sample of the recov module:

15:30:00
   recov : command=ls -l file=file.dat errno=28 try=0
   recov : failure : new_ret=-1

Location

/usr/lib/libmio.a