Clarify comments in API examples.

docs/examples/crypt_log_usage.c

@@ -1,5 +1,5 @@
 /*
- * An example of using logging through libcryptsetup API
+ * libcryptsetup API log example
  *
  * Copyright (C) 2011-2019 Red Hat, Inc. All rights reserved.
  *
@@ -25,10 +25,8 @@
 #include <libcryptsetup.h>
 
 /*
- * This is an example of function that can be registered using crypt_set_log_callback API.
+ * This is an example of crypt_set_log_callback API callback.
  *
- * Its prototype is void (*log)(int level, const char *msg, void *usrptr) as defined
- * in crypt_set_log_callback
  */
 static void simple_syslog_wrapper(int level, const char *msg, void *usrptr)
 {
@@ -71,7 +69,7 @@ int main(void)
 		return 2;
 	}
 
-	/* crypt_set_log_callback() - register a log function for crypt context */
+	/* crypt_set_log_callback() - register a log callback for crypt context */
 	crypt_set_log_callback(cd, &simple_syslog_wrapper, (void *)usrprefix);
 
 	/* send messages ithrough the crypt_log() interface */
@@ -83,7 +81,7 @@ int main(void)
 	/* release crypt context */
 	crypt_free(cd);
 
-	/* Initialize default (global) log function */
+	/* Initialize default (global) log callback */
 	crypt_set_log_callback(NULL, &simple_syslog_wrapper, NULL);
 
 	crypt_log(NULL, CRYPT_LOG_NORMAL, "This is normal log message");

docs/examples/crypt_luks_usage.c

@@ -1,5 +1,5 @@
 /*
- * An example of using LUKS device through libcryptsetup API
+ *  libcryptsetup API - using LUKS device example
  *
  * Copyright (C) 2011-2019 Red Hat, Inc. All rights reserved.
  *
@@ -32,19 +32,15 @@ static int format_and_add_keyslots(const char *path)
 	int r;
 
 	/*
-	 * crypt_init() call precedes most of operations of cryptsetup API. The call is used
+	 * The crypt_init() call is used  to initialize crypt_device context,
-	 * to initialize crypt device context stored in structure referenced by _cd_ in
+	 * The path parameter specifies a device path.
-	 * the example. Second parameter is used to pass underlaying device path.
 	 *
-	 * Note:
+	 * For path, you can use either link to a file or block device.
-	 * If path refers to a regular file it'll be attached to a first free loop device.
+	 * The loopback device will be detached automatically.
-	 * crypt_init() operation fails in case there's no more loop device available.
-	 * Also, loop device will have the AUTOCLEAR flag set, so the file loopback will
-	 * be detached automatically.
 	 */
 
 	r = crypt_init(&cd, path);
