Running the siolib Command-line Programs

Two command-line utilities have been provided with the SIO library for testing purposes. swrite will write data from a Unix file into a file stored in sio_fs and sread will copy data from sio_fs back to a normal Unix file. The sio_fs implementation in siolib uses the Cheops file manager, distributed separately with the NASD release.

swrite works by creating a symbolic link into which it encodes the location in Chops of the actual storage object. This symbolic link is useless to standard Unix programs; only programs that are linked against the sio library and call sio_open to open them can interpret what they point at.

swrite and sread both require that the Cheops file manager and at least one NASD drive be running. The documentation that comes with the NASD 1.0 release describes how to start a drive. The Cheops manager can be run in a mode where it stripes data across many drives. The siolib library and command-line programs are unaware of your drive configuration: you should just see increased bandwidth as you run against more drives.

Here is a summary of the steps needed to get to the point where you can run sread and swrite. We presume that $NASDROOT is set to the root directory of your NASD installation:

  1. Start as many drives as you want to stripe data across, as per the NASD programmer's documentation on running the drive. Typically, you might start a user-level drive under Linux with the command: # $NASDROOT/drive/pdrive -f /dev/sda This would start the drive, using the SCSI disk /dev/sda and formatting it first (the -f option to pdrive). Note that we are running the drive as root, since it needs to access the physical device /dev/sda, which typically is protected against casual use by non-priveleged users.
  2. Create a cheops.dtab file to tell the Cheops manager where the drives are. The format of the file is one entry per line. Each entry looks like: keyword id server port where keyword currently can only be drive, server and port specify the name and port of a NASD drive, and id is a unique number associated with each drive. For instance, if you are running two drives, one on rhoda and one on shirley, your cheops.dtab file might look like: drive 10 rhoda 06661
    drive 20 shirley 06661
    (port 6661 is the standard NASD port).
  3. Run the Cheops manager, while in the same directory as your cheops.dtab file you created in step 2. The Cheops manager lives in $NASDROOT/cheops/mgr/cheops_mgr. It requires at least one argument, the partition number to use on each drive. Make sure that you pick a partition number that is not being used for any other purpose on all of the drives listed in cheops.dtab. The Cheops manager will create the partition if it doesn't exist. For example: % $NASDROOT/cheops/mgr/cheops_mgr 3 starts the Cheops manager using the cheops.dtab file in the current working directory and using partition number 3 on all drives listed in it.
  4. Create a cheops.mtab file to tell the routines in siolib how to contact the Cheops manager. This file has a format identical to that of cheops.dtab, except that the only keyword currently allowed is manager. If, for instance, you are running the Cheops manager on a machine called cookie, your cheops.mtab file would look like: manager cookie 6663 (port 6663 is the standard Cheops manager port).

At this point, you are ready to run swrite and sread. They must be run in the same directory that the cheops.mtab file is in. Both programs take the same arguments:

        % swrite [-v] [-t] [-b blksz] source target
        % sread [-v] [-t] [-b blksz] source target
      
Option Description
-v Turn on verbose output; one dot per megabyte transfered is printed to show progress.
-t Show timing of run in megabytes per second.
-b blksz Set the number of bytes that are read from/written to the files in each request. The defaults are 64kB for swrite and 256kB for sread

swrite expects source to be the name of a Unix file. It reads its contents and writes them into NASD via the Cheops manager (which stripes the data across the drives as per its cheops.dtab file). The target argument to swrite is also the name of a "file" in Unix, but this file will actually be a symbolic link created by swrite, whose contents are specially interpreted by the code in siolib's sio_open primitive. For instance:

        % ./swrite /some/big/file siowrite.test
        Chunk size 65536
        ......................
        % ls -l siowrite.test
        lrwxrwxrwx   1 snl      pdl            38 Feb 17 18:37 siowrite.test -> cmu-sio sio-cheops-fs 0000000000000010
      
In this example, /some/big/file was written into NASD via siolib, and the symbolic link siowrite.test was created to "point" at the data in a way that sread can make sense of.

sread performs the inverse operation of copying data out of NASD and into a regular Unix file:

        % ./sread siowrite.test sioread.test
        % ls -l sioread.test
        -rw-r--r--   1 snl      pdl      23745787 Feb 17 18:40 sioread.test
        % ls -l /some/big/file
        -rw-------   1 snl      pdl      23745787 Dec 17 12:34 /some/big/file
        % cmp /some/big/file sioread.test
        %
      

While running swrite and sread, you will notice messages being printed by the Cheops manager. Error conditions are clearly noted by both the manager and by the swrite and sread programs. If you are unsure of the source of an error, siolib can be compiled with additional debugging messages turned on, as described in compiling siolib.


Last modified: Wed Feb 17 19:50:26 EST 1999