From 8ae0c6d9b4cc7ee47f5fdaf4edc7019d988b7775 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vivek=20Das=C2=A0Mohapatra?= <vivek@collabora.co.uk> Date: Sat, 22 Jul 2017 00:30:58 +0100 Subject: [PATCH] Document everything in capsule.h with gtk-doc comments --- capsule/capsule.h | 64 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/capsule/capsule.h b/capsule/capsule.h index 81c595944..0e768857c 100644 --- a/capsule/capsule.h +++ b/capsule/capsule.h @@ -19,6 +19,21 @@ #include <link.h> +/** + * capsule_item_t: + * @name: The name of the symbol to be relocated + * @shim: address of the ‘fake’ symbol in the proxy library + * @real: address of the ‘real’ symbol in the target library + * + * @shim may typically be left empty in calls to capsule_dlmopen() + * and capsule_relocate(). + * + * @real may also be left empty in calls to capsule_relocate() + * + * Both slots will typically hold the correct values after a successful + * capsule… call. While this is sometimes important internally it is + * not usually of interest to the caller (except maybe for debugging) + */ typedef struct { const char *name; @@ -35,6 +50,27 @@ typedef struct */ void capsule_init (void); +/** + * capsule_relocate: + * @target: The DSO from which to export symbols (currently unused) + * @source: The dl handle from which to export symbols + * @debug: Internal debug flag. Pass 0 here. + * @relocations: Array of capsule_item_t specifying which symbols to export + * @error: location in which to store an error string on failure + * + * Returns: 0 on success, non-zero on failure. + * + * @source is typically the value returned by a successful capsule_dlmopen() + * call (although a handle returned by dlmopen() would also be reasonable). + * + * The #capsule_item_t entries in @relocations need only specify the symbol + * name: The shim and real fields will be populated automatically if they + * are not pre-filled (this is the normal use case, as it would be unusual + * to know these value in advance). + * + * In the unlikely event that an error message is returned in @error it is the + * caller's responsibility to free() it. + */ int capsule_relocate (const char *target, void *source, unsigned long debug, @@ -52,6 +88,8 @@ int capsule_relocate (const char *target, * @errcode: location in which to store the error code on failure * @error: location in which to store an error message on failure * + * Returns: A (void *) DSO handle, as per dlopen(3), or %NULL on error + * * Opens @dso (a library) from a filesystem mounted at @prefix into a * symbol namespace specified by @namespace, using dlmopen(). * @@ -85,6 +123,32 @@ void *capsule_dlmopen (const char *dso, int *errcode, char **error); +/** + * capsule_shim_dlopen: + * @ns: An #Lmid_t value giving the namespace in which to operate + * @prefix: the mount point of the foreign tree in wich to find DSOs + * @exclude: Array of DSO names to ignore + * @file: base name of the target DSO (eg libz.so.1) + * @flag: dlopen() flags to pass to the real dlmopen() call + * + * Returns: a void * dl handle (cf dlopen()) + * + * This helper function exists because dlopen() cannot safely be called + * by a DSO opened into a private namespace. It takes @file and @flag + * arguments (cf dlopen()) and @prefix, @exclude, and @namespace arguments + * (cf capsule_dlmopen(), although namespace is an #Lmid_t and not a pointer + * to one as in capsule_dlmopen()) and performs a safe dlmopen() call instead, + * respecting the same restrictions as capsule_dlmopen(). + * + * Typically this function is used to implement a safe wrapper for dlopen() + * which is passed via the wrappers argument to capsule_dlmopen(). This + * replaces calls to dlopen() by all DSOs in the capsule produced by + * capsule_dlmopen(), allowing libraries which use dlopen() to work inside + * the capsule. + * + * Limitations: RTLD_GLOBAL is not supported in @flag. This is a glibc + * limitation in the dlmopen() implementation. + */ void *capsule_shim_dlopen(Lmid_t ns, const char *prefix, const char **exclude, -- GitLab