12. DSO (Dynamic Symbol Object)

Vous connaissez peut-être les objets partagés (so = shared object) ou les dlls (dll=dynamic link library). Grossièrement on peut dire que DSO est né du principe des so/dll. Mais on parle de dso (Dynamic Symbol Object) pour les différencier des librairies dynamiques so/dll.

Pour comprendre le fonctionnement des dso, il faut savoir comment fonctionne le link et le chargement. En général, lorsqu’on utilise des librairies dynamiques, on les « link » avec le programme principal lors de la compilation. ld(1) s’occupe de cela sur Unix. ld(1) est connu en tant qu’éditeur de lien. Comme ld(1) est habituellement appelé par le compilateur lui-même gcc(1) de façon implicite, peut-être n’avez-vous jamais entendu parler de ld(1). Au mieux avez-vous vu des messages problème de « link » lors de la compilation. Cela signifie que ld(1) n’arrive pas à résoudre certains symboles que vous utilisez dans votre programme. En cours d’exécution, ld.so(8) charge les librairies dynamiques. S’il n’y arrive pas, vous verrez des messages d’erreur de chargement. En résumé, le « link » est fait lors de la compilation, et le chargement est fait lors de l’exécution. Si vous voulez en savoir plus, il vous suffit de lire les manuels ld(1) et ld.so(8).

Grâce à dso, le link et le chargement sont faits lors de l’exécution. Quel est l’intérêt d’un tel mécanisme ? La raison se résume en deux mots : architecture plugin. La seule chose que nous ayons à faire lors de la compilation est de définir les interfaces (« noms symboliques » et la manière les appeler, les paramètres à leur donner, donc) des modules qu’il devra être possible de charger. Le programme charge les modules pendant son exécution, et s’en sert au travers d’interfaces. Les modules dynamiquement « téléchargeables » peuvent ainsi être développés par des programmeurs indépendants. Vous pourrez ainsi rendre votre programme très flexible et extensible.

Voyons voir dso-sample.c. Vous pouvez y voir deux chaines : « libm.so » et « pow ». En réalité, pow(3) est une fonction basique et, en temps normal, n’a pas besoin d’être appelée sous forme de dso, mais c’est simplement pour l’exemple.

Au début, on appelle apr_dso_load() et on lui donne le nom de la librairie : « libm.so ».

/* extrait de dso-sample.c, vérif. des erreurs omise */
const char fname[] = "libm.so";
    apr_dso_handle_t *dso_h;
    apr_dso_load(&dso_h, fname, mp);

Comme vous pouvez l’imaginer, si vous voulez programmer en donnant la possibilité aux autres de faire des plugins pour votre programme, vous devez faire en sorte d’avroi un fichier dans lequel il y a tous les noms des plugins à télécharger. On a déjà quelque chose qui tourne plutôt bien : les modules apache. Leurs noms sont spécifiés, en général, dans le fichier de configuration principal : le fichier « httpd.conf ».

Lorsque apr_dso_load() renvoie une erreur, c’est, la plupart du temps, parce qu’il ne trouve pas le fichier de la librairie dynamique. Le chemin de recherche pour les librairies dépend du système d’exploitation. Sur GNU/Linux, il dépend de la variable d’environnement LD_LIBRARY_PATH. Sur MS-Windows, il dépend de la variable d’environnement PATH. Après avoir un résultat de retour de apr_dso_load() réussi, on peut appeler apr_dso_sym().

Voici le prototype :

/* extrait de apr_dso.h */
APR_DECLARE(apr_status_t) apr_dso_sym(
    apr_dso_handle_sym_t *ressym,
    apr_dso_handle_t *handle,
    const char *symname);

On peut récupérer un objet par son nom via apr_dso_sym(). Le premier argument est un argument résultat. Le second argument est un handle dso, qu’on a avec apr_dso_open() expliqué précédemment. Le troisième argument est le nom du symbole.

Le code suivant est un extrait de dso-sample.c. Le nom du symbole est « pow » et on récupère un pointeur de fontion en tant qu’objet. Comme on connait l’interface de pow(3), il nous suffit de définir la fonction en tant que type : pow_fn_t.

/* extrait de dso-sample.c, vérif. des erreurs omise */
typedef double (*pow_fn_t)(double x, double y);
pow_fn_t pow_fn;

