summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJosé Bollo <jose.bollo@iot.bzh>2016-03-15 10:13:13 +0100
committerJosé Bollo <jose.bollo@iot.bzh>2016-03-15 10:13:13 +0100
commit9c6132dd0bfaca8edae84906ad70a6205b5ba42f (patch)
tree5d25a61df2850b079e7e9f546531c4e651e957ef
parent6ed448e9374ae0b3e2cb78eda2a892151b6ddcfa (diff)
wgt: add comments
Change-Id: I60a592aff0e11b8392a074348688c998e3117265 Signed-off-by: José Bollo <jose.bollo@iot.bzh>
-rw-r--r--src/wgt.c178
-rw-r--r--src/wgt.h14
2 files changed, 162 insertions, 30 deletions
diff --git a/src/wgt.c b/src/wgt.c
index db16129..391c361 100644
--- a/src/wgt.c
+++ b/src/wgt.c
@@ -42,8 +42,12 @@ struct wgt {
static int validsubpath(const char *subpath)
{
int l = 0, i = 0;
+
+ /* absolute path is not valid */
if (subpath[i] == '/')
return 0;
+
+ /* inspect the path */
while(subpath[i]) {
switch(subpath[i++]) {
case '.':
@@ -75,6 +79,14 @@ static int validsubpath(const char *subpath)
return l >= 0;
}
+/*
+ * Normalizes and checks the 'subpath'.
+ * Removes any starting '/' and checks that 'subpath'
+ * does not contains sequence of '..' going deeper than
+ * root.
+ * Returns the normalized subpath or NULL in case of
+ * invalid subpath.
+ */
static const char *normalsubpath(const char *subpath)
{
while(*subpath == '/')
@@ -82,6 +94,10 @@ static const char *normalsubpath(const char *subpath)
return validsubpath(subpath) ? subpath : NULL;
}
+/*
+ * Creates a wgt handler and returns it or return NULL
+ * in case of memory depletion.
+ */
struct wgt *wgt_create()
{
struct wgt *wgt = malloc(sizeof * wgt);
@@ -96,27 +112,19 @@ struct wgt *wgt_create()
return wgt;
}
-void wgt_disconnect(struct wgt *wgt)
-{
- assert(wgt);
- if (wgt->rootfd >= 0)
- close(wgt->rootfd);
- wgt->rootfd = -1;
-}
-
-void wgt_locales_reset(struct wgt *wgt)
-{
- assert(wgt);
- while(wgt->nrlocales)
- free(wgt->locales[--wgt->nrlocales]);
-}
-
+/*
+ * Adds a reference to 'wgt'
+ */
void wgt_addref(struct wgt *wgt)
{
assert(wgt);
wgt->refcount++;
}
+/*
+ * Drops a reference to 'wgt' and destroys it
+ * if not more referenced
+ */
void wgt_unref(struct wgt *wgt)
{
assert(wgt);
@@ -128,6 +136,41 @@ void wgt_unref(struct wgt *wgt)
}
}
+/*
+ * Creates a wgt handle and connect it to 'dirfd' and 'pathname'.
+ *
+ * Returns the created and connected wgt handle on success
+ * or returns NULL if allocation failed or connecting had
+ * error.
+ */
+struct wgt *wgt_createat(int dirfd, const char *pathname)
+{
+ struct wgt *wgt = wgt_create();
+ if (wgt) {
+ if (wgt_connectat(wgt, dirfd, pathname)) {
+ wgt_unref(wgt);
+ wgt = NULL;
+ }
+ }
+ return wgt;
+}
+
+/*
+ * Connect 'wgt' to the directory of 'pathname' relative
+ * to the directory handled by 'dirfd'.
+ *
+ * Use AT_FDCWD for connecting relatively to the current directory.
+ *
+ * Use 'pathname' == NULL or "" for connecting to 'dirfd'. In
+ * that case, 'dirfd' is duplicated and can safely be used later
+ * by the client.
+ *
+ * If 'wgt' is already connected, it will be diconnected before.
+ *
+ * The languages settings are not changed.
+ *
+ * Returns 0 in case of success or -1 in case or error.
+ */
int wgt_connectat(struct wgt *wgt, int dirfd, const char *pathname)
{
int rfd;
@@ -144,29 +187,46 @@ int wgt_connectat(struct wgt *wgt, int dirfd, const char *pathname)
return 0;
}
+/*
+ * Connect 'wgt' to the directory of 'pathname'.
+ *
+ * Acts like wgt_connectat(wgt, AT_FDCWD, pathname)
+ */
int wgt_connect(struct wgt *wgt, const char *pathname)
{
return wgt_connectat(wgt, AT_FDCWD, pathname);
}
-struct wgt *wgt_createat(int dirfd, const char *pathname)
+/*
+ * Disconnetcs 'wgt' if connected.
+ */
+void wgt_disconnect(struct wgt *wgt)
{
- struct wgt *wgt = wgt_create();
- if (wgt) {
- if (wgt_connectat(wgt, dirfd, pathname)) {
- wgt_unref(wgt);
- wgt = NULL;
- }
- }
- return wgt;
+ assert(wgt);
+ if (wgt->rootfd >= 0)
+ close(wgt->rootfd);
+ wgt->rootfd = -1;
}
+/*
+ * Checks if 'wgt' is connected and returns 1 if connected
+ * or 0 if not connected.
+ */
int wgt_is_connected(struct wgt *wgt)
{
assert(wgt);
return wgt->rootfd != -1;
}
+/*
+ * Tests wether the connected 'wgt' has the 'filename'.
+ *
+ * It is an error (with errno = EINVAL) to test an
+ * invalid filename.
+ *
+ * Returns 0 if it hasn't it, 1 if it has it or
+ * -1 if an error occured.
+ */
int wgt_has(struct wgt *wgt, const char *filename)
{
assert(wgt);
@@ -180,6 +240,12 @@ int wgt_has(struct wgt *wgt, const char *filename)
return 0 == faccessat(wgt->rootfd, filename, F_OK, 0);
}
+/*
+ * Opens 'filename' for read from the connected 'wgt'.
+ *
+ * Returns the file descriptor as returned by openat
+ * system call or -1 in case of error.
+ */
int wgt_open_read(struct wgt *wgt, const char *filename)
{
assert(wgt);
@@ -192,6 +258,10 @@ int wgt_open_read(struct wgt *wgt, const char *filename)
return openat(wgt->rootfd, filename, O_RDONLY);
}
+/*
+ * Adds if needed the locale 'locstr' of 'length'
+ * to the list of locales.
+ */
static int locadd(struct wgt *wgt, const char *locstr, int length)
{
int i;
@@ -199,14 +269,18 @@ static int locadd(struct wgt *wgt, const char *locstr, int length)
item = strndup(locstr, length);
if (item != NULL) {
+ /* normalize in lower case */
for (i = 0 ; item[i] ; i++)
item[i] = tolower(item[i]);
+
+ /* search it (no duplication) */
for (i = 0 ; i < wgt->nrlocales ; i++)
if (!strcmp(item, wgt->locales[i])) {
free(item);
return 0;
}
+ /* append it to the list */
ptr = realloc(wgt->locales, (1 + wgt->nrlocales) * sizeof(wgt->locales[0]));
if (ptr) {
wgt->locales = ptr;
@@ -219,13 +293,35 @@ static int locadd(struct wgt *wgt, const char *locstr, int length)
return -1;
}
+/*
+ * clears the list of locales of 'wgt'
+ */
+void wgt_locales_reset(struct wgt *wgt)
+{
+ assert(wgt);
+ while(wgt->nrlocales)
+ free(wgt->locales[--wgt->nrlocales]);
+}
+
+/*
+ * Adds to 'wgt' the locales defined by 'locstr'.
+ *
+ * Example: passing "fr-CH,en-GB" will add "fr-CH",
+ * "fr", "en-GB" and then "en" to the list of locales.
+ *
+ * Returns 0 in case of success or -1 in case of memory
+ * depletion.
+ */
int wgt_locales_add(struct wgt *wgt, const char *locstr)
{
const char *stop, *next;
assert(wgt);
+
+ /* iterate the comma separated languages */
while (*locstr) {
stop = strchrnul(locstr, ',');
next = stop + !!*stop;
+ /* iterate variant of languages in reverse order */
while (locstr != stop) {
if (locadd(wgt, locstr, stop - locstr))
return -1;
@@ -236,6 +332,12 @@ int wgt_locales_add(struct wgt *wgt, const char *locstr)
return 0;
}
+/*
+ * Get the score of the language 'lang' for 'wgt'.
+ *
+ * The lower result means the higher priority of the language.
+ * The returned value of 0 is the top first priority.
+ */
int wgt_locales_score(struct wgt *wgt, const char *lang)
{
int i;
@@ -249,15 +351,26 @@ int wgt_locales_score(struct wgt *wgt, const char *lang)
return INT_MAX;
}
+/*
+ * Applies the localisation algorithm of 'filename'
+ * within 'wgt'. Use the scratch buffer given by 'path'.
+ *
+ * Returns the filepath of the located file or NULL
+ * if not found. If not NULL, the returned value is either
+ * 'path' or the normalized version of 'filename'.
+ */
static const char *localize(struct wgt *wgt, const char *filename, char path[PATH_MAX])
{
int i;
+ /* get the normalized name */
filename = normalsubpath(filename);
if (!filename) {
errno = EINVAL;
return NULL;
}
+
+ /* search in locales */
for (i = 0 ; i < wgt->nrlocales ; i++) {
if (snprintf(path, PATH_MAX, "locales/%s/%s", wgt->locales[i], filename) >= PATH_MAX) {
errno = EINVAL;
@@ -272,6 +385,13 @@ static const char *localize(struct wgt *wgt, const char *filename, char path[PAT
return NULL;
}
+/*
+ * Gets the localized file of 'filename' within 'wgt'.
+ *
+ * Returns a fresh allocated string for the found 'filename'.
+ * Returns NULL if file is not found (ENOENT) or memory
+ * exhausted (ENOMEM).
+ */
char *wgt_locales_locate(struct wgt *wgt, const char *filename)
{
char path[PATH_MAX];
@@ -280,6 +400,7 @@ char *wgt_locales_locate(struct wgt *wgt, const char *filename)
assert(wgt);
assert(wgt_is_connected(wgt));
+
loc = localize(wgt, filename, path);
if (!loc)
result = NULL;
@@ -291,7 +412,13 @@ char *wgt_locales_locate(struct wgt *wgt, const char *filename)
return result;
}
-
+/*
+ * Opens for read the localized version of 'filename'
+ * from the connected 'wgt'.
+ *
+ * Returns the file descriptor as returned by openat
+ * system call or -1 in case of error.
+ */
int wgt_locales_open_read(struct wgt *wgt, const char *filename)
{
char path[PATH_MAX];
@@ -299,6 +426,7 @@ int wgt_locales_open_read(struct wgt *wgt, const char *filename)
assert(wgt);
assert(wgt_is_connected(wgt));
+
loc = localize(wgt, filename, path);
if (!loc)
return -1;
diff --git a/src/wgt.h b/src/wgt.h
index bd8c428..82ad4db 100644
--- a/src/wgt.h
+++ b/src/wgt.h
@@ -18,24 +18,28 @@
struct wgt;
+/* creation and reference */
extern struct wgt *wgt_create();
-extern struct wgt *wgt_createat(int dirfd, const char *pathname);
-
extern void wgt_addref(struct wgt *wgt);
extern void wgt_unref(struct wgt *wgt);
+/* connection and disconnection */
+extern struct wgt *wgt_createat(int dirfd, const char *pathname);
extern int wgt_connect(struct wgt *wgt, const char *pathname);
extern int wgt_connectat(struct wgt *wgt, int dirfd, const char *pathname);
extern void wgt_disconnect(struct wgt *wgt);
extern int wgt_is_connected(struct wgt *wgt);
-extern int wgt_has(struct wgt *wgt, const char *filename);
-extern int wgt_open_read(struct wgt *wgt, const char *filename);
-
+/* management of locales */
extern void wgt_locales_reset(struct wgt *wgt);
extern int wgt_locales_add(struct wgt *wgt, const char *locstr);
extern int wgt_locales_score(struct wgt *wgt, const char *lang);
+/* direct access to files */
+extern int wgt_has(struct wgt *wgt, const char *filename);
+extern int wgt_open_read(struct wgt *wgt, const char *filename);
+
+/* localised access to files */
extern char *wgt_locales_locate(struct wgt *wgt, const char *filename);
extern int wgt_locales_open_read(struct wgt *wgt, const char *filename);