Add a bunch of comments to the code
authorMikko Rasa <tdb@tdb.fi>
Sun, 9 Aug 2015 12:14:10 +0000 (15:14 +0300)
committerMikko Rasa <tdb@tdb.fi>
Sun, 9 Aug 2015 12:40:54 +0000 (15:40 +0300)
main.c

diff --git a/main.c b/main.c
index 2472f5db6057f2b1e2b4b31175f333e124f7a3ae..f8b4c2ef664eabe93f1c92f0fa5fb2b062f19e56 100644 (file)
--- 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);