libfshelp-tests: Tests for file record locking

2019-03-04  Svante Signell <svante.signell@gmail.com>

        * test-*.c: Update code, remove test results.
        * README.new_tests: New file, summarize new test results.

2019-02-12  Svante Signell <svante.signell@gmail.com>

        * test-*.c: Update code, add some test results.
        * Makefile: Remove extra flags.

2019-02-01  Svante Signell <svante.signell@gmail.com>

        * Update copyright years.

2016-05-23  Svante Signell <svante.signell@gmail.com>

        * Makefile: Add sub-directory libfshelp-tests.

2018-12-07  Svante Signell <svante.signell@gmail.com>

        * Update copyright years.
        * locks.c(cmd_lock): Call fshelp_rlock_tweak()
          with new last argument rendezvous = MACH_PORT_NULL.

2017-01-05  Svante Signell <svante.signell@gmail.com>

        * Update copyright years and headers.

2016-12-28  Svante Signell <svante.signell@gmail.com>

        * Makefile: test-flock.c, test-lockf.c and test-fcntl.c
        * test-lockf.c: New file
        * Rename set-flock.c, set-fcntl.c to test-flock.c test-fcntl.c
        * TODO: Update README

2016-05-23  Svante Signell <svante.signell@gmail.com>

        * Makefile: Link with pthread, add build of set-flock.c and set-fcntl.c
        * define temporary CPP_FLAGS until glibc is updated
        * set-flock.c, set-fcntl.c: New files.
        * Fix typos in README

2001-04-11  Neal H Walfield  <neal@cs.uml.edu>

        * ChangeLog: New file, mentioning itself in this sentence.
        * Makefile: New file.
        * README: Likewise.
        * fork.c: Likewise.
        * locks: Likewise.
        * locks-tests: Likewise.
        * locks.c: Likewise.
        * race.c: Likewise.

1 files changed, 102 insertions, 0 deletions

diff --git a/libfshelp-tests/README b/libfshelp-tests/README
new file mode 100644
index 00000000..3efc6a94
--- /dev/null
+++ b/libfshelp-tests/README
@@ -0,0 +1,102 @@
+These programs are used to help test the algorithms in the libfshelp
+library.
+
+Record Locking
+==============
+
+Race
+----
+
+Race locks a file, reads an integer, increments it, writes the result to
+the file and then unlocks the file -- 10,000 times.  It is intended that
+multiple instances of this program be run at the same time.  Race takes
+three arguments:  the file to use, the start of the lock and the length.
+For obvious reasons, it is important that all instances of race have
+locks that overlap.  For example:
+
+	# rm -f foo && ( ./race foo 2 0 & ./race foo 2 3 & \
+	> ./race foo 0 3 )
+	Was blocked 5482 times
+	Was blocked 5485 times
+	Was blocked 5479 times
+	# cat foo
+	30000
+
+We see here that each process was blocked several thousand times and that
+the result in the file foo is 30000.  Perfect.
+
+Locks
+-----
+
+Locks is an interactive shell that has one ``file'' and ten open file
+descriptors.  Using some simple commands, one can test to see if locks
+are established, cleared, and enforced.  The principal command is
+`lock,' which takes four parameters.  The first is the file descriptor
+to lock, the second is the start of the lock, the third is the length of
+the lock (0 = until EOF) and the last is the type of lock to establish
+from the set {0: F_UNLCK, 1: F_RDLCK, 2: F_WRLCK}.  Help on the other
+commands can be gotten using the `help' command.
+
+A small run:
+
+	# ./locks
+	> lock 0 10 0 1
+	  0:    Start =   10; Length =    0; Type = F_RDLCK
+
+Lock from byte 10 through the EOF.
+
+	> lock 0 20 0 0
+	  0:    Start =   10; Length =   10; Type = F_RDLCK
+
+Unlock from byte 20 through the EOF.
+
+	> lock 0 11 8 2
+	  0:    Start =   10; Length =    1; Type = F_RDLCK
+	        Start =   11; Length =    8; Type = F_WRLCK
+	        Start =   19; Length =    1; Type = F_RDLCK
+
+Upgrade bytes 11 through 19 to a write lock.
+
+	> lock 0 9 10 1
+	  0:    Start =    9; Length =    2; Type = F_RDLCK
+	        Start =   11; Length =    8; Type = F_WRLCK
+	        Start =   19; Length =    1; Type = F_RDLCK
+
+Add a read lock to byte 9.
+
+	> lock 1 0 10 1
+	  1:    Start =    0; Length =   10; Type = F_RDLCK
+
+Read lock the first ten bytes of the file through file descriptor 1.
+
+	> lock 1 10 0 1
+	Resource temporarily unavailable
+
+Attempts to read lock the rest of the file.  This, however, fails as
+there are outstanding write locks held through file descriptor 1.
+
+	> lock 1 10 0 0
+	  1:    Start =    0; Length =   10; Type = F_RDLCK
+
+What happens when file descriptor tries to unlock the blocked range?
+
+	> lock 1 10 0 2
+	Resource temporarily unavailable
+
+Nothing.
+
+A bunch of tests live in locks-tests.  One can run them through the test
+program using: `./locks < ./locks-test 2>&1 | less'.  If it core dumps or
+triggers an assertion, that is a bug.  Report it.
+
+Fork
+----
+
+Tests to see if the a child inherits the locks across a fork.  According
+to POSIX, the child should not.
+
+	# ./fork foo
+	Parent has a write lock; Others have a write lock.
+	Child has a write lock; Others have a write lock.
+
+We are not POSIX compliant.