Polished txt and finally threw out getter functions

doc/ddlp.txt

@@ -12,7 +12,7 @@ has to take some extra precautions to participate.
 If a program does not feel vulnerable to disturbance, then the precautions
 impose much less effort than if the program feels the need for protection.
 
-Two levels are specified:
+Two locking strategies are specified:
 DDLP-A operates on device files only. It is very Linux specific.
 DDLP-B adds proxy lock files, inspired by FHS /var/lock standard.
 
@@ -30,9 +30,9 @@ So this is advisory and exclusive locking.
 With kernel 2.6 it seems to work on all device drivers which might get used
 to access a CD/DVD drive.
 
-The vulnerable programs do not start their operation before they occupied a
+The vulnerable programs shall not start their operation before they occupied a
 wide collection of drive representations.
-Non-vulnerable programs take care to detect the occupation of _one_ such
+Non-vulnerable programs shall take care to detect the occupation of _one_ such
 representation.
 
                           So for Friendly Programs

libburn/ddlpa.c

@@ -16,8 +16,6 @@
 #include <sys/ioctl.h>
 #include <scsi/scsi.h>
 
-/* No getter functions. This makes the compiled code leaner. */
-#define DDLPA_H_NOT_ENCAPSULATED 1
 
 /* All callers of ddlpa must do this */
 #include "ddlpa.h"
@@ -322,6 +320,9 @@ static int ddlpa_std_by_btl(struct ddlpa_lock *o)
 
 		return 0;
 	}
+
+	/* >>> add more info about busy and forbidden paths */
+
 	return ENOENT;
 }
 
@@ -344,7 +345,8 @@ static int ddlpa_open_all(struct ddlpa_lock *o)
 			/* There may be the same rdev but different inode. */
 			no_o_excl = (o->sibling_rdevs[i] == o->rdev);
 		
-			/* Look for multiply registered device drivers */	
+			/* Look for multiply registered device drivers with
+			   distinct inodes. */	
 			for (j = 0; j < i; j++) {
 				if (o->sibling_devs[j] == o->sibling_devs[i] &&
 			   	  o->sibling_inodes[j] == o->sibling_inodes[i])
@@ -467,40 +469,10 @@ int ddlpa_lock_btl(int bus, int target, int lun,
 }
 
 
-#ifndef DDLPA_H_NOT_ENCAPSULATED
+#ifdef DDLPA_C_STANDALONE
-
-int ddlpa_get_fd(struct ddlpa_lock *lockbundle)
-{
-	/* >>> */
-	return -1;
-}
-
-
-char *ddlpa_get_fd_path(struct ddlpa_lock *lockbundle)
-{
-	/* >>> */
-	return "none";
-}
-
-
-int ddlpa_get_siblings(struct ddlpa_lock *lockbundle, 
-			char **std_path, int *num_siblings,
-			char ***sibling_paths, int **sibling_fds)
-{
-	*num_siblings = 0;
-
-	/* >>> */
-
-	return 1;
-}
-
-#endif /* ! DDLPA_H_NOT_ENCAPSULATED */
-
 
 /* ----------------------------- Test / Demo -------------------------- */
 
-#ifdef DDLPA_C_STANDALONE
-
 
 int main(int argc, char **argv)
 {
@@ -520,14 +492,19 @@ usage:;
 
 	if (my_path[0] != '/' && my_path[0] != '.' &&
 	    strchr(my_path, ',') != NULL) {
-		/* cdrecord style dev=Bus,Target,Lun */
+		/* 
+		   cdrecord style dev=Bus,Target,Lun
+		*/
+
 		sscanf(my_path, "%d,%d,%d", &bus, &target, &lun);
 		ret = ddlpa_lock_btl(bus, target, lun, O_RDWR, 0, &lck,
 					 &errmsg);
 	} else {
-		/* This substitutes for:
+		/*
+		   This substitutes for:
 			fd = open(my_path, O_RDWR | O_EXCL);
 		*/
+
 		ret = ddlpa_lock_path(my_path, O_RDWR, 0, &lck, &errmsg);
 	}
 	if (ret) {
@@ -537,7 +514,7 @@ usage:;
 				errmsg);
 		free(errmsg);
 		fprintf(stderr, "Error condition : %d '%s'\n",
-			errno, strerror(errno));
+			ret, strerror(ret));
 		exit(2);
 	}
 	fd = lck->fd;