/* récupérer la fonction pow(3) de libm.so */
apr_dso_sym(
    (apr_dso_handle_sym_t*)&pow_fn,
    dso_h, "pow");

/* appeler pow(3) */
printf("%d ^ %d = %f\n", 2, 2, pow_fn(2, 2));

Si votre programme a des plugins, vous devrez définir des noms symboliques ainsi que leurs interfaces. Par la suite, les développeurs devront s’appuyer sur ces déclarations. Enfin, on appelle apr_dso_unload() pour libérer le module. Cela diminue ainsi la consommation mémoire.

10. Options de la ligne de commande

Pour les outils en ligne de commande (CLI, Command Line Interface), les options qu’on donne en ligne de commandes sont souvent utilisées. La librairie libapr met des fonctions à disposition qui facilitent grandement la gestion des options fournies en ligne de commande. Voici un extrat de getopt-sample.c.

/* extrait de getopt-sample.c */
static const apr_getopt_option_t opt_option[] = {
    /* énumération comme suit :
     * {opt. longue}, {opt. courte},
     * {flag "argument qui suit"}, {description} :
     */

    /* -i nomfichier or --in nomfichier : */
    { "in", 'i', TRUE, "fichier entrant" },

    /* -o nomfichier or --out nomfichier : */
    { "out", 'o', TRUE, "fichier sortant" },

    /* -h or --help : */
    { "help", 'h', FALSE, "voir l'aide" },

    /* sentinelle de fin : */
    { NULL, 0, 0, NULL },
};

En premier lieu, il faut fournir un tableau d’éléments apr_getopt_option_t. On l’appelle (ici) option-list. Chaque élément a quatre variables :

1. une option longue ;
2. une option courte ;
3. un flag « argument qui suit », pour préciser si cette option nécessite un argument qui doit la suivre ;
4. une description.

Par exemple, pour l’option « help » :

• Une option longue : ‘–help’ :
• Une option courte : ‘-h’.

Les options courtes sont obligatoires et les options longues sont optionnelles. On peut tout à fait mettre NULL pour une option longue. La troisième variable précise si un argument supplémentaire doit suivre cette option. Par exemple si une option de ligne de commande fonctionne ainsi  ‘–in nomfichier’, c’est à dire qu’il faut obligatoirement préciser un nom de fichier, il faut mettre ce flag à vrai (TRUE). Ainsi, si le programme est exécuté et qu’on donne cette option sans donner un argument, par exemple ‘./a.out -in’, une erreur est levée.
Enfin, le tableau de la liste des options doit se terminer par une sentinelle vide qui précise que la liste est finie (voir l’exemple précédent).
Pour parcourir les options fournies dans la ligne de commande, if faut tout d’abord initialiser le parser en appelant ‘apr_getopt_init()’ (pour initialiser un objet apr_getopt_t) puis faire une boucle en s’aidant du tableau des options. Ensuite, on appelle en boucle apr_getopt_long() tant qu’il renvoie APR_SUCCESS. Voici un extrait de getopt-sample.c :

