commit 4947010ee5b703090a638870bd5557eb613305f4
parent 6dbe2f6b0541c5eef5efcf1bdd753858d86f4f0e
Author: Kyle Milz <kyle@0x30.net>
Date: Fri, 13 Oct 2017 11:43:17 -0700
lib: add function comments and a license
Diffstat:
2 files changed, 70 insertions(+), 15 deletions(-)
diff --git a/lib/lib_os.h b/lib/lib_os.h
@@ -1,7 +1,48 @@
/*
- * Operating system specific functions.
+ * Copyright (c) 2017 Kyle Milz <kyle@0x30.net>
+ *
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+/*
+ * Extend the length of the file descriptor given by the first argument by at
+ * least the number of bytes given as the second argument.
+ *
+ * Returns a pointer to the beginning of the newly allocated region on success.
*/
void *citrun_extend(int, size_t);
+
+/*
+ * Creates a new semi random file name, opens it and returns the descriptor.
+ * If the CITRUN_PROCDIR environment variable is set its value is prefixed to
+ * the file name otherwise an operating system specific prefix is used.
+ *
+ * Returns the descriptor number on success.
+ */
int citrun_open_fd();
+
+/*
+ * Takes a pointer to `struct citrun_header` and fills in as many header fields
+ * as possible.
+ */
void citrun_os_info(struct citrun_header *);
+
+/*
+ * Checks if the global `citrun_gl.lock` file is in the directory given by
+ * CITRUN_PROCDIR if it exists. If CITRUN_PROCDIR does not exist an operating
+ * system specific location is used instead.
+ *
+ * If no lock file exists, a viewer is started.
+ */
void citrun_start_viewer();
diff --git a/lib/lib_unix.c b/lib/lib_unix.c
@@ -30,13 +30,22 @@
#define UNIX_PROCDIR "/tmp/citrun"
+
+/*
+ * Implementation of lib_os.h interface for at least:
+ * - OpenBSD
+ * - Darwin
+ * - Linux
+ */
+
/*
- * Extend the length of the file descriptor passed as the first argument, by a
- * number of bytes (rounded up to a convenient size) given by the second
- * argument.
+ * Rounds up the second argument to a multiple of the system page size, which
+ * makes working with mmap nicer.
*
- * Returns a pointer to the beginning of the extended region on success.
- * Instrumented program exits nonzero on failure.
+ * Get the current mapping length, extend it by truncation and then extend the
+ * memory mapping.
+ *
+ * If this function fails the instrumented program will exit nonzero.
*/
void *
citrun_extend(int fd, size_t req_bytes)
@@ -67,12 +76,13 @@ citrun_extend(int fd, size_t req_bytes)
}
/*
- * Opens a new file semi randomly named like "my_program_name_3IcD7HyvoZ".
- * If the CITRUN_PROCDIR environment variable is set its value is prefixed to
- * the file name else "/tmp/citrun/" is prefixed.
+ * If CITRUN_PROCDIR is not set UNIX_PROCDIR is used as a prefix. Attempt to
+ * create the prefix but don't error if it already exists.
+ *
+ * Create a file name by concatenating the program name with a 10 character (man
+ * page suggests this amount) random template and pass that to mkstemp(3).
*
- * Returns a new file descriptor with a unique file system path on success.
- * Instrumented program exits nonzero on failure.
+ * If this program fails the instrumented program will exit nonzero.
*/
int
citrun_open_fd()
@@ -82,7 +92,7 @@ citrun_open_fd()
int fd;
if ((procdir = getenv("CITRUN_PROCDIR")) == NULL)
- procdir = "/tmp/citrun";
+ procdir = UNIX_PROCDIR;
if (mkdir(procdir, S_IRWXU) && errno != EEXIST)
err(1, "mkdir '%s'", procdir);
@@ -99,10 +109,14 @@ citrun_open_fd()
}
/*
- * Takes a pointer to a struct citrun_header and fills in fields related to
- * process id, program name, and working directory.
+ * Fills in the following fields:
+ * - process id
+ * - parent process id
+ * - process group
+ * - program name
+ * - current working directory
*
- * Returns nothing and never fails.
+ * This function doesn't fail.
*/
void
citrun_os_info(struct citrun_header *h)
