added comments

please correct/add comments as you read/write code

comar/src/acl.c

@@ -18,6 +18,7 @@
 #include "log.h"
 #include "iksemel.h"
 
+//! access control group, a group id and level
 struct acl_group {
 	gid_t gid;
 	unsigned int level;
@@ -32,9 +33,16 @@ struct acl_class {
 static gid_t *acl_allowed_gids;
 static unsigned int acl_nr_allowed_gids;
 
+//! Count groups
 static int
 count_groups(iks *tag, int class_no)
 {
+    /*!
+    Returns the number of group tags in child tags of 'tag'
+    It also counts group tags under class tag ( class permissions )
+    @return Returns number of groups
+    */
+
 	iks *x;
 	unsigned int nr = 0;
 	// global permissions
@@ -51,9 +59,15 @@ count_groups(iks *tag, int class_no)
 	return nr;
 }
 
+//! add_allowed
 static void
 add_allowed(gid_t gid)
 {
+    /*!
+    This function allocates memory for allowed group id's. @see acl_allowed_gids
+    Every group is added once
+    */
+
 	static unsigned int max_allowed = 0;
 	unsigned int i;
 
@@ -76,9 +90,16 @@ add_allowed(gid_t gid)
 	acl_allowed_gids[acl_nr_allowed_gids++] = gid;
 }
 
+//! add_group
 static void
 add_group(iks *tag, int level, struct acl_class *ac)
 {
+    /*!
+    Scans the 'tag's 'name' attribute, and searches the result in groups database (unix groups db)
+    When found, numerical group id and level is set to current group structure
+    \param ac is the allocated memory for acl_group structure \param level is permissions level
+    */
+
 	struct acl_group *ag;
 	char *name;
 	struct group *grp;
@@ -97,9 +118,16 @@ add_group(iks *tag, int level, struct acl_class *ac)
 	++ac->cur;
 }
 
+//! add_groups
 static void
 add_groups(iks *tag, int class_no, int level, struct acl_class *ac)
 {
+·   /*!
+·   Searches 'tag' in 'group' and 'class' tags, calls add_group function with found tags
+·   level and acl_class is passed to add_group
+·   \sa add_group
+·   */
+
 	iks *x;
 	// global permissions
 	for (x = iks_find(tag, "group"); x; x = iks_next_tag(x)) {
@@ -114,9 +142,16 @@ add_groups(iks *tag, int class_no, int level, struct acl_class *ac)
 	}
 }
 
+//! set_class
 static void
 set_class(iks *model, int class_no)
 {
+·   /*!
+·   Allocates memory for all found 'group's in 'model' @see count_groups()
+·   Then add_groups is called and acl_class is put in node table
+·   \sa add_groups
+·   */
+
 	struct acl_class *ac;
 	int nr_groups = 0;
 
@@ -135,9 +170,15 @@ set_class(iks *model, int class_no)
 	model_acl_set(class_no, ac);
 }
 
+//! access control initialize
 void
 acl_init(void)
 {
+·   /*!
+·   Loads /etc/comar/security-policy.xml file
+·   For all classes in model.xml file, look in security-policy if theres a match
+·   */
+
 	iks *policy;
 	iks *model;
 	int class_no;
@@ -166,9 +207,15 @@ acl_init(void)
 	}
 }
 
+//! check_acl
 static int
 check_acl(int node, struct Creds *cred)
 {
+·   /*!
+·   Checks if cred->uid user is capable to perform the action,
+·   @return Returns 1 if capable, 0 otherwise
+·   */
+
 	gid_t gids[64];
 	int nr_gids = 64;
 	struct passwd *pw;
@@ -202,10 +249,16 @@ check_acl(int node, struct Creds *cred)
 	return 0;
 }
 
+//! Find if user is ok to execute command
 int
 acl_is_capable(int cmd, int node, struct Creds *cred)
 {
-	// root always capable
+·   /*!
+·   Checks if cred->uid user is capable executing command cmd.
+·   Root is always capable, only CMD_CALL commands are allowed here
+·   @return Returns 1 if allowed, 0 otherwise
+·   */
+
 	if (cred->uid == 0)
 		return 1;
 
@@ -217,9 +270,15 @@ acl_is_capable(int cmd, int node, struct Creds *cred)
 	return 0;
 }
 
+//! Check if user can connect
 int
 acl_can_connect(struct Creds *cred)
 {
+·   /*!
+·   Checks if user with user id cred->uid can connect comar.
+·   @return Returns 1 if can connect, 0 otherwise
+·   */
+
 	gid_t gids[64];
 	int nr_gids = 64;
 	struct passwd *pw;

comar/src/cfg.c

@@ -55,6 +55,7 @@ static struct option longopts[] = {
 
 static char *shortopts = "m:d:s:g:phv";
 
+//! Print usage
 static void
 print_usage(void)
 {
@@ -73,6 +74,7 @@ print_usage(void)
 	);
 }
 
+//! Print version
 static void
 print_version(void)
 {
@@ -87,6 +89,7 @@ print_version(void)
 	);
 }
 
+//! Parse command line options
 void
 cfg_init(int argc, char *argv[])
 {

comar/src/data.c

@@ -24,9 +24,15 @@
 #include "utility.h"
 #include "iksemel.h"
 
+//! Check database format
 static int
 check_db_format(void)
 {
+·   /*!
+·   Checks db format.
+·   @return returns 0 if db is Model db or App db, 1 else
+·   */
+
 	FILE *f;
 	size_t len;
 	char *fmt_name;
@@ -60,9 +66,18 @@ check_db_format(void)
 
 static char *code_lock_name;
 
+//! Database init function
 int
 db_init(void)
 {
+·   /*!
+·   Checks comar db directory and db format, creates if not exists.
+·   Also checks code/lock file
+·   @return Returns 0 on success, \n Returns -1 on error, \n Returns -2 if db type is not app or model \n
+·   Returns -3 if code/lock name is not set ( either theres something wrong with data dir,
+·   or memory allocation error )
+·   */
+
 	struct stat fs;
 	size_t size;
 
@@ -93,6 +108,7 @@ db_init(void)
 	return 0;
 }
 
+//! Structure that carries databases
 struct databases {
 	DB_ENV *env;
 	DB *model;
@@ -106,9 +122,20 @@ struct databases {
 #define CODE_DB 4
 #define PROFILE_DB 8
 
+//! Open a database
 static int
 open_database(DB_ENV *env, DB **dbp, const char *name)
 {
+·   /*!
+·   Creates a DB structure that is the handle for a Berkeley DB database
+·   and opens it as a standalone, sorted - balanced tree structured DB.
+·   env is the environment, and dbp is db type ( model, app, code or profile )
+·   with 'name' file name
+·   @return Returns -1 if can not create database \n
+·   Returns -2 if can not open database \n
+·   Returns 0 otherwise \n
+·   */
+
 	int e;
 	DB *db;
 
@@ -127,9 +154,23 @@ open_database(DB_ENV *env, DB **dbp, const char *name)
 	return 0;
 }
 
+//! Create and open DB_ENV
 static int
 open_env(struct databases *db, int which)
 {
+·   /*!
+·   Creates DB_ENV structure with db_home directory set to
+·   comar db dir. After creating enviroment, opens database
+·   with created env and specified DB type (type is 'which' in this case)
+·   @return Returns -1 if can not create database environment \n
+·   Returns -2 if can not open database environment. \n
+·   Returns -3 if which is a model db, and db could not be created or opened \n
+·   Returns -4 if which is a app db, and db could not be created or opened \n
+·   Returns -5 if which is a code db, and db could not be created or opened \n
+·   Returns -6 if which is a profile db, and db could not be created or opened \n
+·   Returns 0 otherwise
+·   */
+
 	int e;
 
 	memset(db, 0, sizeof(struct databases));
@@ -165,6 +206,7 @@ open_env(struct databases *db, int which)
 	return 0;
 }
 
+//! Close created databases and environment of db
 static void
 close_env(struct databases *db)
 {
@@ -175,10 +217,12 @@ close_env(struct databases *db)
 	db->env->close(db->env, 0);
 }
 
+//! Fetches and returns the record called 'name' from database 'db'
 static char *
 get_data(DB *db, const char *name, size_t *sizep, int *errorp)
 {
-	DBT pair[2];
+    /*! \param errorp Error number returned */	
+    DBT pair[2];
 
 	memset(&pair[0], 0, sizeof(DBT) * 2);
 	pair[0].data = (char *) name;
@@ -193,9 +237,18 @@ get_data(DB *db, const char *name, size_t *sizep, int *errorp)
 	return NULL;
 }
 
+//! Put data to a database
 static int
 put_data(DB *db, const char *name, const char *data, size_t size)
 {
+·   /*!
+·   Puts "name and 'size of name'" as first pair, and
+·   "data and size" as second pair to DB. \n
+·   DBT is key/data pair structure of berkeley db
+·   @return This function can return a non-zero error for errors specified for \n
+·   other Berkeley DB and C library or system functions. or DB_RUNRECOVERY
+·   */
+
 	DBT pair[2];
 
 	memset(&pair[0], 0, sizeof(DBT) * 2);
@@ -206,10 +259,12 @@ put_data(DB *db, const char *name, const char *data, size_t size)
 	return db->put(db, NULL, &pair[0], &pair[1], 0);
 }
 
+//! Delete name from database
 static int
 del_data(DB *db, const char *name)
 {
-	DBT key;
+    /*! @return Returns error number \sa put_data */	
+    DBT key;
 
 	memset(&key, 0, sizeof(DBT));
 	key.data = (char *) name;
@@ -217,9 +272,16 @@ del_data(DB *db, const char *name)
 	return db->del(db, NULL, &key, 0);
 }
 
+//! Make a key string
 static char *
 make_key(int node_no, const char *app)
 {
+·   /*!
+    This function looks for node_no numbered record in node table
+·   and makes a key formatted like: path/app
+·   @return returns the key
+·   */
+
 	const char *path;
 	char *key;
 	size_t size;
@@ -234,9 +296,16 @@ make_key(int node_no, const char *app)
 	return key;
 }
 
+//! Append an item to db
 static int
 append_item(DB *db, const char *key, const char *item)
 {
+·   /*!
+·   If theres no such record, put it in db
+·   @return If item is already in db returns -1 \n
+·   Returns 0 normally
+·   */
+
 	char *t, *s;
 	char *old;
 	char *data;
@@ -279,10 +348,15 @@ append_item(DB *db, const char *key, const char *item)
 	return 0;
 }
 
+//! Put node to db
 int
 db_put_script(int node_no, const char *app, const char *buffer, size_t size)
 {
-	struct databases db;
+·   /**
+·   @return -1 or -2 on error, 0 normally
+·   */
+	
+    struct databases db;
 	int e, ret = -1;
 
 	if (open_env(&db, APP_DB | MODEL_DB)) goto out;
@@ -302,9 +376,15 @@ out:
 	return ret;
 }
 
+//! Delete app application from databases
 int
 db_del_app(const char *app)
 {
+·   /*!
+    Delete app application from app, model and code databases
+·   \sa db_delete_code del_data
+·   */
+
 	struct databases db;
 	char *list, *list2, *t, *s;
 	int e, ret = -1;
@@ -360,16 +440,21 @@ out:
 	return ret;
 }
 
+//! Fetch data
 int
 db_get_apps(int node_no, char **bufferp)
 {
+    /*!
+·   Fetches data of node 'node_no' and writes it to bufferp
+·   @return Returns -1 on error, 0 otherwise
+·   */
 	struct databases db;
 	int e, ret = -1;
 
 	if (open_env(&db, MODEL_DB)) goto out;
 
 	*bufferp = get_data(db.model, model_get_path(node_no), NULL, &e);
-	if (e) goto out;
+	if (e) goto out; // error
 
 	ret = 0;
 out:
@@ -397,9 +482,16 @@ out:
 	return ret;
 }
 
+//! Make a path key to store the code
 static char *
 make_code_key(int node_no, const char *app)
 {
+·   /*!
+·   Key path will be in format: cfg_data_dir/code/script.py
+·   @return Returns the key, or 0 on allocation error
+·   \sa cfg.c
+·   */
+
 	const char *path;
 	char *key;
 	char *t;
@@ -420,9 +512,16 @@ make_code_key(int node_no, const char *app)
 	return key;
 }
 
+//! Lock comar lock file
 static int
 lock_code_db(int is_exclusive)
 {
+·   /*!
+·   Locks the lock file for reading or writing
+·   if is_exclusive is true, lock for writing, otherwise, lock for reading
+·   @return Returns file descriptor to lock file, -1 on error
+·   */
+
 	int fd;
 
 	fd = open(code_lock_name, O_WRONLY | O_CREAT, 0600);
@@ -438,16 +537,26 @@ lock_code_db(int is_exclusive)
 	return fd;
 }
 
+//! Unlocks the file and closes it.
 static void
 unlock_code_db(int fd)
 {
+    /*! @param fd the file descriptor to lock file */
 	flock(fd, LOCK_UN);
 	close(fd);
 }
 
+//! Load code
 int
 db_load_code(int node_no, const char *app, char **bufferp)
 {
+·   /*!
+·   Loads the code numbered 'node_no' in node table, and assigns bufferp to its address
+·   @return Returns -1 on allocation error @see make_code_key \n
+·   Returns -2 if can not load code @see load_code
+·   \sa make_code_key load_file
+·   */
+
 	char *key;
 	char *code;
 	int fd;
@@ -464,9 +573,16 @@ db_load_code(int node_no, const char *app, char **bufferp)
 	return 0;
 }
 
+//! Save code to db
 int
 db_save_code(int node_no, const char *app, const char *buffer)
 {
+·   /*!
+·   @return Returns -1 on file path error \n
+·   Returns -2 on write error \n
+·   Returns 0 normally
+·   */
+
 	char *key;
 	int fd;
 	int ret;
@@ -481,9 +597,17 @@ db_save_code(int node_no, const char *app, const char *buffer)
 	return 0;
 }
 
+//! Delete code from filesystem
 int
 db_delete_code(int node_no, const char *app)
 {
+·   /*!
+    Deletes code numbered 'node_no' in node table from filesystem·
+·   @return Returns -1 on allocation error @see make_code_key \n
+·   Returns -2 on error unlinking file
+·   Returns 0 otherwise
+·   */
+
 	char *key;
 	int fd;
 	int ret;
@@ -498,6 +622,7 @@ db_delete_code(int node_no, const char *app)
 	return 0;
 }
 
+//! Creates a key with format: Node/App/instance=value
 static char *
 make_profile_key(int method, const char *app, const char *inst_key, const char *inst_value)
 {
@@ -594,9 +719,17 @@ out:
 
 struct databases *blaa = NULL;
 
+//! Get key from profile db
 struct pack *
 db_get_profile(int node_no, const char *app, const char *inst_key, const char *inst_value)
 {
+·   /*!
+·   From node_no, app, inst_key and inst_value, this function first makes a profile key
+·   with format node/app/instance=value. Then gets this key from profile db
+·   and returns a pointer to a package structure carrying its data and size
+·   @return Returns a pointer to data pack
+·   */
+
 	struct databases db;
 	struct pack *p = NULL;
 	int e;
@@ -657,6 +790,7 @@ out:
 	close_env(&db);
 }
 
+//! Fetch instance of node/app/key from profile db and send data to function 'func'
 int
 db_get_instances(int node_no, const char *app, const char *key, void (*func)(char *str, size_t size))
 {
@@ -692,6 +826,7 @@ out:
 	return ret;
 }
 
+//! Dump profile db. @return Returns a string representation of tree
 char *
 db_dump_profile(void)
 {
@@ -704,7 +839,7 @@ db_dump_profile(void)
 	char *ret = NULL;
 
 	memset(&pair[0], 0, sizeof(DBT) * 2);
-	pair[1].flags = DB_DBT_MALLOC;
+	pair[1].flags = DB_DBT_MALLOC; // berkeley will handle malloc
 
 	if (open_env(&db, PROFILE_DB)) goto out;
 

comar/src/event.c

@@ -64,6 +64,7 @@ trig_instance(char *str, size_t size)
 	pack_delete(p);
 }
 
+//! Start the startup methods at every comar start
 static void
 trigger_startup_methods(void)
 {
@@ -107,6 +108,7 @@ trigger_startup_methods(void)
 	}
 }
 
+//! event process code
 static void
 event_proc(void)
 {
@@ -118,6 +120,7 @@ event_proc(void)
 	// no more event for now, kernel device events are handled by udev
 }
 
+//! Start the event process
 void
 event_start(void)
 {

comar/src/job.c

@@ -23,6 +23,7 @@ struct ipc_source bk_channel;
 int bk_node;
 char *bk_app;
 
+//! Pack the result and send it to parent
 static int
 send_result(int cmd, const char *data, size_t size)
 {
@@ -54,9 +55,15 @@ job_send_result(int cmd, const char *data, size_t size)
 	return send_result(cmd, data, size);
 }
 
+//! Register the model
 static int
 do_register(int node, const char *app, const char *fname)
 {
+·   /*!
+    Register script by first testing it by compiling.
+·   If it compiles well, put script. \sa db_put_script csl_compile
+    */
+
 	char *buf;
 	char *code;
 	size_t codelen;
@@ -87,6 +94,7 @@ do_register(int node, const char *app, const char *fname)
 	return 0;
 }
 
+//! Remove application \sa db_del_app
 static int
 do_remove(const char *app)
 {
@@ -99,6 +107,7 @@ do_remove(const char *app)
 	return 0;
 }
 
+//! This function acts like do_execute, only executs commands for events. @see do_execute
 static int
 do_event(const char *event, int node, const char *app, struct pack *p)
 {
@@ -137,9 +146,17 @@ do_event(const char *event, int node, const char *app, struct pack *p)
 	return e;
 }
 
+//! Load the app code and execute it through csl
 static int
 do_execute(int node, const char *app, struct pack *pak)
 {
+·   /*!
+    Load the app code and execute it with python/c api @see csl.c
+·   If execution lasts more than 6 seconds, logs this information @see log_info
+·   Returns 0 on a successfull call, returns error returned by csl execute function otherwise
+·   \sa csl.c
+·   */
+
 	struct timeval start, end;
 	unsigned long msec;
 	struct pack *p = NULL;
@@ -206,15 +223,22 @@ do_execute(int node, const char *app, struct pack *pak)
 
 static struct pack *bk_pak;
 
+//! This function calls do_execute with global bk_node, bk_app and bk_pak
 static void
 exec_proc(void)
 {
 	do_execute(bk_node, bk_app, bk_pak);
 }
 
+//! If a call command is triggered, make needed call.
 static int
 do_call(int node, struct pack *pak)
 {
+·   /*!
+    Get scripts and run them, send results and return
+·   @return Returns 0
+    */
+
 	struct pack *p = NULL;
 	char *apps;
 	int ok = 0;
@@ -286,6 +310,7 @@ do_call(int node, struct pack *pak)
 	return 0;
 }
 
+//! This function logs the job and calls execute function @see do_execute
 static int
 do_call_package(int node, const char *app, struct pack *p)
 {
@@ -296,6 +321,7 @@ do_call_package(int node, const char *app, struct pack *p)
 	return 0;
 }
 
+//! Gets a list of applications from database
 static int
 do_getlist(int node)
 {
@@ -315,6 +341,7 @@ do_getlist(int node)
 	return 0;
 }
 
+//! This function calls db_dump_profile and sends the result. @see db_dump_profile
 static int
 do_dump_profile(void)
 {
@@ -331,9 +358,14 @@ do_dump_profile(void)
 	return 0;
 }
 
+//! child job process code
 static void
 job_proc(void)
 {
+·   /*!
+·   Listen for incoming requests and process the commands.
+·   */
+
 	struct ipc_struct ipc;
 	struct pack *p;
 	struct ProcChild *sender;
@@ -342,6 +374,7 @@ job_proc(void)
 	size_t size;
 
 	p = pack_new(256);
+    // wait untill theres something to listen
 	while (1) {
 		if (1 == proc_listen(&sender, &cmd, &size, 1)) break;
 	}
@@ -380,6 +413,7 @@ job_proc(void)
 	}
 }
 
+//! Start a Comar job @see job_proc
 int
 job_start(int cmd, struct ipc_struct *ipc, struct pack *pak)
 {

comar/src/log.c

@@ -19,6 +19,7 @@
 #include "log.h"
 #include "process.h"
 
+//! Puts time into f
 static void
 timestamp(FILE *f)
 {
@@ -32,6 +33,7 @@ timestamp(FILE *f)
 	fputs(buf, f);
 }
 
+//! Prints comar version info and process id to stdout
 static void
 pidstamp(FILE *f)
 {
@@ -41,9 +43,16 @@ pidstamp(FILE *f)
 		fprintf(f, "(%s-%d) ", my_proc.desc + 5, getpid());
 }
 
+//! Print log
 static void
 log_print(const char *fmt, va_list ap, int error)
 {
+·   /*!
+    Writes log to file (cfg_log_file_name) or stdout according to cfg_log_* options
+·   comar version, process id, timestamp and errors(if any) are written
+·   \sa cfg.c
+·   */
+
 	if (cfg_log_console) {
 		pidstamp(stdout);
 		vprintf(fmt, ap);
@@ -65,6 +74,7 @@ log_print(const char *fmt, va_list ap, int error)
 	// FIXME: syslog?
 }
 
+//! Log starter. Permissions of log file are set here
 void
 log_start(void)
 {
@@ -75,9 +85,15 @@ log_start(void)
 	}
 }
 
+//! Error logging
 void
 log_error(const char *fmt, ...)
 {
+·   /*!
+·   Same as log_info, if this function is called instead, writes
+·   information as an 'error' to log file
+·   */
+
 	va_list ap;
 
 	va_start(ap, fmt);
@@ -85,9 +101,16 @@ log_error(const char *fmt, ...)
 	va_end(ap);
 }
 
+//! Print log info
 void
 log_info(const char *fmt, ...)
 {
+·   /*!
+·   Prints log info of variable arguments with log_print function.
+·   Console or file usage depends on cfg_log_* options
+·   \sa log_print cfg.c
+·   */
+
 	va_list ap;
 
 	va_start(ap, fmt);
@@ -95,6 +118,7 @@ log_info(const char *fmt, ...)
 	va_end(ap);
 }
 
+//! Log messages from sub processes for debugging