libburn/ddlpa.h

@@ -3,28 +3,14 @@
    Implementation of Delicate Device Locking Protocol level A.
    Copyright (C) 2007 Thomas Schmitt <scdbackup@gmx.net>
    Provided under any of the following licenses: GPL, LGPL, BSD. Choose one.
+
+   See ../doc/ddlp.txt for a description of the protocol.
 */
 
 #ifndef DDLPA_H_INCLUDED
 #define DDLPA_H_INCLUDED 1
 
 
-/* >>> For now : do not encapsulate the details of struct ddlpa_lock */
-#ifndef DDLPA_H_NOT_ENCAPSULATED
-#define DDLPA_H_NOT_ENCAPSULATED 1
-#endif
-
-
-#ifndef DDLPA_H_NOT_ENCAPSULATED
-
-/** Container for locking state and parameters.
-*/
-struct ddlpa_lock;
-
-
-#else /* ! DDLPA_H_NOT_ENCAPSULATED */
-
-
 /* An upper limit for the length of standard paths and sibling paths */
 #define DDLPA_MAX_STD_LEN 15
 
@@ -60,8 +46,6 @@ struct ddlpa_lock {
 	char *errmsg;
 };
 
-#endif /* DDLPA_H_NOT_ENCAPSULATED */
-
 
 
 /** Lock a recorder by naming a device file path. Allocate a new container.
@@ -71,12 +55,11 @@ struct ddlpa_lock {
     @param ddlpa_flags 0 = default behavior: the standard path will be opened
                            and treated by fcntl(F_SETLK)
                        DDLPA_OPEN_GIVEN_PATH causes the input parameter "path"
-                       to be used with open(2) and fcntl(2). Caution: This
+                       to be used with open(2) and fcntl(2).
-                       weakens the fcntl part of DDLP-A.
                        DDLPA_ALLOW_MISSING_SGRCD allows to grant a lock
-                       although not both, a sg and a sr|scd device, have been
+                       although not all three, a sg, a sr and a scd device
-                       found during sibling search. Normally this is counted
+                       file have been found during sibling search. Normally
-                       as failure due to EBUSY. 
+                       this is counted as failure due to EBUSY. 
     @param lockbundle  gets allocated and then represents the locking state
     @param errmsg      if *errmsg is not NULL after the call, it contains an
                        error message. Then to be released by free(3).
@@ -113,42 +96,6 @@ int ddlpa_destroy(struct ddlpa_lock **lockbundle);
 
 
 
-#ifndef DDLPA_H_NOT_ENCAPSULATED
-
-/** Obtain the file descriptor for doing serious work on the recorder.
-    @param lockbundle  the lock which has been activated either by
-                       ddlpa_lock_path() or ddlpa_lock_btl()
-    @return            the file descriptor
-*/
-int ddlpa_get_fd(struct ddlpa_lock *lockbundle);
-
-/** Obtain the path which was used to open the file descriptor.
-    @param lockbundle  the lock
-    @return            a pointer to the path string. 
-                       Do not alter that string ! Do not free(3) it !
-*/
-char *ddlpa_get_fd_path(struct ddlpa_lock *lockbundle);
-
-
-/* Obtain info about the standard path and eventual locked siblings.
-    @param lockbundle    the lock to inquire
-    @param std_path      a pointer to the string with the standard path.
-                         Do not alter that string ! Do not free(3) it !
-    @param num_siblings  Tells the number of elements in sibling_*[].
-                         0 and 1 will be the most frequent values.
-    @param sibling_paths Tells the device file paths of the opened sibling
-                         device representations
-                         Do not alter those strings ! Do not free(3) them !
-    @param sibling_fds   Contains the opened file descriptors on sibling_paths
-    @return              0=success , 1=failure (will hardly happen) 
-*/
-int ddlpa_get_siblings(struct ddlpa_lock *lockbundle, 
-                       char **std_path, int *num_siblings,
-                       char ***sibling_paths, int **sibling_fds);
-
-#endif /* ! DDLPA_H_NOT_ENCAPSULATED */
-
-
 /** Definitions of macros used in above functions */
 
 #define DDLPA_OPEN_GIVEN_PATH 1