From 201d78e7bebc0fbf56dceab237d6ee1af8d77c6b Mon Sep 17 00:00:00 2001 From: Mikko Rasa Date: Sun, 9 Aug 2015 15:14:10 +0300 Subject: [PATCH] Add a bunch of comments to the code --- main.c | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) 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=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", >k_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(>k_main_quit), NULL); -- 2.45.2