comment and describe a little this tricky code

Signed-off-by: Daniel Lezcano <daniel.lezcano@free.fr>
---
 procfs.c |   71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 70 insertions(+), 1 deletion(-)

Index: lxcfs/procfs.c
===================================================================
--- lxcfs.orig/procfs.c
+++ lxcfs/procfs.c
@@ -1,6 +1,36 @@
+/*
+ * Copyright (c) 2009 Daniel Lezcano <daniel.lezcano@free.fr>
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * Author : Daniel Lezcano <daniel.lezcano@free.fr>
+ *
+ * ---
+ * fuse procfs proxy:
+ *
+ * The following program allows to overlap the /proc directory in
+ * order to hide or modify content to be showed to the user.
+ *
+ * Definitions:
+ *  - a file/directory showed as it is in the real /proc is a 'proxy'
+ *  - a file/directory hidden from the initial /proc is a 'shadow'
+ *  - a file/directory changed from the initial /proc is a 'mirror'
+ *
+ * At the init time, we did not bind mounted the old /proc, so we grab
+ * a reference on it and use the openat, opendirat, etc ... to relatively
+ * work with the old /proc directory
+ *
+ * When one of the ops is called (eg. open), we check if the file is
+ * hidden, otherwise we check if it is mirrored, otherwise we call the
+ * real file function syscall (here open).
+ *
+ * This program is intented to be extended ...
+ */
 
 #include <fuse.h>
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -20,6 +50,13 @@ enum {
 	PROCFS_MIRROR,
 };
 
+/*
+ * Global structure when initialization fuse-procfs.
+ *  - procdir is the reference on the old /proc mounting point
+ *  - subdir is a working variable when walking on the dir tree
+ *  - shadow_hash contains the files/directory to be hidden
+ *  - mirror_hash contains the files to be mirrored with their ops
+ */
 struct procfs_info {
 	DIR *procdir;
 	DIR *subdir;
@@ -27,6 +64,9 @@ struct procfs_info {
 	struct hsearch_data mirror_hash;
 };
 
+/*
+ * mirror_ops : file operations to be used for hooking the file content on /proc
+ */
 struct mirror_ops {
 	int (*open)(const char *, struct fuse_file_info *);
 	int (*read)(const char *, char *, size_t, off_t, struct fuse_file_info *);
@@ -44,15 +84,30 @@ static struct mirror_ops meminfo_ops = {
 	.release = meminfo_release,
 };
 
+/*
+ * descriptor for proxy file : when the file is opened, the descriptor is fd
+ * is stored in order to be reused in the read, write, etc ... functions
+ */
 struct proxy_file {
 	int fd;
 };
 
+/*
+ * descriptor for mirror : at the open time, the filename is checked against
+ * the mirror hash table and the corresponding ops are retrieved and stored
+ * in this structure
+ */
 struct mirror_file {
 	struct mirror_ops *ops;
 	void *data;
 };
 
+/*
+ * General file descriptor wrapping all the information for each kind of file
+ * - type describes if it is a mirror or a proxy file
+ * - the union contains the information for the file
+ * - private_data contains something specific stored at open time
+ */
 struct procfs_file {
 	int type;
 	union {
@@ -63,10 +118,16 @@ struct procfs_file {
 	void *private_data;
 };
 
+/*
+ * Statically define the list of the entries we want to hide
+ */
 static ENTRY shadow_entries[] = {
 	{ "sys", NULL },
 };
 
+/*
+ * Statically define the list of the entries we want to mirror
+ */
 static ENTRY mirror_entries[] = {
 	{ "meminfo", &meminfo_ops },
 };
@@ -75,6 +136,9 @@ static ENTRY mirror_entries[] = {
 #define SHADOW_HASH_SIZE 32
 #define MIRROR_HASH_SIZE 32
 
+/*
+ * a simple wrapper function to find an entry in the hash
+ */
 ENTRY *hash_find(char *key, struct hsearch_data *hash)
 {
 	ENTRY entry, *pentry;
@@ -86,6 +150,8 @@ ENTRY *hash_find(char *key, struct hsear
 	return pentry;
 }
 
+/*** fuse ops definitions ***/
+
 static int procfs_readlink(const char *path, char *buf, size_t bufsiz)
 {
 	struct fuse_context *context = fuse_get_context();
@@ -133,6 +199,7 @@ static int procfs_open(const char *path,
 	if (strcmp(path, "/"))
 		bname += 1;
 
+	/* this path is hidden */
  	if (hash_find(bname, &fsinfo->shadow_hash))
  		return -ENOENT;
 
@@ -142,6 +209,7 @@ static int procfs_open(const char *path,
 
 	fi->fh = (typeof(fi->fh))pfile;
 
+	/* this patch must be mirrored */
 	entry = hash_find(bname, &fsinfo->mirror_hash);
 	if (entry) {
 		pfile->type = PROCFS_MIRROR;
@@ -150,6 +218,7 @@ static int procfs_open(const char *path,
 			return pfile->file.mirror.ops->open(path, fi);
 	}
 
+	/* default we proxy the file */
 	pfile->type = PROCFS_PROXY;
 	pfile->file.proxy.fd = openat(dirfd(fsinfo->procdir), bname, fi->flags);
 	if (pfile->file.proxy.fd < 0) {



