1FILE_IO(3)                        file_io 1.3                       FILE_IO(3)
2
3
4

NAME

6       nfstest.file_io - File I/O module
7

DESCRIPTION

9       Provides  an  interface  to  create  and  manipulate files of different
10       types.  The arguments allow running for a specified period of  time  as
11       well as running multiple processes. Each process modifies a single file
12       at a time and the file name space is  different  for  each  process  so
13       there  are  no collisions between two different processes modifying the
14       same file.
15
16       File types:
17         - Regular file
18         - Hard link
19         - Symbolic link
20
21       File operations:
22         - Open (create or re-open)
23         - Open downgrade
24           This is done by opening the file for read and write, then the  file
25       is
26           opened  again  as  read only and finally closing the read and write
27       file
28           descriptor
29         - Read (sequential or random access)
30         - Write (sequential or random access)
31         - Remove
32         - Rename
33         - Truncate (path or file descriptor)
34         - Readdir
35         - Lock
36         - Unlock
37         - Tlock
38

CLASSES

40   class FileIO(baseobj.BaseObj)
41       FileIO object
42
43       Usage:
44           from nfstest.file_io import FileIO
45
46           # Instantiate FileIO object given top level directory
47           x = FileIO(datadir="/tmp/data")
48
49           # Run workload creating the top level directory if necessary
50           x.run()
51
52
53       Methods defined here:
54       ---------------------
55
56       __del__(self)
57       Destructor
58
59       __init__(self, **kwargs)
60       Constructor
61
62       Initialize object's private data
63
64
65              datadir:
66                     Top level directory where files will be created,
67                     it will be created if it does not exist
68
69              seed:  Seed to initialized the random number generator
70                     [default: automatically generated]
71
72              nprocs:
73                     Number of processes to use [default: 1]
74
75              runtime:
76                     Run time [default: 0 (indefinitely)]
77
78              verbose:
79                     Verbose level: none|info|debug|dbg1-7|all [default: 'none']
80
81              exiterr:
82                     Exit on first error [default: False]
83
84              read:  Read file percentage [default: 40.0]
85
86              write: Write file percentage [default: 40.0]
87
88              rdwr:  Read/write file percentage [default: 20.0]
89
90              randio:
91                     Random file access percentage [default: 50.0]
92
93              iodelay:
94                     Seconds to delay I/O operations [default: 0.0]
95
96              direct:
97                     Use direct I/O [default: False]
98
99              rdwronly:
100                     Use read and write only, no rename, remove, etc. [default: False]
101
102              create:
103                     Create file percentage [default: 5.0]
104
105              odgrade:
106                     Open downgrade percentage [default: 5.0]
107
108              osync: Open file with O_SYNC [default: 10.0]
109
110              fsync: Percentage of fsync after write [default: 2.0]
111
112              rename:
113                     Rename file percentage [default: 5.0]
114
115              remove:
116                     Remove file percentage [default: 5.0]
117
118              trunc: Truncate file percentage [default: 2.0]
119
120              ftrunc:
121                     Truncate opened file percentage [default: 2.0]
122
123              link:  Create hard link percentage [default: 1.0]
124
125              slink: Create symbolic link percentage [default: 0.2]
126
127              readdir:
128                     List contents of directory percentage [default: 0.5]
129
130              lock:  Lock file percentage [default: 20.0]
131
132              unlock:
133                     Unlock file percentage [default: 80.0]
134
135              tlock: Lock test percentage [default: 20.0]
136
137              lockfull:
138                     Lock full file percentage [default: 50.0]
139
140              minfiles:
141                     Minimum number of files to create before any file operation
142                     is executed [default: 10]
143
144              fsizeavg:
145                     File size average [default: 1m]
146
147              fsizedev:
148                     File size standard deviation [default: 256k]
149
150              rsize: Read block size [default: 64k]
151
152              rsizedev:
153                     Read block size standard deviation [default: 8k]
154
155              wsize: Write block size [default: 64k]
156
157              wsizedev:
158                     Write block size standard deviation [default: 8k]
159
160              sizemult:
161                     Size multiplier [default: 1.0]
162
163              createlog:
164                     Create log file [default: False]
165
166              createlogs:
167                     Create a log file for each process [default: False]
168
169              logdir:
170                     Log directory [default: '/tmp']
171
172       get_mountpoint(self)
173       Get mount point from data directory
174
175       run(self)
176       Main function where all processes are started
177
178       run_process(self, tid=0)
179       Main loop for each process
180
181   class FileObj(baseobj.BaseObj)
182       Base class so objects will inherit the methods providing the string
183       representation of the object and a simple debug printing and logging
184       mechanism.
185
186       Usage:
187           from baseobj import BaseObj
188
189           # Named arguments
190           x = BaseObj(a=1, b=2)
191
192           # Dictionary argument
193           x = BaseObj({'a':1, 'b':2})
194
195           # Tuple arguments: first for keys and second for the values
196           x = BaseObj(['a', 'b'], [1, 2])
197
198           # All of the above will create an object having two attributes:
199           x.a = 1 and x.b = 2
200
201           # Add attribute name, this will be the only attribute to be displayed
202           x.set_attrlist("a")
203
204           # Add list of attribute names to be displayed in that order
205           x.set_attrlist(["a", "b"])
206
207           # Set attribute with ordered display rights
208           x.set_attr("a", 1)
209           # This is the same as
210           setattr(x, "a", 1) or x.a = 1
211           x.set_attrlist("a")
212
213           # Set attribute with switch duplicate
214           # The following creates an extra attribute "switch" with
215           # the same value as attribute "a":
216           #   x.a == x.switch
217           #   x.a is x.switch
218           x.set_attr("a", 1, switch=True)
219
220           # Make the current object flat by allowing all the attributes
221           # for the new attribute to be accessed directly by the current
222           # object so the following is True:
223           #   x.d == x.c.d
224           x.set_attr("c", BaseObj(d=11, e=22), switch=True)
225
226           # Set the comparison attribute so x == x.a is True
227           x.set_eqattr("a")
228
229           # Set verbose level of object's string representation
230           x.debug_repr(level)
231
232           # Set string format for verbose level 1
233           x.set_strfmt(1, "arg1:{0}")
234           # In the above example the first positional argument is "a"
235           # so the str(x) gives "arg1:1"
236
237           # Set attribute shared by all instances
238           # If a global or shared attribute is set on one instance,
239           # all other instances will have access to it:
240           #   y = BaseObj(d=2, e=3)
241           # then the following is true
242           #   x.g == y.g
243           #   x.g is y.g
244           x.set_global("g", 5)
245
246           # Set level mask to display all debug messages matching mask
247           x.debug_level(0xFF)
248
249           # Add a debug mapping for mask 0x100
250           x.debug_map(0x100, 'opts', "OPTS: ")
251
252           # Set global indentation to 4 spaces for dprint
253           x.dindent(4)
254
255           # Set global indentation to 4 spaces for displaying objects
256           x.sindent(4)
257
258           # Set global truncation to 64 for displaying string objects
259           x.strsize(64)
260
261           # Do not display timestamp for dprint messages
262           x.tstamp(enable=False)
263
264           # Change timestamp format to include the date
265           x.tstamp(fmt="{0:date:%Y-%m-%d %H:%M:%S.%q} ")
266
267           # Get timestamp if enabled, else return an empty string
268           out = x.timestamp()
269
270           # Open log file
271           x.open_log(logfile)
272
273           # Close log file
274           x.close_log()
275
276           # Write data to log file
277           x.write_log(data)
278
279           # Format the given arguments
280           out = x.format("{0:x} - {1}", 1, "hello")
281
282           # Format the object attributes set by set_attrlist()
283           out = x.format("{0:x} - {1}")
284
285           # Print debug message only if OPTS bitmap matches the current
286           # debug level mask
287           x.dprint("OPTS", "This is an OPTS debug message")
288
289
290   class TermSignal(builtins.Exception)
291       Exception to be raised on SIGTERM signal
292
293

FUNCTIONS

295       stop_handler(signum, frame)
296       Signal handler to catch SIGTERM and allow for graceful termination
297       of subprocesses
298

SEE ALSO

300       baseobj(3), formatstr(3)
301
302

BUGS

304       No known bugs.
305

AUTHOR

307       Jorge Mora (mora@netapp.com)
308
309
310
311NFStest 3.2                      21 March 2023                      FILE_IO(3)