libsysio/tests/README

   1 To run the tests, just do a "make check" in the tests subdirectory.
   2 On the CPlant alpha systems, 3 of the 7 tests in test_all.pl are excluded
   3 due to known problems (problems as of the date of writing this; they
   4 may have since been fixed).  You can also manually run the individual
   5 tests or ./test_all.pl.  If you are running on CPlant, you need to
   6 run test_all.pl with a -alpha argument. Either "make check" or
   7 test_all.pl  will run the 7 basic functionality tests (explained
   8 below) and report the total number of passes and failures.
   9 number of passes and failures.
  10
  11 -----------------------SCRIPTS---------------------------------
  12
  13 There are a total of 8 scripts: test_copy.pl, test_list.pl,
  14 test_getcwd.pl, test_stats.pl, test_stdfd.pl, test_path.pl,
  15 populator.pl, and verifier.pl.  All but the last two scripts
  16 are ran with the test_all.pl script.  Here is an explanation
  17 of the scripts.  All scripts take an optional "-alpha" arg
  18 for running the scripts in an alpha/cplant environment.  The
  19 alpha arg makes certain assumptions about the running of the
  20 environment; for example, it does not initilization and it
  21 starts off the test driver with yod.
  22
  23 test_copy.pl <src> <dest> : This copies a file from src to dest.
  24                           : It runs a system cmp to verify that
  25                           : the two files are equivalent
  26
  27 test_list.pl [-p] <dir>               : This comes in two forms.
  28 test_list.pl [-p] <fstype:mdir> <dir> : In the first form, it will
  29                                       : parse through the getdirentries
  30                                       : result in order to generate a
  31                                       : a listing. If the -p option is
  32                                       : given, it will print out the
  33                                       : listing.  In the second form, it
  34                                       : mounts mdir into dir and then does
  35                                       : the listing
  36
  37 test_getcwd.pl <dir> : Tests getcwd by verifying that setting the current
  38                      : working directory to dir and then calling getcwd
  39                      : returns dir
  40
  41 test_stats.pl <file> : Verifies that the set of stat calls (stat, fstat,
  42                      : fstatvfs, statvfs) return the same set of stats for file
  43                      : and that the calls return the same items as Perl's stat
  44                      : call (which would use a native library and not libsysio)
  45
  46 test_stdfd.pl <file> : Verified that stdin, stdout, and stderr can be opened and
  47                      : either written to or read from
  48
  49 test_path.pl <path1> <path2> ... : Print each path listed and its type.
  50                                  : If no paths are given, paths are read
  51                                  : from stdin until a "quit" is given
  52
  53 populator.pl [-seed seed]     : Create a file and populate with random numbers.
  54              [-file filename] : Will use the given seed for the random number
  55              [-bytes bytes]   : generator if it is given, otherwise it uses the
  56                               : the current time as a seed.  The seed used is
  57                               : returned.  If no filename is given, the file
  58                               : will be named randfile.seed.procnum, where seed
  59                               : is the seed used and procnum is the process number
  60                               : of the script.  If no bytes are given, 1024 bytes
  61                               : are written.  All write commands use libsysio
  62
  63
  64 verifier.pl <-seed seed> <-file fname> : Verifies that all bytes in the file fname
  65                                        : (which was created with populator) match the
  66                                        : random numbers which would have been used with
  67                                        : the populator, using the given seed.
  68
  69
  70
  71 -----------------------------TEST DRIVER---------------------------------
  72
  73
  74 There are 6 basic commands for the test driver, CALL, PRINT,
  75 ALLOC, FREE, HELP, and exit (EXIT, quit, or QUIT will also work).
  76
  77 CALL is the main command for running libsysio calls.  The format
  78 will depend on the particular libsysio command being ran.
  79 Basically, the format is CALL cmd args.  The available commands
  80 used with CALL are (in no particular order):
  81
  82 fstat           iwrite          read            chdir
  83 fstatvfs        iwritev         readv           chmod
  84 fsync           list            rmdir           chown
  85 ftruncate       lseek           sizeof          close
  86 getcwd          lstat           stat            cmpstr
  87 getdirentries   mkdir           statvfs         creat
  88 init            mknod           symlink         debug
  89 ioctl           mount           truncate        dup
  90 iodone          open            umask           dup2
  91 iowait          umount          endian          ipread
  92 printline       unlink          ipreadv         pread
  93 write           fcntl           ipwrite         preadv
  94 writev          fdatasync       ipwritev        pwritev
  95 fill            iread           pwrite          ireadv
  96
  97 The specifics of the commands are explained later.
  98
  99 The return value from a command can be saved and referenced later
 100 by using a syntax similar to $foo = x.  Commands can be combined, such
 101 as:
 102
 103 CALL fstat ( $fd = CALL open foo ) ( $buf = ALLOC 128 ),
 104
 105 with some cautionary notes.  First, everything needs to be
 106 seperated by a space.  File names with spaces in them need to be quoted,
 107 as in:
 108
 109 $fd = CALL open "file with spaces" O_RDONLY
 110
 111 Second, any value that is used needs to be identified with an identifier.
 112 In other words, the command:
 113
 114 $buf = ALLOC ( CALL sizeof stat )
 115
 116 will not work, but the command
 117
 118 $buf = ALLOC ( $size = CALL sizeof stat )
 119
 120 will.
 121
 122
 123 All commands return a 4 digit status code.  The codes are:
 124
 125 0000  : Success.  This does NOT necessarily mean that the libsysio
 126       : command returned success, only that there were no errors
 127       : in issuing the command to libsysio.  To get the result of
 128       : the libsysio command, use PRINT $$ .  PRINT $errno will return
 129       : the last error code.
 130 0x001 : Invalid arguments given to command
 131 0x002 : Invalid command issued
 132 0x004 : Invalid variable identifier given
 133
 134
 135 ALLOC takes a size argument and an optional alignment argument.
 136 FREE takes the variable to free as an argument.
 137 HELP without any arguments displays the list of commands.
 138 HELP <cmd> will give information on the specific command
 139
 140 PRINT take several forms.  To just print out a variable, type
 141 PRINT $var-name.  If the variable is an integer, it will return
 142 the integer.  If it is a string, it will print out the string.
 143 If it is a buffer, it will print out the buffer as a series of
 144 hex digits.  Note for most buffers, the test driver will not
 145 know what it contains--just because it should contain a string
 146 does not mean that the driver will know that.
 147
 148 The other form of PRINT is:
 149
 150 PRINT $var_name <offset> <length> <type>
 151
 152 which will print out length units of the given type starting at
 153 the given offset.  The length is the total length in bytes, so
 154 for an integer, a length of 4 would only print out one integer.
 155 The length argument is ignored for strings.  Allowable types are
 156 INT SHORT CHAR and LONG.
 157
 158 For most of the CALL commands, their format is similar to the
 159 related sysio call.  The ones that do not have a corresponding
 160 sysio call are listed below:
 161
 162 init:  This MUST be called prior to any sysio calls.  It initilizes
 163     :  libsysio
 164
 165 printline: If debugging is turned on, this will print a line number
 166          : with any debug lines
 167
 168 fill <val> <type> <size> <offset> <buf>: Fills buffer buf with size
 169                                        : bytes of val starting at
 170                                        : buf+offset.  The type of val
 171                                        : can be UINT. STR, or PTR and
 172                                        : is given by the type arg
 173
 174 list <dir>: Lists contents of dir.  If no dir is given, uses cwd
 175
 176 debug <num>: Sets debug level to num
 177
 178 sizeof <obj>: Gives the size of the obj.  Valid objs are char, int,
 179             : long, flock, stat, and statvfs
 180
 181 endian: returns 0 if the machine is little endian, one otherwise
 182
 183 cmpstr <buf1> <buf2>: Issues a strcmp call on the two buffers to
 184                     : see if they are the same.  Returns 0 for a
 185                     : match