From: Mikko Rasa <tdb@tdb.fi>
Date: Sun, 9 Aug 2015 12:14:10 +0000 (+0300)
Subject: Add a bunch of comments to the code
X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=201d78e7bebc0fbf56dceab237d6ee1af8d77c6b;p=pmount-gui.git

Add a bunch of comments to the code
---

diff --git a/main.c b/main.c
index 2472f5d..f8b4c2e 100644
--- a/main.c
+++ b/main.c
@@ -30,6 +30,10 @@ typedef struct sDevice
 
 int verbosity = 0;
 
+/**
+Parses a string of the form name=value and places the components in a Property
+structure.  Returns 0 on success, or -1 if the string wasn't a valid property.
+*/
 int parse_property(char *str, int size, Property *prop)
 {
 	int equals = -1;
@@ -53,6 +57,11 @@ int parse_property(char *str, int size, Property *prop)
 	return 0;
 }
 
+/**
+Retrieves all properties associated with a /dev node.  The returned array is
+terminated with an entry containing NULL values.  Use free_properties to free
+the array.
+*/
 Property *get_device_properties(char *node)
 {
 	int pid;
@@ -63,6 +72,7 @@ Property *get_device_properties(char *node)
 	pid = fork();
 	if(pid==0)
 	{
+		/* Child process */
 		if(verbosity>=2)
 			printf("Running udevadm info -q property -n \"%s\"\n", node);
 
@@ -74,6 +84,7 @@ Property *get_device_properties(char *node)
 	}
 	else if(pid>0)
 	{
+		/* Parent process */
 		char *buf;
 		int bufsize;
 		int pos = 0;
@@ -113,6 +124,9 @@ Property *get_device_properties(char *node)
 			{
 				if(eof)
 					break;
+
+				/* There was no newline in the buffer but there is more output to
+				be read.  Try again with a larger buffer. */
 				bufsize *= 2;
 				buf = (char *)realloc(buf, bufsize);
 				continue;
@@ -120,6 +134,7 @@ Property *get_device_properties(char *node)
 
 			if(parse_property(buf, newline, &prop)==0)
 			{
+				/* Reserve space for a sentinel value as well. */
 				props = (Property *)realloc(props, (n_props+2)*sizeof(Property));
 				props[n_props] = prop;
 				++n_props;
@@ -135,6 +150,7 @@ Property *get_device_properties(char *node)
 
 		if(props)
 		{
+			/* Terminate the array with NULL pointers. */
 			props[n_props].name = NULL;
 			props[n_props].value = NULL;
 		}
@@ -153,6 +169,10 @@ Property *get_device_properties(char *node)
 	}
 }
 
+/**
+Looks for a property in an array of properties and returns its value.  Returns
+NULL if the property was not found.
+*/
 char *get_property_value(Property *props, char *name)
 {
 	int i;
@@ -162,6 +182,10 @@ char *get_property_value(Property *props, char *name)
 	return NULL;
 }
 
+/**
+Checks if a property has a specific value.  A NULL value is matched if the
+property does not exist.
+*/
 int match_property_value(Property *props, char *name, char *value)
 {
 	char *v = get_property_value(props, name);
@@ -170,6 +194,9 @@ int match_property_value(Property *props, char *name, char *value)
 	return strcmp(v, value)==0;
 }
 
+/**
+Frees an array of properties and all strings contained in it.
+*/
 void free_properties(Property *props)
 {
 	int i;
@@ -183,6 +210,9 @@ void free_properties(Property *props)
 	free(props);
 }
 
+/**
+Reads device names from an fstab/mtab file.
+*/
 char **get_mount_entries(char *filename, int (*predicate)(struct mntent *))
 {
 	FILE *file;
@@ -209,21 +239,33 @@ char **get_mount_entries(char *filename, int (*predicate)(struct mntent *))
 	return devices;
 }
 
+/**
+Returns an array of all currently mounted devices.
+*/
 char **get_mounted_devices(void)
 {
 	return get_mount_entries("/etc/mtab", NULL);
 }
 
+/**
+Checks if an fstab entry has the user option set.
+*/
 int is_user_mountable(struct mntent *me)
 {
 	return hasmntopt(me, "user")!=NULL;
 }
 
+/**
+Returns an array of user-mountable devices listed in fstab.
+*/
 char **get_fstab_devices(void)
 {
 	return get_mount_entries("/etc/fstab", &is_user_mountable);
 }
 
+/**
+Checks if an array of strings contains the specified string.
+*/
 int is_in_array(char **array, char *str)
 {
 	int i;
@@ -235,6 +277,9 @@ int is_in_array(char **array, char *str)
 	return 0;
 }
 
+/**
+Frees an array of strings.
+*/
 void free_string_array(char **array)
 {
 	int i;
@@ -245,6 +290,9 @@ void free_string_array(char **array)
 	free(array);
 }
 
+/**
+Checks if a partition identified by a sysfs path is on a removable device.
+*/
 int is_removable(char *devpath)
 {
 	char fnbuf[256];
@@ -253,11 +301,15 @@ int is_removable(char *devpath)
 	int fd;
 
 	len = snprintf(fnbuf, sizeof(fnbuf), "/sys%s", devpath);
+	/* Default to not removable if the path was too long. */
 	if(len+10>=(int)sizeof(fnbuf))
 		return 0;
 
+	/* We got a partition as a parameter, but the removable property is on the
+	disk.  Replace the last component with "removable". */
 	for(ptr=fnbuf+len; (ptr>fnbuf && *ptr!='/'); --ptr) ;
 	strcpy(ptr, "/removable");
+
 	fd = open(fnbuf, O_RDONLY);
 	if(fd!=-1)
 	{
@@ -277,6 +329,11 @@ int is_removable(char *devpath)
 	return 0;
 }
 
+/**
+Checks if a partition's disk or any of its parent devices are connected to any
+of a set of buses.  The device is identified by a sysfs path.  The bus array
+must be terminated with a NULL entry.
+*/
 int check_buses(char *devpath, char **buses)
 {
 	char fnbuf[256];
@@ -284,6 +341,7 @@ int check_buses(char *devpath, char **buses)
 	int len;
 
 	len = snprintf(fnbuf, sizeof(fnbuf), "/sys%s", devpath);
+	/* Default to no match if the path was too long. */
 	if(len+10>=(int)sizeof(fnbuf))
 		return 0;
 
@@ -291,18 +349,22 @@ int check_buses(char *devpath, char **buses)
 		if(*ptr=='/')
 		{
 			char linkbuf[256];
+			/* Replace the last component with "subsystem". */
 			strcpy(ptr, "/subsystem");
 			len = readlink(fnbuf, linkbuf, sizeof(linkbuf)-1);
 
 			if(len!=-1)
 			{
 				linkbuf[len] = 0;
+				/* Extract the last component of the subsystem symlink. */
 				for(; (len>0 && linkbuf[len-1]!='/'); --len) ;
+
 				if(verbosity>=2)
 				{
 					*ptr = 0;
 					printf("  Subsystem of %s is %s\n", fnbuf, linkbuf+len);
 				}
+
 				if(is_in_array(buses, linkbuf+len))
 					return 1;
 			}
@@ -311,6 +373,11 @@ int check_buses(char *devpath, char **buses)
 	return 0;
 }
 
+/**
+Check if an array of properties describes a device that can be mounted.  An
+array of explicitly allowed devices can be passed in as well.  Both arrays must
+be terminated by a NULL entry.
+*/
 int can_mount(Property *props, char **allowed)
 {
 	static char *removable_buses[] = { "usb", "firewire", 0 };
@@ -322,9 +389,12 @@ int can_mount(Property *props, char **allowed)
 	if(is_in_array(allowed, devname))
 		return 1;
 
+	/* Special case for CD devices, since they are not partitions.  Only allow
+	mounting if media is inserted. */
 	if(match_property_value(props, "ID_TYPE", "cd") && match_property_value(props, "ID_CDROM_MEDIA", "1"))
 		return 1;
 
+	/* Only allow mounting partitions. */
 	if(!match_property_value(props, "DEVTYPE", "partition"))
 		return 0;
 
@@ -332,6 +402,9 @@ int can_mount(Property *props, char **allowed)
 	if(is_removable(devpath))
 		return 1;
 
+	/* Certain buses are removable by nature, but devices only advertise
+	themselves as removable if they support removable media, e.g. memory card
+	readers. */
 	bus = get_property_value(props, "ID_BUS");
 	if(is_in_array(removable_buses, bus))
 		return 1;
@@ -339,6 +412,10 @@ int can_mount(Property *props, char **allowed)
 	return check_buses(devpath, removable_buses);
 }
 
+/**
+Returns an array of all device nodes in a directory.  Symbolic links are
+dereferenced.
+*/
 char **get_device_nodes(char *dirname)
 {
 	DIR *dir;
@@ -361,6 +438,7 @@ char **get_device_nodes(char *dirname)
 		char *node;
 		int duplicate = 0;
 
+		/* Ignore . and .. entries. */
 		if(de->d_name[0]=='.' && (de->d_name[1]==0 || (de->d_name[1]=='.' && de->d_name[2]==0)))
 			continue;
 
@@ -379,6 +457,8 @@ char **get_device_nodes(char *dirname)
 			}
 		}
 
+		/* There may be multiple symlinks to the same device.  Only include each
+		device once in the returned array. */
 		if(checked)
 		{
 			for(i=0; (!duplicate && i<n_checked); ++i)
@@ -415,6 +495,7 @@ char **get_device_nodes(char *dirname)
 	return nodes;
 }
 
+/** Returns an array of all mountable devices. */
 Device *get_devices(void)
 {
 	char **nodes = NULL;
@@ -465,6 +546,8 @@ Device *get_devices(void)
 
 			devname = get_property_value(props, "DEVNAME");
 
+			/* Get a human-readable label for the device.  Use filesystem label,
+			filesystem UUID or device node name in order of preference. */
 			label = get_property_value(props, "ID_FS_LABEL");
 			if(!label)
 				label = get_property_value(props, "ID_FS_UUID");
@@ -487,6 +570,7 @@ Device *get_devices(void)
 
 			stat(nodes[i], &st);
 
+			/* Reserve space for a sentinel entry. */
 			devices = (Device *)realloc(devices, (n_devices+2)*sizeof(Device));
 			devices[n_devices].node = nodes[i];
 			devices[n_devices].label = strdup(label);
@@ -505,6 +589,7 @@ Device *get_devices(void)
 
 	if(devices)
 	{
+		/* Terminate the array with NULL pointers. */
 		devices[n_devices].node = NULL;
 		devices[n_devices].label = NULL;
 		devices[n_devices].description = NULL;
@@ -513,6 +598,9 @@ Device *get_devices(void)
 	return devices;
 }
 
+/**
+Frees an array of devices and all strings contained in it.
+*/
 void free_devices(Device *devices)
 {
 	int i;
@@ -527,6 +615,10 @@ void free_devices(Device *devices)
 	free(devices);
 }
 
+/**
+Callback for activating a row in the device list.  Mounts or unmounts the
+device depending on operating mode.
+*/
 void row_activated(GtkTreeView *list, GtkTreePath *path, GtkTreeViewColumn *column, gpointer user_data)
 {
 	GtkTreeModel *model;
@@ -548,6 +640,7 @@ void row_activated(GtkTreeView *list, GtkTreePath *path, GtkTreeViewColumn *colu
 		pid = fork();
 		if(pid==0)
 		{
+			/* Child process */
 			if(verbosity>=1)
 			{
 				if(umount)
@@ -568,6 +661,7 @@ void row_activated(GtkTreeView *list, GtkTreePath *path, GtkTreeViewColumn *colu
 		}
 		else if(pid>0)
 		{
+			/* Parent process */
 			char buf[1024];
 			int pos = 0;
 			int status = 0;
@@ -582,6 +676,8 @@ void row_activated(GtkTreeView *list, GtkTreePath *path, GtkTreeViewColumn *colu
 
 			while(1)
 			{
+				/* The write fd for the pipe may be inherited by a fuse server
+				process and stay open indefinitely. */
 				if(select(pipe_fd[0]+1, &fds, NULL, NULL, &timeout))
 				{
 					int len;
@@ -622,6 +718,8 @@ void row_activated(GtkTreeView *list, GtkTreePath *path, GtkTreeViewColumn *colu
 			{
 				GtkWidget *dialog;
 
+				/* Pmount terminated with nonzero status or a signal.  Display an
+				error to the user. */
 				dialog = gtk_message_dialog_new(NULL, 0, GTK_MESSAGE_ERROR, GTK_BUTTONS_OK, "%s", buf);
 				g_signal_connect(dialog, "response", &gtk_main_quit, NULL);
 				gtk_widget_show_all(dialog);
@@ -634,6 +732,10 @@ void row_activated(GtkTreeView *list, GtkTreePath *path, GtkTreeViewColumn *colu
 	(void)column;
 }
 
+/**
+Callback for the mount/unmount button.  Causes the selected row in the device
+list to be activated.
+*/
 void button_clicked(GtkButton *button, gpointer user_data)
 {
 	GtkWidget *list = (GtkWidget *)user_data;
@@ -651,6 +753,9 @@ void button_clicked(GtkButton *button, gpointer user_data)
 	(void)button;
 }
 
+/**
+Global key press callback for the window.
+*/
 gboolean key_press(GtkWidget *widget, GdkEvent *event, gpointer user_data)
 {
 	if(event->key.keyval==GDK_KEY_Escape)
@@ -725,6 +830,7 @@ int main(int argc, char **argv)
 	n_listed = 0;
 	if(devices)
 	{
+		/* Populate the list with devices in appropriate state. */
 		latest = 0;
 		for(i=0; devices[i].node; ++i)
 			if(!devices[i].mounted==!umount)
@@ -733,6 +839,7 @@ int main(int argc, char **argv)
 				gtk_list_store_set(store, &iter, 0, devices[i].description, 1, &devices[i], -1);
 				if(devices[i].time>latest)
 				{
+					/* Pre-select the device that appeared on the system most recently. */
 					latest = devices[i].time;
 					gtk_tree_selection_select_iter(selection, &iter);
 				}
@@ -748,6 +855,7 @@ int main(int argc, char **argv)
 	{
 		GtkWidget *dialog;
 
+		/* Don't show the main window if no devices were listed. */
 		dialog = gtk_message_dialog_new(NULL, 0, GTK_MESSAGE_WARNING, GTK_BUTTONS_OK,
 			"No devices to %s", (umount ? "unmount" : "mount"));
 		g_signal_connect(dialog, "response", G_CALLBACK(&gtk_main_quit), NULL);