Merge remote-tracking branch 'flubber/master'

7 files changed, 700 insertions, 0 deletions

diff --git a/user/tlecarrour/auto-apt.mdwn b/user/tlecarrour/auto-apt.mdwn
new file mode 100644
index 00000000..6a5adb80
--- /dev/null
+++ b/user/tlecarrour/auto-apt.mdwn
@@ -0,0 +1,57 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+auto-apt
+========
+
+When you want to build a program from source and it fails due to missing headers. Auto-apt can search what package would provide the header files.  
+(from [[https://help.ubuntu.com/community/AutoApt]])
+
+
+[[!toc startlevel=2]]
+
+
+* * *
+
+
+Log
+---
+
+* **Started**: 2012-01-24
+* **Discussed**: [2012-01-26](http://lists.debian.org/debian-hurd/2012/01/msg00129.html)
+* **Draft Submitted**: -
+* **Submitted**: -
+* **Accepted**: -
+
+
+* * *
+
+
+ToDo
+----
+
+The output of `grep -R PATH_MAX auto-apt-0.3.22/*` is a bit long. It contains files that have been patched using `#define PATH_MAX XYZ`.  
+Here is the only file of interest:
+
+    pkgcdb/pkgtab.c:    char buf[PATH_MAX];
+    pkgcdb/pkgtab.c:    assert(p - pkg < PATH_MAX);
+    pkgcdb/pkgtab.c:    static char buf[PATH_MAX];
+    pkgcdb/pkgtab.c:    assert(len < PATH_MAX);
+
+
+* * *
+
+
+Comments
+--------
+
+Work in progress, see related [thread](http://lists.debian.org/debian-hurd/2012/01/msg00129.html).
+
diff --git a/user/tlecarrour/memstat.mdwn b/user/tlecarrour/memstat.mdwn
new file mode 100644
index 00000000..7e090c8c
--- /dev/null
+++ b/user/tlecarrour/memstat.mdwn
@@ -0,0 +1,162 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+memstat
+=======
+
+Lists all the processes, executables, and shared libraries that are using up virtual memory. It's helpful to see how the shared memory is used and which 'old' libs are loaded.  
+**Home page**: [[http://sourceforge.net/projects/memstattool]]
+
+[[!toc startlevel=2]]
+
+
+* * *
+
+
+Log
+---
+
+* **Started**: 2012-01-20
+* **Discussed**: [2012-01-21](http://lists.debian.org/debian-hurd/2012/01/msg00081.html)
+* **Draft Submitted**: [2012-01-25](http://lists.debian.org/debian-hurd/2012/01/msg00122.html)
+* **Submitted**: 2012-02-02, Bug#[658384](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=658384)
+* **Accepted**: -
+
+
+* * *
+
+
+ToDo
+----
+
+Here is the output of `grep -R PATH_MAX memstat-0.9/*`:
+
+    memstat.c:    char *p, major[8], minor[8], buff[PATH_MAX + 300], *path, perm[4];
+    memstat.c:    char linkname[PATH_MAX], filename[PATH_MAX];
+    memstat.c:    if ((len = readlink(filename, linkname, PATH_MAX)) == -1) {
+
+
+* * *
+
+
+Comments
+--------
+
+Here are comments on the patch...
+
+    +#define FMT_PROC_MAPS "/proc/%d/maps"
+    +#define FMT_PROC_EXE  "/proc/%d/exe"
+
+Define string formats.
+
+     static void read_proc(void)
+     {
+         unsigned int nread, pid;
+         unsigned long inode, lo, hi, offs;
+    -    char *p, major[8], minor[8], buff[PATH_MAX + 300], *path, perm[4];
+    +    char *p, major[8], minor[8], *path, perm[4];
+    +    char *buff = NULL;
+    +    size_t buff_size = 0;
+
+In this function we turn `buff` into dynamically allocated string.
+
+
+    -   sprintf(buff, "/proc/%d/maps", pid);
+    -   f = fopen(buff, "r");
+    +   char filename[sizeof(FMT_PROC_MAPS) + (sizeof(int) * 3) + 1];
+    +   sprintf(filename, FMT_PROC_MAPS, pid);
+    +   f = fopen(filename, "r");
+
+Compute the maximum size of `filename` using `sizeof(int) * 3` as explainend in the [[porting guide|porting_guide_for_dummies]].
+
+
+    -   while (fgets(buff, sizeof(buff), f)) {
+    +   while (!feof(f)) {
+    +       buff = get_line(f);
+    +       if (buff == NULL)
+    +       break;
+
+Read a line from the file using [[get_line()|porting_guide_for_dummies]].
+
+
+    -       if ((strlen(buff) == 10) && (strcmp(buff, " (deleted)") == 0))
+    +       if ((strlen(buff) == 10) && (strcmp(buff, " (deleted)") == 0)) {
+    +       free(buff);
+            continue;
+    +       }
+            nread = sscanf(buff, "%lx %lx %4s %lx %s %s %lu %as", &lo, &hi, perm, &offs, major, minor, &inode, &path);
+    +       free(buff);
+
+Free the `buff` when it's not used anymore.
+
+
+    +       buff_size = 4; /* size of the format string without "%x" expressions */
+    +       buff_size += strlen(major);
+    +       buff_size += strlen(minor);
+    +       buff_size += sizeof(int) * 3 + 1; /* inode */
+    +       buff_size += 1; /* '\0' */
+    +       buff = malloc(buff_size);
+    +       if (buff == NULL) {
+    +           perror("Cannot allocate memory!");
+    +           exit(1);
+    +       }
+
+Compute the size that the `buff` must have.
+
+
+    -   char linkname[PATH_MAX], filename[PATH_MAX];
+    -   ssize_t len;
+    +   char *linkname = NULL;
+    +   struct stat sb;
+    +   ssize_t len = -1;
+
+In this function we turn linkname into dynamically allocated string. 
+filename will be declared later.
+
+
+    -   sprintf(filename, "/proc/%d/exe", pid);
+    -   if ((len = readlink(filename, linkname, PATH_MAX)) == -1) {
+    +   char filename[sizeof(FMT_PROC_EXE) + (sizeof(int) * 3) + 1];
+    +   sprintf(filename, FMT_PROC_EXE, pid);
+
+Same as above with `FMT_PROC_MAPS`.
+
+
+    +   if (lstat(filename, &sb) == -1) {
+    +       perror("lstat");
+    +       deleted = 1;
+    +   }
+    +   else {
+    +       linkname = malloc(sb.st_size + 1);
+    +       if (linkname == NULL) {
+    +       fprintf(stderr, "insufficient memory\n");
+    +       deleted = 1;
+    +       }
+    +       else {
+    +       len = readlink(filename, linkname, sb.st_size + 1);
+    +       }
+    +   }
+    +   if (len < 0 || len > sb.st_size) {
+            fprintf(stderr, "Cannot read link information for %s\n", filename);
+            deleted = 1;
+        }
+    -   linkname[len] = '\0';
+    +   else {
+    +       linkname[sb.st_size] = '\0';
+    +   }
+
+Use `readlink()` as explained in the porting guide. 
+Require lstat to get the link size.
+
+
+    +   free(linkname);
+Free dynamically allocated variable that is not used anymore.
+
diff --git a/user/tlecarrour/patch_life_cycle.mdwn b/user/tlecarrour/patch_life_cycle.mdwn
new file mode 100644
index 00000000..574317af
--- /dev/null
+++ b/user/tlecarrour/patch_life_cycle.mdwn
@@ -0,0 +1,89 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+Patch Life Cycle
+================
+
+[[!toc startlevel=2]]
+
+
+* * *
+
+
+Start
+-----
+
+Follow the steps listed on the [[package porting page|porting_guide_for_dummies]].
+
+
+Discuss
+-------
+
+Send the patch for review to [debian-hurd@lists.debian.org](mailto:debian-hurd@lists.debian.org).  
+**Before** sending the patch, make sure that you've solved all the known problems listed in the [[package porting general introduction|hurd/porting/guidelines]] 
+and the [[porting guide for dummies|porting_guide_for_dummies]].
+
+
+Submit Draft
+------------
+
+When the patch is good enough, you can write the draft of the official bug report.  
+This draft should first be sent for review to [debian-hurd@lists.debian.org](mailto:debian-hurd@lists.debian.org) with the patch attached.
+
+Here is an example for memstat:
+
+    Source: memstat
+    Version: 0.9
+    Severity: important
+    Tags: patch
+    User: debian-hurd@lists.debian.org
+    Usertags: hurd
+    X-DebBugs-CC: debian-hurd@lists.debian.org
+
+    Hi,
+
+    This patch solves the build problems for GNU/Hurd due to PATH_MAX
+    issues. The solution is to make dynamic string allocations instead of
+    using fixed length buffers. The patch involves one file, and is
+    trivial. Parts of the the code has been reviewed by GNU/Hurd developers
+    and Debian GNU/Hurd developers and maintainers.
+
+    FIXME:
+    Is it really useful to check if BUFSIZ is defined?
+
+    TODO:
+    Should the "whole package" be tested with valgrind on GNU/Linux?!
+    If yes, is there a standard procedure to do it?!
+
+    Thanks! 
+    Special thanks to Jérémie and Richard for their comments!
+
+    (Not submitted yet, comments are welcome.)
+
+Once it's been approved, you can proceed to the submission.
+
+
+Submit
+------
+
+The bug report is the same as above, with all the **FIXME**, **TODO** and final comment removed.  
+Attach the patch and send it to [submit@bugs.debian.org](mailto:submit@bugs.debian.org).  
+Convention for the attachment name is: `fix_FTBFS4Hurd.patch`
+
+
+Accept
+------
+
+Once the patch has been accepted, update your patch page!  
+**Congratulations!**
+
+
+
diff --git a/user/tlecarrour/porting_guide_for_dummies.mdwn b/user/tlecarrour/porting_guide_for_dummies.mdwn
new file mode 100644
index 00000000..749344fd
--- /dev/null
+++ b/user/tlecarrour/porting_guide_for_dummies.mdwn
@@ -0,0 +1,203 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+Porting Guide for Dummies
+=========================
+
+The problems addressed here were encountered while working 
+on fixing **PATH_MAX** and **MAXPATHLEN**.
+
+[[!toc startlevel=2 levels=3]]
+
+
+* * *
+
+
+Test on Hurd
+------------
+
+
+### Installing the required files
+
+As `apt-get source` will download and extract many files, you may want to create a dedicated folder for the package and work from there.
+
+    mkdir PACKAGE
+    cd PACKAGE
+    sudo apt-get build-dep PACKAGE
+    apt-get source PACKAGE
+
+
+### Trying to build the package
+
+    cd PACKAGE_SOURCE
+    dpkg-buildpackage -us -uc -rfakeroot -tc
+
+
+### Test a quick fix
+
+In all the files that use **PATH_MAX**, include those lines at the beginning.
+
+    #ifndef PATH_MAX
+    #define PATH_MAX 4196
+    #endif
+
+Try to rebuild the package and see if it's solved the problem.  
+If yes, you can start working on the package.
+
+
+* * *
+
+
+Basic things
+------------
+
+### Maintaining a original version
+
+    mkdir old
+    cp -r PACKAGE_SOURCE old/
+
+
+### Coding style
+
+Follow the conventions used in the source code!
+
+    if (condition) {
+        do_smthg();
+    }
+
+is not the same as:
+
+    if (condition) 
+    {
+        do_smthg();
+    }
+
+and is not the same as:
+
+    if (condition)
+        do_smthg();
+
+Pay attention to spaces surrounding, or not, arithmetic signs and symbols:
+
+    a = do_smthg( b + c );
+    a = do_smthg(b+c);
+
+
+### Indentation
+
+By default use 8 spaces as the size for 1 tab. 
+Then figure out if the code uses tab + 1/2 tab:
+
+    ....if (condition) {
+    ------->do_smthg();
+    ....}
+
+or tab only:
+
+    ------->if (condition) {
+    ------->------->do_smthg();
+    ------->}
+
+
+### Creating a patch
+
+    diff -Naur old/PACKAGE-VERSION PACKAGE-VERSION > fix_FTBFS4Hurd.patch
+
+
+* * *
+
+
+Known problems
+--------------
+
+### Dynamically allocated buffer returned by a function
+
+Use a static buffer
+
+### Buffer used to format an expression containing an INTEGER
+
+The length of an INTEGER in a string can be up to sizeof (int) * 3 + 1.
+
+> The usual trick for "%d" is to use the constant 'sizeof (int) * 3 + 1'. 
+I included + 1 for the sign, but it's not really necessary 
+if we exepect sizeof(int) >= 2, which we probably should. 
+**Jérémie Koenig**
+
+    log(MAX_INT)
+     = log(2 ^ 32)
+     = 32 * log(2)
+     = 4 * 8 * log(2)
+     = sizeof(int) * 2.40823997
+     < sizeof(int) * 3
+
+
+### Proper use of realloc()
+
+use a new_buff to check if everything went fine Free buf if realloc failed (and prog doesn't exit)
+
+
+### Reading lines from file
+
+Function to read line (no size limit, ending with "\n") from a file.
+
+    +static char *get_line(FILE *f)
+    +{
+    +    char *buff  = NULL;
+    +    char *new_buff  = NULL;
+    +    size_t buff_size = 0;
+    +    size_t last = 0;
+    +
+    +    while (!feof(f)) {
+    +   buff_size = buff_size ? buff_size * 2 : BUFSIZ;
+    +   new_buff = realloc(buff, buff_size);
+    +   if (new_buff == NULL) {
+    +       free(buff);
+    +       return NULL;
+    +   }
+    +   buff = new_buff;
+    +   if (fgets(buff + last, buff_size - last, f) == NULL) {
+    +       free(buff);
+    +       return NULL;
+    +   }
+    +   last = strlen(buff);
+    +   if (buff[last - 1] == '\n')
+    +       return buff;
+    +    }
+    +    return buff;
+    +}
+
+
+### Proper use of readlink()
+
+One has to rely on lstat() to get the size of the link that readlink() returns.
+
+Declare what you need:
+
+    char *linkname = NULL;
+    struct stat sb;
+    ssize_t len = -1;
+
+Call lstat() and check return value:
+
+    if (lstat(filename, &sb) == -1) {
+
+Create a buffer of the appropriate size and check the return value:
+
+    linkname = malloc(sb.st_size + 1);
+    if (linkname == NULL) {
+
+Call readlink(), check return value and set the null char in the linkname:
+
+    len = readlink(filename, linkname, sb.st_size + 1);
+    if (len < 0 || len > sb.st_size) {
+    ...
+    linkname[sb.st_size] = '\0';
+
diff --git a/user/tlecarrour/rng-tools.mdwn b/user/tlecarrour/rng-tools.mdwn
new file mode 100644
index 00000000..329852a0
--- /dev/null
+++ b/user/tlecarrour/rng-tools.mdwn
@@ -0,0 +1,56 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+rng-tools
+=========
+
+Daemon to use a Hardware TRNG. The rngd daemon acts as a bridge between a Hardware TRNG (true random number generator) such as the ones in some Intel/AMD/VIA chipsets, and the kernel's PRNG (pseudo-random number generator).  
+(from [[http://packages.debian.org/lenny/rng-tools]])
+
+[[!toc startlevel=2]]
+
+
+* * *
+
+
+Log
+---
+
+* **Started**: 2012-01-28
+* **Discussed**: [2012-01-30](http://lists.debian.org/debian-hurd/2012/01/msg00177.html)
+* **Draft Submitted**: -
+* **Submitted**: -
+* **Accepted**: -
+
+
+* * *
+
+
+ToDo
+----
+
+Here is the output of `grep -R PATH_MAX rng-tools-2-unofficial-mt.14/*`:
+
+    viapadlock_engine.c:static char cpudev_path[PATH_MAX+1];
+    viapadlock_engine.c:char devpath[PATH_MAX+1];
+
+
+* * *
+
+
+Comments
+--------
+
+Work in progress, see related [thread](http://lists.debian.org/debian-hurd/2012/01/msg00177.html).
+
+Even if the **PATH_MAX** can be easily fixed, some problems remain.  
+The code uses `linux/types.h`, that has to be replaced by `sys/types.h`, but also uses `linux/random.h` which has no equivalent I know of.  
+At least one source file is named after the OS: `rngd_linux.c`.
diff --git a/user/tlecarrour/suckless-tools.mdwn b/user/tlecarrour/suckless-tools.mdwn
new file mode 100644
index 00000000..abc89761
--- /dev/null
+++ b/user/tlecarrour/suckless-tools.mdwn
@@ -0,0 +1,79 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+suckless-tools
+==============
+
+Home of dwm, dmenu and other quality software with a focus on simplicity, clarity, and frugality.  
+**Home page**: [[http://suckless.org]]
+
+[[!toc startlevel=2]]
+
+
+* * *
+
+
+Log
+---
+
+* **Started**: 2012-01-31
+* **Discussed**: [2012-01-31](http://lists.debian.org/debian-hurd/2012/01/msg00191.html)
+* **Draft Submitted**: [2012-02-01](http://lists.debian.org/debian-hurd/2012/02/msg00001.html)
+* **Submitted**: 2012-02-02, Bug#[658386](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=658386)
+* **Accepted**: -
+
+
+* * *
+
+
+ToDo
+----
+
+Here is the output of `grep -R PATH_MAX suckless-tools-38/*`:
+
+    dmenu/dmenu_path.c: char buf[PATH_MAX];
+
+
+* * *
+
+
+Comments
+--------
+
+Here are comments on the patch...
+
+     void
+     scan(void) {
+    -   char buf[PATH_MAX];
+    +   char *buf = NULL;
+    +   char *new_buf = NULL;
+    +   size_t buf_size = 0;
+
+In this function we turn `buf` into dynamically allocated string.
+
+
+            while((ent = readdir(dp))) {
+    +           buf_size = strlen(dir)+strlen(ent->d_name)+2;
+    +           if(!buf || strlen(buf) < buf_size) {
+    +               new_buf = realloc(buf, buf_size);
+    +               if(!new_buf)
+    +                   die("realloc failed");
+    +               buf = new_buf;
+    +           }
+
+For each directory entry we create or adapt the buffer size.
+
+
+            }
+    +       free(buf);
+
+We free the buf when done.
+
diff --git a/user/tlecarrour/up-imapproxy.mdwn b/user/tlecarrour/up-imapproxy.mdwn
new file mode 100644
index 00000000..fceea7d3
--- /dev/null
+++ b/user/tlecarrour/up-imapproxy.mdwn
@@ -0,0 +1,54 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+
+up-imapproxy
+============
+
+SquirrelMail's IMAP Proxy is a caching IMAP proxy server intended for use with webmail clients that cannot maintain persistent connections to an IMAP server.  
+**Home page**: [[http://www.imapproxy.org]]
+
+[[!toc startlevel=2]]
+
+
+* * *
+
+
+Log
+---
+
+* **Started**: 2012-01-31
+* **Discussed**: -
+* **Draft Submitted**: -
+* **Submitted**: -
+* **Accepted**: -
+
+
+* * *
+
+
+ToDo
+----
+
+Here is the output of `grep -R PATH_MAX up-imapproxy-1.2.7/*`:
+
+    src/main.c:    char f_randfile[ PATH_MAX ];
+
+
+* * *
+
+
+Comments
+--------
+
+Work in progress...
+
+Only the function that fills the buffer knows how long it can be.  
+This function is `RAND_file_name()` and is part of **OpenSSL**.