-	if (r < 0 ) {
+	if (r < 0) {
 		printf("crypt_init() failed for %s.\n", path);
 		return r;
 	}
@@ -52,49 +48,37 @@ static int format_and_add_keyslots(const char *path)
 	printf("Context is attached to block device %s.\n", crypt_get_device_name(cd));
 
 	/*
-	 * So far no data were written on your device. This will change with call of
+	 * So far, no data were written to the device.
-	 * crypt_format() only if you specify CRYPT_LUKS2 as device type.
 	 */
-	printf("Device %s will be formatted to LUKS device after 5 seconds.\n"
+	printf("Device %s will be formatted as a LUKS device after 5 seconds.\n"
 	       "Press CTRL+C now if you want to cancel this operation.\n", path);
 	sleep(5);
 
 	/*
 	 * NULLs for uuid and volume_key means that these attributes will be
-	 * generated during crypt_format(). Volume key is generated with respect
+	 * generated during crypt_format().
-	 * to key size parameter passed to function.
-	 *
-	 * crypt_format() checks device size (LUKS header must fit there).
 	 */
 	r = crypt_format(cd,		/* crypt context */
-			 CRYPT_LUKS2,	/* LUKS2 is new LUKS header; use CRYPT_LUKS1 for LUKS1 */
+			 CRYPT_LUKS2,	/* LUKS2 is a new LUKS format; use CRYPT_LUKS1 for LUKS1 */
 			 "aes",		/* used cipher */
-			 "xts-plain64",	/* used block mode and IV generator*/
+			 "xts-plain64",	/* used block mode and IV */
 			 NULL,		/* generate UUID */
 			 NULL,		/* generate volume key from RNG */
 			 512 / 8,	/* 512bit key - here AES-256 in XTS mode, size is in bytes */
 			 NULL);		/* default parameters */
 
-	if(r < 0) {
+	if (r < 0) {
 		printf("crypt_format() failed on device %s\n", crypt_get_device_name(cd));
 		crypt_free(cd);
 		return r;
 	}
 
 	/*
-	 * The device now contains LUKS header, but there is
+	 * The device now contains a LUKS header, but there is no active keyslot.
-	 * no active keyslot with encrypted volume key yet.
-	 */
-
-	/*
-	 * cryptt_kesylot_add_* call stores volume_key in encrypted form into keyslot.
-	 * Without keyslot you can't manipulate with LUKS device after the context will be freed.
 	 *
-	 * To create a new keyslot you need to supply the existing one (to get the volume key from) or
+	 * crypt_keyslot_add_* call stores the volume_key in the encrypted form into the keyslot.
-	 * you need to supply the volume key.
 	 *
-	 * After format, we have volume key stored internally in context so add new keyslot
+	 * After format, the volume key is stored internally.
-	 * using this internal volume key.
 	 */
 	r = crypt_keyslot_add_by_volume_key(cd,			/* crypt context */
 					    CRYPT_ANY_SLOT,	/* just use first free slot */
@@ -112,8 +96,8 @@ static int format_and_add_keyslots(const char *path)
 	printf("The first keyslot is initialized.\n");
 
 	/*
-	 * Add another keyslot, now using the first keyslot.
+	 * Add another keyslot, now authenticating with the first keyslot.
-	 * It will decrypt volume key from the first keyslot and creates new one with another passphrase.
+	 * It decrypts the volume key from the first keyslot and creates a new one with the specified passphrase.
 	 */
 	r = crypt_keyslot_add_by_passphrase(cd,			/* crypt context */
 					    CRYPT_ANY_SLOT,	/* just use first free slot */
@@ -139,18 +123,15 @@ static int activate_and_check_status(const char *path, const char *device_name)
 
 	/*
 	 * LUKS device activation example.
-	 * It's sequence of sub-steps: device initialization, LUKS header load
-	 * and the device activation itself.
 	 */
 	r = crypt_init(&cd, path);
-	if (r < 0 ) {
+	if (r < 0) {
 		printf("crypt_init() failed for %s.\n", path);
 		return r;
 	}
 
 	/*
-	 * crypt_load() is used to load the LUKS header from block device
+	 * crypt_load() is used to load existing LUKS header from a block device
-	 * into crypt_device context.
 	 */
 	r = crypt_load(cd,		/* crypt context */
 		       CRYPT_LUKS,	/* requested type - here LUKS of any type */
@@ -163,11 +144,11 @@ static int activate_and_check_status(const char *path, const char *device_name)
 	}
 
 	/*
-	 * Device activation creates device-mapper devie mapping with name device_name.
+	 * Device activation creates a device-mapper device with the specified name.
 	 */
 	r = crypt_activate_by_passphrase(cd,		/* crypt context */
 					 device_name,	/* device name to activate */
-					 CRYPT_ANY_SLOT,/* which slot use (ANY - try all) */
+					 CRYPT_ANY_SLOT,/* the keyslot use (try all here) */
 					 "foo", 3,	/* passphrase */
 					 CRYPT_ACTIVATE_READONLY); /* flags */
 	if (r < 0) {
@@ -182,7 +163,7 @@ static int activate_and_check_status(const char *path, const char *device_name)
 	printf("\tdevice UUID: %s\n", crypt_get_uuid(cd));
 
 	/*
-	 * Get info about active device (query DM backend)
+	 * Get info about the active device.
 	 */
 	r = crypt_get_active_device(cd, device_name, &cad);
 	if (r < 0) {
@@ -210,7 +191,7 @@ static int handle_active_device(const char *device_name)
 	int r;
 
 	/*
-	 * crypt_init_by_name() initializes device context and loads LUKS header from backing device
+	 * crypt_init_by_name() initializes context by an active device-mapper name
 	 */
 	r = crypt_init_by_name(&cd, device_name);
 	if (r < 0) {
@@ -227,7 +208,7 @@ static int handle_active_device(const char *device_name)
 	}
 
 	/*
-	 * crypt_deactivate() is used to deactivate device
+	 * crypt_deactivate() is used to deactivate a device
 	 */
 	r = crypt_deactivate(cd, device_name);
 	if (r < 0) {