lustre/tests/mpi/write_append_truncate.1

   1 .\" Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
   2 .\" Use is subject to license terms.
   3 .\"
   4 .\" Author: Andreas Dilger <adilger@sun.com>
   5 .TH write_append_truncate 1 "Oct 29, 2008" Lustre "utilities"
   6 .SH NAME
   7 write_append_truncate \- MPI test of concurrent file operation coherency
   8 .SH SYNOPSIS
   9 .B write_append_truncate
  10 .RB [ -a
  11 .IR append_max ]
  12 .RB [ -C ]
  13 .RB [ -n
  14 .IR nloops ]
  15 .RB [ -s
  16 .IR seed ]
  17 .RB [ -t
  18 .IR trunc_max ]
  19 .RB [ -T ]
  20 .RB [ -w
  21 .IR write_max ]
  22 .RB [ -W ]
  23 .I filename
  24 .I ...
  25 .SH DESCRIPTION
  26 The
  27 .B write_append_truncate
  28 program does data coherency testing for parallel filesystem using
  29 .BR mpi (7)
  30 to launch and co-ordinate processes.  It runs multiple parallel
  31 processes on one or more nodes, as specified to
  32 .BR mpirun (1),
  33 .BR pdsh (1),
  34 or other MPI job launcher, each operating on the same shared file.
  35 .sp
  36 The master process creates
  37 .I filename
  38 if it does not exist
  39 .I
  40 For each of the
  41 .I num_loops
  42 test iterations one process truncates the file to zero size and writes
  43 a random number of check bytes,
  44 .BR W
  45 between 1 and
  46 .I write_max
  47 to
  48 .IR filename .
  49 .sp
  50 Other processes wait on an MPI barrier until
  51 this is complete.  One of the processes is chosen, to do an append
  52 .RB ( write (2)
  53 with
  54 .BR O_APPEND ) of
  55 a random size,
  56 .BR A ,
  57 between 1 and
  58 .I append_max
  59 bytes to the end of the file.  A second process does a concurrent
  60 .BR truncate (2)
  61 operation on the file to a random size,
  62 .BR W + T ,
  63 between 1 and
  64 .I trunc_max
  65 bytes beyond the end of the initial
  66 .B W
  67 bytes data.  This truncate will either extend the file size if it is
  68 done before the append, or it will truncate the file if it is done
  69 after the append.
  70 .sp
  71 A second MPI barrier ensures both of the processes have completed
  72 their respective operations, and then the master process reads the entire
  73 file and verifies the contents.
  74 .sp
  75 The beginning of the file is verified to contain the
  76 .B W
  77 check bytes up to the offset it was initially filled to.
  78 .br
  79 If the file size is equal to the truncated size,
  80 .BR W + T ,
  81 then the truncate operation was done
  82 .I after
  83 the append and the data beyond the initial write offset
  84 .BR W
  85 to the end of file
  86 .BR W + T
  87 should contain the
  88 .B A
  89 bytes of append check data, and possibly a zero-filled hole at the
  90 end of the file if
  91 .B T
  92 is larger than
  93 .BR A .
  94 .sp
  95 Otherwise, the truncate operation was done
  96 .I before
  97 the append and the data beyond the initial write offset
  98 .B W
  99 to the truncate offset
 100 .BR W + T
 101 should be a zero-filled hole.  Beyond the hole to the end of file
 102 there should be
 103 .B A
 104 bytes of append check data.  The total file size should be
 105 .BR W " + " T " + " A .
 106 .LP
 107 .SH SEE ALSO
 108 .BR mpirun (1)
 109 .BR pdsh (1)