[Pkg-privacy-commits] [libgsecuredelete] 35/168: Improved documentation.
Ulrike Uhlig
u-guest at moszumanska.debian.org
Thu Jul 7 20:06:35 UTC 2016
This is an automated email from the git hooks/post-receive script.
u-guest pushed a commit to branch master
in repository libgsecuredelete.
commit 7909426a3e7534772f4a14efecd48a37b87967d1
Author: Colomban Wendling <ban at herbesfolles.org>
Date: Wed Oct 7 15:19:22 2009 +0200
Improved documentation.
---
HACKING | 30 ++++++++++++++++++++++++++++++
gsecuredelete/async-operation.vala | 27 +++++++++++++++++++++++----
gsecuredelete/delete-operation.vala | 24 +++++++++++++++++++++---
gsecuredelete/fill-operation.vala | 8 ++++++--
gsecuredelete/mem-operation.vala | 4 ++++
gsecuredelete/securedelete-operation.vala | 14 +++++++++-----
gsecuredelete/swap-operation.vala | 10 +++++++---
gsecuredelete/utils.vala | 6 ++++--
8 files changed, 104 insertions(+), 19 deletions(-)
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..52ba2b0
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,30 @@
+= File & directory content
+
+* gsecuredelete/
+ Contains the source code of the library.
+
+ * utils.vala:
+ Gneral use utilities.
+ * async-operation.vala:
+ The base class for manage (swpawn and watch) the subptocesses.
+ * securedelete-operation.vala:
+ Base class for all operations. It is a subclass of AsyncOperation and
+ it implements all generic stuff for all S* oeprations.
+ * zeroable-operation.vala:
+ A superclass of SecureDeleteOperation that implements the -z option
+ that is common for almost all S* operation but not all.
+ * delete-operation.vala:
+ Implements the wrapper for `srm`
+ * fill-operation.vala:
+ Implements the wrapper for `sfill`
+ * mem-operation.vala:
+ Implements the wrapper for `smem`
+ * swap-operation.vala:
+ Implements the wrapper for `sswap`
+ * main.vala:
+ A test application for the operations. It is not actual part of the
+ library.
+
+= Coding style
+
+Watch the code and see!
diff --git a/gsecuredelete/async-operation.vala b/gsecuredelete/async-operation.vala
index 3ffabc1..b77ce02 100644
--- a/gsecuredelete/async-operation.vala
+++ b/gsecuredelete/async-operation.vala
@@ -111,12 +111,27 @@ namespace Gsd
protected int fd_err;
/* signals */
+ /** AsyncOperation::finished:
+ * @success: whether the operation succeed.
+ * @message: if the operation failed, contains the error message.
+ *
+ * This signal is emitted when the operation just terminated.
+ */
public signal void finished (bool success,
string? message);
+ /** AsyncOperation::progress:
+ * @fraction: the current progress, from 0.0 to 1.0.
+ *
+ * This signal is emitted when the progress status of the operation changes.
+ */
public signal void progress (double fraction);
/* properties */
- /* whether the operation object is busy */
+ /** AsyncOperation: busy:
+ * Whether the operation object is busy. A busy operation cannot be reused
+ * until it gets ready again. An operation is busy when it is currently
+ * doing a job.
+ */
public bool busy {
public get;
protected set;
@@ -172,13 +187,16 @@ namespace Gsd
/* gets the additional progress status of the child process.
* This function gets called from time to time to get the new additional
* progress of the operation, since last call.
+ * Then, the combination of the returned values of repeated calls to this
+ * function should be equal to the value returned by get_max_progress() in
+ * order to report a meaningful progress status.
*/
protected virtual uint get_progress ()
{
return 0;
}
- /* updates the progress status and emit DeleteOperation::progress if
+ /* updates the progress status and emit AsyncOperation::progress if
* changed */
private void update_progress ()
{
@@ -189,7 +207,7 @@ namespace Gsd
}
}
- /* checks if the child finished, and disatches related things.
+ /* checks if the child finished, and dispatches related things.
*
* It is meant to be called as a timeout function.
*/
@@ -202,7 +220,8 @@ namespace Gsd
string? message = null;
/* FIXME: 1 = WNOHANG, but WNOHANG doesn't seems to be accessible from
- * Vala */
+ * Vala at the moment (0.7.7).
+ * See https://bugzilla.gnome.org/show_bug.cgi?id=597020 */
wait_rv = Posix.waitpid ((Posix.pid_t)this.pid, out exit_status, 1);
if ((int)wait_rv < 0) {
critical ("waitpid() failed: %s", strerror (errno));
diff --git a/gsecuredelete/delete-operation.vala b/gsecuredelete/delete-operation.vala
index 9d55403..419efc7 100644
--- a/gsecuredelete/delete-operation.vala
+++ b/gsecuredelete/delete-operation.vala
@@ -21,9 +21,13 @@ using GLib;
namespace Gsd
{
+ /** DeleteOperation:
+ *
+ * Wrapper for `srm`.
+ */
public class DeleteOperation : ZeroableOperation
{
- private List<string> _paths;
+ private List<string> _paths; /* the list of paths to remove */
private uint n_files = 0;
/* properties */
@@ -34,14 +38,28 @@ namespace Gsd
}
}
- /* adds a path to the list of paths to remove */
+ /** add_path:
+ * @path: a path to securely remove.
+ *
+ * Adds a path to the list of paths to remove.
+ */
public void add_path (string path)
requires (! this.busy)
{
this._paths.append (path);
}
- /* removes a path from the list of paths to remove */
+ /** remove_path:
+ * @path: a path already added you don't want to remove.
+ *
+ * Removes a path from the list of paths to remove.
+ * <warning>
+ * This is NOT a filter for files not to remove! It only remove a path
+ * previously added with add_path() from the list of paths to remove, it
+ * does not prevent removing of a path if the directory containing it is
+ * in the list of paths to remove.
+ * </warning>
+ */
public void remove_path (string path)
requires (! this.busy)
{
diff --git a/gsecuredelete/fill-operation.vala b/gsecuredelete/fill-operation.vala
index 56b1edc..dbc929d 100644
--- a/gsecuredelete/fill-operation.vala
+++ b/gsecuredelete/fill-operation.vala
@@ -19,6 +19,10 @@
namespace Gsd
{
+ /** FillOperation:
+ *
+ * Wrapper for `sfill`.
+ */
public class FillOperation : ZeroableOperation
{
/**
@@ -47,7 +51,7 @@ namespace Gsd
* I recommend you not to fill in a useful directory but inside a new and
* clean one. This can be useful if the filling is interrupted, voluntarily
* or not, as this process may spawn a lot of files that might not be
- * deleted.
+ * deleted when interrupted.
*/
public string directory {
get;
@@ -55,7 +59,7 @@ namespace Gsd
default = null;
}
- /* returns the argument needed for the a wipe mode */
+ /* returns the argument needed for a wipe mode */
private unowned string? get_argument_for_wipe_mode (WipeMode wipe_mode)
{
switch (wipe_mode) {
diff --git a/gsecuredelete/mem-operation.vala b/gsecuredelete/mem-operation.vala
index 93e6e09..979b19f 100644
--- a/gsecuredelete/mem-operation.vala
+++ b/gsecuredelete/mem-operation.vala
@@ -24,6 +24,10 @@ namespace Gsd
* * test
*/
+ /** MemOperation:
+ *
+ * Wrapper for `smem`.
+ */
public class MemOperation : SecureDeleteOperation
{
/* builds the argument vector */
diff --git a/gsecuredelete/securedelete-operation.vala b/gsecuredelete/securedelete-operation.vala
index 66523ec..e4940a7 100644
--- a/gsecuredelete/securedelete-operation.vala
+++ b/gsecuredelete/securedelete-operation.vala
@@ -21,7 +21,10 @@ using GLib;
namespace Gsd
{
-
+ /* FIXME: do NOT use SEACH_PATH but rather give an absolute path, because
+ * using the search path is everything but secure: if the process calling
+ * this have privileges, and a malicious user tweaked the PATH to make another
+ * program being called, this may lead to GRAVE problems. */
/**
* SecureDeleteOperation:
*
@@ -34,11 +37,11 @@ namespace Gsd
/**
* Mode:
*
- * Secure mode:
+ * Security mode:
* @NORMAL: normal mode
* @FAST: faster but less secure (correspond to the -f option)
- * @VERY_FAST: really faster but with a very poor security
- * @VERY_VERY_FAST: even more faster, even less secure
+ * @VERY_FAST: really faster but with a very poor security (-l option)
+ * @VERY_VERY_FAST: even more faster, even less secure (-ll option)
*/
public enum Mode {
NORMAL,
@@ -79,6 +82,7 @@ namespace Gsd
}
}
+ /* returns the supposed number of pass to show the progress status */
protected override uint get_max_progress ()
{
/* FIXME: Get the pass number reported by the program? */
@@ -109,7 +113,7 @@ namespace Gsd
/** run_sync:
* Runs a SecureDelete operator asynchronously.
*
- * Returns: whether subprocess started successfully.
+ * Returns: whether operation started successfully.
*/
public new bool run (uint watch_interval = 100)
throws SpawnError, AsyncOperationError
diff --git a/gsecuredelete/swap-operation.vala b/gsecuredelete/swap-operation.vala
index aff5a2f..21316ba 100644
--- a/gsecuredelete/swap-operation.vala
+++ b/gsecuredelete/swap-operation.vala
@@ -19,10 +19,14 @@
namespace Gsd
{
+ /** SwapOperation:
+ *
+ * Wrapper for `sswap`.
+ */
public class SwapOperation : ZeroableOperation
{
/** SwapOperation:device:
- * The swap device to wipe
+ * The swap device to wipe.
*/
public string device {
get;
@@ -32,8 +36,8 @@ namespace Gsd
/**
* Whether to throw an error if the swap is detected as being currently
* used.
- * This may be useless as doing the operation on a in-use swap may crash the
- * system.
+ * This may be useful because doing the operation on a in-use swap may crash
+ * the system.
*/
public bool check_device {
get;
diff --git a/gsecuredelete/utils.vala b/gsecuredelete/utils.vala
index 598d795..01fc4c4 100644
--- a/gsecuredelete/utils.vala
+++ b/gsecuredelete/utils.vala
@@ -45,6 +45,7 @@ namespace Gsd
if (fd > 0) {
Posix.fd_set rfds = {};
+ /* FIXME: is waiting 0ms a portable thing not for blocking? */
Posix.timeval tv = {0, 0};
Posix.FD_ZERO (rfds);
@@ -65,7 +66,8 @@ namespace Gsd
* @fd: a file descriptor
* @n_bytes: number of bytes to read from @fd, or -1 to read all @fd
*
- * Reads content of a file as a C string (0-terminated).
+ * Reads content of a file as a string.
+ * This function may only work with text data.
*
* Returns: a newly allocated string containing data in @fd.
*/
@@ -123,7 +125,7 @@ namespace Gsd
return (string?) (owned) buf;
}
- /* counts the number of occurrence a given byte in a file descriptor.
+ /* Counts the number of occurrence of a given byte in a file descriptor.
* This function is non-blocking and returns 0 if there is no
* data in the buffer rather than blocking waiting for data to read. */
public uint count_ready_bytes (int fd,
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/libgsecuredelete.git
More information about the Pkg-privacy-commits
mailing list