/* extrait de getopt-sample.c */
/* initialiser apr_getopt_t */
apr_getopt_t *opt;
apr_getopt_init(&opt, mp, argc, argv);
/* parcourir toutes les options via opt_option[] */
while ((rv = apr_getopt_long(opt,opt_option,
                             &optch,
                             &optarg)) == APR_SUCCESS) {
...etc.

Dans la boucle, apr_getopt_long() enumère les options passées en ligne de commande une par une. Si l’option trouvée fait partie de la liste des options, apr_getopt_long() renvoie APR_SUCCESS et initialise la valeur de optch en conséquence. Si l’option a un argument supplémentaire apr_getopt_long() le lit et initialise la valeur de optarg.

Voyons un exemple concret. Imaginons que vous lanciez le programme en y ajoutant une option et une valeur associée : ‘./getopt-sample -h -i foo.txt’. Lors de la première boucle, apr_getopt_long() trouve ‘h’ dans la liste des option. Donc, apr_getopt_long() renvoie APR_SUCCESS et initialise optch avec la valeur ‘h’. Sur la boucle suivante, apr_getopt_long() trouve ‘i’ dans la liste des options, et comme ‘i’ nécessite un argument qui doit le suivre, il y a lecture de l’argument suivant, ‘foo.txt’. Ainsi, apr_getopt_long() renvoie APR_SUCCESS, avec optch qui vaut ‘i’ et optarg qui vaut « foo.txt ». Lors de la boucle suivante, apr_getopt_long() ne trouve plus d’options et renvoie par conséquent APR_EOF.

11. memory map (mmap)

mmap signifie « mapping mémoire ». Ce qui veut dire « mapper » des fichiers en mémoire. mmap est principalement utilisé pour :

• Lire/écrire dans des fichiers le plus rapidement possible ;
• Allouer un espace mémoire consécutif plus gros (gestion spécifique à chaque système d’exploitation) ;
• Partage mémoire entre différents processus.

Pensez au cas où vous voulez lire un fichier en entier en une fois. Dans ce cas il faut faire un buffer, lire du début jusqu’à la fin dans une boucle. Le code ressemblerait à cela :

/* code simpliste pour lire le contenu d'un fichier */
apr_file_t *fp;
apr_file_open(&fp, filename, APR_READ, APR_OS_DEFAULT, mp);
while (1) {
    char buf[1024];
    apr_size_t len = sizeof(buf);
    rv = apr_file_read(fp, buf, &len);
    if (rv != APR_SUCCESS) {
        break;
    }
    /* scan buf */
}
apr_file_close(fp);

On peut faire mieux, avec apr_mmap_t :

/* extrait de mmap-sample.c, vérif. des erreurs omise */
apr_file_open(&fp, filename, APR_READ, APR_OS_DEFAULT, mp);
apr_finfo_t finfo;
apr_file_info_get(&finfo, APR_FINFO_SIZE, fp);
apr_mmap_t *mmap;
apr_mmap_create(&mmap, fp, 0, finfo.size, APR_MMAP_READ, mp);
/* scan mmap->mm */
apr_mmap_delete(mmap);

Si le fichier est suffisamment gros, le code basé sur mmap sera plus rapide.
Plus important encore, mmap aide à éviter la fragmentation mémoire. La plupart des systèmes (qui doivent gérer les allocations mémoire) se trouvent confronté au problème de fragmentation mémoire, mais mmap n’entre pas dans le cadre d’allocation mémoire dans l’espace utilisateur. Malheureusement, sur certains systèmes, mmap est parfois lent et bogué.

On peut utiliser mmap pour modifier des fichiers. On ouvre le fichier avec APR_WRITE, puis on « mmap » le fichier en précisant le flag APR_MMAP_WRITE.

REMARQUE : Il est interdit de « mmap-er » un fichier ouvert avec le flag APR_BUFFERED. Le code suivant renverra toujours l’erreur APR_EBADF :

/* Exemple mmap BOGUE */
apr_file_t *fp;
apr_mmap_t *mm;
apr_file_open(&fp,
    fname,
    APR_READ|APR_BUFFERED,
    APR_OS_DEFAULT, mp);
rv = apr_mmap_create(&mm,
    fp, 0,
    finfo.size,
    APR_MMAP_READ, mp);
/* BOGUE : le résultat sera TOUJOURS :
 * rv==APR_EBADF
 */

Note

Regardez le tutoriel au complet, en Anglais, ici.
Vous trouverez tout ce tutoriel séparé en plusieurs pages ici.
Ce fichier est l’exemple le plus simple pour mettre en oeuvre les fonctions apr_xx
Il vient d’ici.

/**
 * Exemple du tutoriel apr
 * http://dev.ariel-networks.com/apr/
 */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#include <apr_general.h>
#include <apr_getopt.h>

/**
 * command line options sample code
 * @remark Error checks omitted
 */
int main(int argc, const char *argv[])
{
    apr_status_t rv;
    apr_pool_t *mp;
    /* API is data structure driven */
    static const apr_getopt_option_t opt_option[] = {
        /* -i nomfichier or --in nomfichier : */
        { "in", 'i', TRUE, "fichier entrant" },
        /* -o nomfichier or --out nomfichier : */
        { "out", 'o', TRUE, "fichier sortant" },
        /* -h or --help : */
        { "help", 'h', FALSE, "voir l'aide" },
        /* sentinelle de fin : */
        { NULL, 0, 0, NULL },
    };
    apr_getopt_t *opt;
    int optch;
    const char *optarg;

    apr_initialize();
    apr_pool_create(&mp, NULL);

    /* initialize apr_getopt_t */
    apr_getopt_init(&opt, mp, argc, argv);

    /* parcourir toutes les options via opt_option[] */
    while ((rv = apr_getopt_long(opt,opt_option,
                                 &optch,
                                 &optarg)) == APR_SUCCESS) {
        switch (optch) {
        case 'i':
            printf("opt=i, %s\n", optarg);
            break;
        case 'o':
            printf("opt=o, %s\n", optarg);
            break;
        case 'h':
            printf("afficher l'aide\n");  /* no arg */
            break;
        }
    }
    if (rv != APR_EOF) {
        printf("mauvaises options\n");
    }

    apr_terminate();
    return 0;
}

8. gestion des chaines de caractères

Je suppose que vous connaissez les bases de manipulation de chaine en C, notamment les fonctions strlen(3) et strcpy(3). La librairie libapr propose des fonctions extrêmement utiles de gestion des chaines. Elles sont pratiquement les mêmes que leur équivalent en ANSI C. Pourquoi libapr fournit encore une autre possibilité de gestion de chaines ? L’intérêt est directement lié avec le principe de gestion par pool mémoire. Dans une gestion habituelle de chaine en C, il faut écrire du code de gestion de mémoire : allocation, libération, etc. Le code qui suit en est l’exemple.

/* exemple de manipulation de chaine ANSI C */
/* (code simpliste) */
/* on concatène 3 chaines : s1, s2, s3 */
int len1 = strlen(s1);
int len2 = strlen(s2);
int len3 = strlen(s3);
int total_len = len1 + len2 + len3;
char *cat_str = malloc(total_len + 1);
strcpy(cat_str, s1);
strcat(cat_str, s2);
strcat(cat_str, s3);
/* plus tard, il nous faut libérer la mémoire allouée */
free(cat_str);

La même chose avec la librairie libapr s’écrira ainsi :

/* pseudo code sur la gestion des chaines de libapr */
apr_pool_t *mp;
apr_pool_create(&mp, NULL);
/* apr_pstrcat() gère à la fois l'allocation
 * mémoire et la concaténation des chaines
 * Si la chaine concaténée est en lecture seule,
 * il nous faut utiliser le type 'const char*'.
 */
const char *cat_str = apr_pstrcat(mp, s1, s2, s3, NULL);
/* plus tard, la seule chose à faire
 * est de détuire le pool mémoire
 * pour tout libérer
 */
apr_pool_destroy(mp);

De la même façon que apr_pstrcat(), apr_psprintf() vous aide à écrire un code beaucoup plus simple. Vous trouvez d’autres fonctions sur les chaines dans apr_strings.h.

9. Gestion de de l’heure

Les fonctions mises à disposition par libapr sont basées sur le schéma POSIX. Une valeur de type apr_time_t représente le temps écoulé depuis une époque UNIX c’est à dire depuis le 1/1/1970. Seulement il y a deux différences de taille :

1. apr_time_t est géré sur 64 bits (long long)
2. apr_time_t réprésente des microsecondes

La fonction la plus utile est apr_time_now(). Comme vous l’imaginez, elle renvoie la date et l’heure courante. Vous trouverez sa déclaration dans apr_time.h.

/* extrait de apr_time.h */
APR_DECLARE(apr_time_t) apr_time_now(void);

Très souvent nous avons à convertir une valeur apr_time_t dans d’autres formats. Il y a principalement deux formats qui vous seront utiles :

1. Une structure temps : apr_time_exp_t (time structure)
2. Les formats exprimant les dates sous forme de chaines (p.ex. la rfc822)

Pour convertir apr_time_t en une structure apr_time_exp_t, il faut utiliser les fonctions de la libapr suivantes :

/* extrait de apr_time.h */
APR_DECLARE(apr_status_t) apr_time_exp_gmt(
    apr_time_exp_t *result, apr_time_t input);
APR_DECLARE(apr_status_t) apr_time_exp_lt(
    apr_time_exp_t *result, apr_time_t input);

La fonction apr_time_exp_gmt() renvoie le résultat qui est dans une zone GMT, et apr_time_exp_lt() renvoie le résultat en se basant sur la zone de temps locale. Le premier argument des deux fonctions est un argument résultat.
Il est possible de faire la conversion dans l’autre sens : convertir une structure apr_time_exp_t en une valeur apr_time_t.

/* extrait de apr_time.h */
APR_DECLARE(apr_status_t) apr_time_exp_get(
    apr_time_t *result, apr_time_exp_t *input);

Il y a plusieurs fonctions pour convertir une valeur apr_time_t en différents formats de chaines représentant une date / heure :

/* extrait de apr_time.h */
APR_DECLARE(apr_status_t) apr_rfc822_date(
    char *date_str, apr_time_t t);
APR_DECLARE(apr_status_t) apr_ctime(
    char *date_str, apr_time_t t);
APR_DECLARE(apr_status_t) apr_strftime(
    char *s, apr_size_t *retsize, apr_size_t max,
    const char *format, apr_time_exp_t *tm);

A l’inverse, si on a des chaines dans ces formats, et qu’on veut les convertir en une valeur apr_time_t, il faut appeler des fonctions utilitaires de apr-util (un sous ensemble de la libapr), définis dans apr_date.h.
Regardez l’exemple de time-sample.c pour avoir un exemple concret de l’utilisation de ces fonctions.
REMARQUE : Comme expliqué juste avant, apr_time_t est un type long long (64 bits). Notez bien que le code suivant déclenchera un débordement.

/* Exemple BOGUE. Génération de débordement */
const apr_time_t UNE_HEURE = 1000 * 1000 * 60 * 60;

On le résoud en faisant une conversion de type explicite, mais je vous recommande d’utiliser simplement le type que fournit la librairie libapr. Le code suivant le montre.

/* deux exemples pour contourner
 * le débordement expliqué juste avant
 */
const apr_time_t UNE_HEURE = APR_TIME_C(1000) * 1000 * 60 * 60;

ou bien :

const apr_time_t UNE_HEURE = APR_USEC_PER_SEC * 60 * 60;

REMARQUE : Parfois, souvent en déboguant, on veut afficher des valeurs de temps en clair. Malheureusement, Unix et Windows ont des manière différentes de spécifier le type 64 bits quand on se sert de printf(3). Sur Unix c’est « %lld » est sur Windows c’est « %I64d ». Pour de tels problèmes de portabilité, la librairie libapr fournit des spécificateurs de format, p.ex. APR_INT64_T_FMT. Il y a aussi APR_TIME_T_FMT dans apr_time.h. On peut écrire du code parfaitement portable en utilisant ces spécificateurs.

/* Sur Unix, APR_INT64_T_FMT est défini dans apr.h */
#define APR_INT64_T_FMT "lld"
/* Sur Windows, APR_INT64_T_FMT est défini dans apr.h */
#define APR_INT64_T_FMT "I64d"

/* extrait de apr_time.h */
#define APR_TIME_T_FMT APR_INT64_T_FMT

/* On peut utiliser APR_TIME_T_FMT de cette façon : */
printf("L'heure courante est : %" APR_TIME_T_FMT "[us]\n",
    apr_time_now());

/**
 * Exemple du tutoriel apr
 * http://dev.ariel-networks.com/apr/
 */
#ifdef HAVE_CONFIG_H
#include 
#endif

#include 
#include 
#include 

#include 
#include 

static void format_to_struct(apr_time_t t)
{
    apr_time_exp_t tm;
    apr_time_t t2;

    apr_time_exp_gmt(&tm, t);
    printf("GMT: tm.hour = %d, tm.min = %d, tm.sec = %d\n", tm.tm_hour, tm.tm_min, tm.tm_sec);
    apr_time_exp_lt(&tm, t);
    printf("local: tm.hour = %d, tm.min = %d, tm.sec = %d\n", tm.tm_hour, tm.tm_min, tm.tm_sec);

    /* conversion inverse */
    apr_time_exp_gmt_get(&t2, &tm);/* from tm to t2 */
    assert(t == t2);
}

static void format_to_string(apr_time_t t)
{
    char rbuf[APR_RFC822_DATE_LEN + 1];
    char cbuf[APR_CTIME_LEN + 1];

    apr_rfc822_date(rbuf, t);
    printf("apr_rfc822_date: %s\n", rbuf);
    apr_ctime(cbuf, t);
    printf("apr_ctime: %s\n", cbuf);
}

/**
 * Exemple des routines de gestion de l'heure
 * @remark Vérif. des erreurs omise
 */
int main(int argc, const char *argv[])
{
    apr_pool_t *mp;
    apr_time_t t;

    apr_initialize();
    apr_pool_create(&mp, NULL);

    /* récupérer l'heure courante
     * (temps écoulé depuis le 1/1/1973, en micro-secondes)
     */
    t = apr_time_now();
    printf("Heure courante : %" APR_TIME_T_FMT "[us]\n", t);
    printf("Heure courante : %" APR_TIME_T_FMT "[ms]\n", apr_time_as_msec(t));
    printf("Heure courante : %" APR_TIME_T_FMT "[s]\n", apr_time_sec(t));

    /* formattage de l'heure */
    format_to_struct(t);
    format_to_string(t);

    apr_terminate();
    return 0;
}

Note

Regardez le tutoriel au complet, en Anglais, ici.
Vous trouverez tout ce tutoriel séparé en plusieurs pages ici.
Ce fichier est l’exemple le plus simple pour mettre en oeuvre les fonctions apr_xx
Il vient d’ici.

/**
 * Exemple de code tutoriel
 * http://dev.ariel-networks.com/apr/
 */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#include <apr_general.h>
#include <apr_file_info.h>
#include <apr_strings.h>

/**
 * Parcours d'un répertoire de manière récursive
 * @return TRUE si tout est Ok, sinon FALSE.
 */
static int traverse_dir(const char *dirpath, apr_pool_t *mp)
{
    apr_status_t rv;
    apr_finfo_t dirent;
    apr_dir_t *dir;

    printf("Directory: %s\n", dirpath);
    if ((rv = apr_dir_open(&dir, dirpath, mp)) != APR_SUCCESS) {
        return FALSE;
    }

    while ((apr_dir_read(&dirent,
                         APR_FINFO_DIRENT | APR_FINFO_TYPE | APR_FINFO_NAME,
                         dir)) == APR_SUCCESS) {
        if (dirent.filetype == APR_DIR) {
            char *path;
            if (strcmp(dirent.name, ".") == 0 || strcmp(dirent.name, "..") == 0) {
                continue;
            }

            if ((rv = apr_filepath_merge(&path,
                                         dirpath,
                                         dirent.name,
                                         0,
                                         mp)) != APR_SUCCESS) {
                goto error;
            }
            /* beaucoup plus simple :
             * path = apr_pstrcat(mp, dirpath, "/", dirent.name, NULL);
             */
             traverse_dir(path, mp);
        } else if (dirent.filetype == APR_REG) {
            printf("Nom de fichier normal/classique : %s\n",
                apr_pstrcat(mp, dirpath, "/", dirent.name, NULL));
        } else {
            printf("Nom de fichier anormal/pas classique : %s\n",
                apr_pstrcat(mp, dirpath, "/", dirent.name, NULL));
        }
    }

    if ((rv = apr_dir_close(dir)) != APR_SUCCESS) {
        return FALSE;
    }
    return TRUE;

 error:
    apr_dir_close(dir);
    return FALSE;
}

/**
 * Exemple de listing d'un répertoire
 * @remark Vérif. des erreurs omises
 */
int main(int argc, char **argv)
{
    apr_status_t rv;
    apr_pool_t *mp;
    const char *dirname;
    apr_finfo_t finfo;

    if (argc == 2) {
        dirname = argv[1];
    } else {
        dirname = ".";
    }

    apr_initialize();
    apr_pool_create(&mp, NULL);

    if ((rv = apr_stat(&finfo,
                       dirname,
                       APR_FINFO_TYPE, mp)) != APR_SUCCESS) {
        goto error;
    }
    if (finfo.filetype != APR_DIR) {
        printf("precisez un nom de repertoire\n");
        goto error;
    }
    traverse_dir(dirname, mp);

    apr_terminate();
    return 0;

 error:
    apr_terminate();
    return -1;
}

Note

Regardez le tutoriel au complet, en Anglais, ici.
Vous trouverez tout ce tutoriel séparé en plusieurs pages ici.
Ce fichier exemple vient d’ici.

/**
 * Exemple pour le tutoriel apr
 * http://dev.ariel-networks.com/apr/
 */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#include <apr_general.h>
#include <apr_file_io.h>

static apr_status_t do_writelock(const char *fname, apr_pool_t *mp)
{
    apr_status_t rv;
    apr_file_t *fp;

    if ((rv = apr_file_open(&fp, fname, APR_WRITE, APR_OS_DEFAULT, mp)) != APR_SUCCESS) {
        return rv;
    }
    rv = apr_file_lock(fp, APR_FLOCK_EXCLUSIVE | APR_FLOCK_NONBLOCK);
    /* si vous mettez le drapeau APR_FLOCK_NONBLOCK, apr_file_lock() ne fonctionnera pas.
     * Il faut toujours vérifier la valeur de retour */
    if (rv != APR_SUCCESS) {
        puts("writable-lock failed");
        goto done;
    }
    printf("%s est verrouillé en écriture.\n", fname);
    printf("Appuyez sur une touche pour le déverrouiller.\n");
    getchar();

    apr_file_unlock(fp);
 done:
    apr_file_close(fp);
    return rv;
}

static apr_status_t do_readlock(const char *fname, apr_pool_t *mp)
{
    apr_status_t rv;
    apr_file_t *fp;

    if ((rv = apr_file_open(&fp, fname, APR_READ,  APR_OS_DEFAULT, mp)) != APR_SUCCESS) {
        return rv;
    }
    rv = apr_file_lock(fp, APR_FLOCK_SHARED | APR_FLOCK_NONBLOCK);
    if (rv != APR_SUCCESS) {
        puts("Impossible de mettre le verrou en lecture.");
        goto done;
    }

    apr_file_unlock(fp);
 done:
    apr_file_close(fp);
    return rv;
}

/**
 * Exemple de verrou fichier
 * @remark Vérif. des erreur supprimée pour plus de clarté
 */
int main(int argc, const char *argv[])
{
    apr_status_t rv;
    apr_pool_t *mp;
    int c;
    const char *fname;

    if (argc < 2) {
        printf("Utilisation : %s fichier-de-sortie\n", argv[0]);
        return 0;
    }
    fname = argv[1];

    apr_initialize();
    apr_pool_create(&mp, NULL);

    puts("verrou-écriture / verrou-lecture [w/r]?");
    c = getchar();
    if (c == 'w') {
        rv = do_writelock(fname, mp);
    } else if (c == 'r') {
        rv = do_readlock(fname, mp);
    }

    apr_pool_destroy(mp);
    apr_terminate();
    return 0;
}

Note

Regardez le tutoriel au complet, en Anglais, ici.
Vous trouverez tout ce tutoriel séparé en plusieurs pages ici.
Ce fichier est l’exemple le plus simple pour mettre en oeuvre les fonctions apr_xx
Il vient d’ici.

/**
 * Tutoriel apr, exemple de code
 * http://dev.ariel-networks.com/apr/
 */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#include <apr_general.h>
#include <apr_file_io.h>

/**
 * exemple de récupération d'informations sur un fichier
 * @remark Vérif. des erreurs omise
 */
int main(int argc, const char *argv[])
{
    apr_status_t rv;
    apr_pool_t *mp;
    apr_file_t *fp;
    const char *fname;
    apr_finfo_t finfo;

    if (argc < 2) {
        printf("Utilisation : %s fichier-de-sortie\n", argv[0]);
        return 0;
    }
    fname = argv[1];

    apr_initialize();
    apr_pool_create(&mp, NULL);

    /* @remark depuis apr-1.1.0, utiliser APR_FOPEN_READ au lieu de APR_READ */
    if ((rv = apr_file_open(&fp, fname, APR_READ, APR_OS_DEFAULT, mp)) != APR_SUCCESS) {
        return -1;
    }

    /* Ci-suivent deux façons différentes pour récupérer
     * l'information : elles donnent le même résultat.
     *
     * Si vous avez déjà ouvert le fichier,
     * le premier est le meilleur. Sinon, le
     * second est le meilleur.
     */

    /* Récupération des informations. Via apr_file_t */
    rv = apr_file_info_get(&finfo, APR_FINFO_NORM, fp);
    /* Récupération des informations. Via le nom de fichier */
    rv = apr_stat(&finfo, fname, APR_FINFO_NORM, mp);

    apr_file_close(fp);

    apr_terminate();
    return 0;
}