pool *ap_make_sub_pool(pool *p)

Crée un sous-pool dans un pool. Le sous-pool est automatiquement détruit lorsque le pool p est supprimé, mais peut également être détruit avant par ap_destroy_pool ou réinitialisé par ap_clear_pool. Renvoie le nouveau pool.

void ap_clear_pool(pool *p)

Réinitialise un pool en supprimant tous ses sous-pools avec destroy_pool et en le nettoyant. Le pool lui-même reste vide mais intact et peut donc être réutilisé.

void ap_destroy_pool(pool *p)

Supprime un pool en lançant les méthodes de nettoyage pour son contenu et en supprimant tous ses sous-pools avant ce nettoyage.

long ap_bytes_in_pool(pool *p)

Renvoie le nombre d’octets alloués à un pool.

long ap_bytes_in_free_blocks(void)

Renvoie le nombre d’octets des blocs libres pour tous les pools.

void *ap_palloc(pool *p, int size)

Alloue une taille mémoire d’au moins size octets. Cette zone est supprimée lorsque le pool est détruit. Renvoie un pointeur vers ce nouveau bloc mémoire.

void *ap_pcalloc(pool *p, int size)

Alloue une taille mémoire d’au moins size octets et initialise cette zone à zéro. Cette zone est supprimée lorsque le pool est détruit. Renvoie un pointeur vers ce nouveau bloc mémoire.

char *ap_pstrdup(pool *p,const char *s)

Duplique une chaîne dans un pool. Cette zone est supprimée lorsque le pool est détruit. Renvoie NULL si s vaut NULL ; sinon, renvoie un pointeur vers la nouvelle copie de la chaîne.

char *ap_pstrndup(pool *p, const char *s, int n)

Alloue n +1 octets de mémoire et copie au plus n caractère de s en complétant par le caractère NULL. Cette zone est supprimée lorsque le pool est détruit. Renvoie NULL si s vaut NULL ; sinon, renvoie un pointeur vers la nouvelle copie de la chaîne.

char *ap_pstrcat(pool *p, ...)

Concatène la liste de chaînes dans un nouveau bloc mémoire, qui est supprimé lorsque le pool est détruit. La liste doit se terminer par NULL. Renvoie un pointeur vers cette zone mémoire :

pstrcat(p,"Hello,","world!",NULL);

renvoie un bloc mémoire contenant Hello,world!.

array_header *ap_make_array(pool *p, int nelts, int elt_size)

Alloue de la mémoire pour stocker nelts éléments de elt_size octets. Le tableau peut grossir pour contenir autant d’éléments que nécessaire et il est supprimé lorsque le pool est détruit. Renvoie un pointeur vers le tableau.

void *ap_push_array(array_header *arr)

Renvoie un pointeur vers l’élément suivant du tableau arr et alloue plus de mémoire si nécessaire.

void ap_array_cat(array_header *dst, const array_header *src)

Ajoute le tableau src à la suite du tableau dst. Si nécessaire, plus de mémoire est allouée à dst pour qu’il puisse recevoir les éléments supplémentaires. Bien que cette opération n’ait de sens que si les deux tableaux contiennent des éléments de même taille, aucune vérification n’est effectuée.

array_header *ap_copy_array(pool *p, const array_header *arr)

Crée une copie du tableau arr dans le pool p. Le nouveau tableau est détruit en même temps que le pool. Renvoie un pointeur vers ce tableau.

array_header *ap_copy_array_hdr(pool *p, const array_header *arr)

Copie le tableau arr dans le pool p sans copier immédiatement son contenu. Si le tableau est étendu par un appel à push_array, le tableau original est copié dans le nouveau tableau avant que l’ajout ne s’effectue. Renvoie un pointeur vers ce tableau.

Cette fonction comporte au moins deux pièges. Si le tableau n’est pas étendu, la mémoire qui lui a été allouée est détruite en même temps que le tableau original. De plus, toutes les modifications apportées au tableau original peuvent également affecter le nouveau tableau si elles interviennent avant l’extension de ce dernier.

array_header *ap_append_arrays(pool *p, const array_header *first,
const array_header *second)

Crée un nouveau tableau formé des éléments de first, puis de ceux de second. Si second est vide, le nouveau tableau partage la mémoire avec first jusqu’à ce qu’un nouvel élément lui soit ajouté (c’est une conséquence de l’utilisation de ap_copy_array_hdr( ) pour créer le nouveau tableau ; voir les mises en garde à propos de cette fonction). Renvoie un pointeur vers le nouveau tableau.

table *ap_make_table(pool *p, int nelts)

Crée une table avec suffisamment d’espace pour y stocker nelts éléments. Renvoie un pointeur vers cette table.

table *ap_copy_table(pool *p, const table *t)

Renvoie un pointeur vers une copie de la table.

array_header *ap_table_elts(table *t)

Renvoie le tableau sur lequel repose la table.

int ap_is_empty_table(table *t)

Renvoie une valeur non nulle si la table est vide.

void ap_table_set(table *t, const char *key, const char *value)

Si key a déjà une valeur qui lui est associée dans t, cette valeur est remplacée par une copie de value ; sinon, une nouvelle entrée est créée dans la table. La clé et la valeur sont dupliquées via un appel à ap_pstrdup( ).

void ap_table_setn(table *t, const char *key, const char *value)

Identique à ap_table_set( ), sauf que la clé et la valeur ne sont pas dupliquées. Cette fonction est généralement utilisée pour copier une valeur d’un pool dans un sous-pool.

void ap_table_merge(table *t, const char *key, const char *value)

Si key a déjà une valeur qui lui est associée dans t, value est ajoutée à la valeur existante, séparée par une virgule et un espace ; sinon, une nouvelle entrée est créée, comme dans table_set. Si plusieurs instances de key existent dans la table, seule la première est affectée.

pool *p; /* Initialisé ailleurs */

table *t;

char *v;

t=make_table(1);

table_set(t,"uneCle","Hello");

table_merge(t,"uneCle","world!");

v=table_get(t,"uneCle"); /* v contient maintenant "Hello, world!" */

void ap_table_mergen(table *t, const char *key, const char *value)

Identique à ap_table_merge( ), sauf que si une nouvelle paire clé/valeur est créée, elle n’est pas dupliquée. Cette fonction est généralement utilisée pour fusionner une valeur d’un pool dans un sous-pool.

void ap_table_add(table *t, const char *key, const char *value)

Ajoute une nouvelle entrée dans la table, en associant key à value. La nouvelle entrée est créée que la clé existe déjà ou non dans la table. La clé et la valeur sont dupliquées par un appel à ap_pstrdup( ).

void ap_table_addn(table *t, const char *key, const char *value)

Ajoute une nouvelle entrée dans la table, en associant key à value. La nouvelle entrée est créée que la clé existe déjà ou non dans la table. La clé et la valeur ne sont pas dupliquées, vous devez donc vous assurer qu’elles ne seront pas modifiées. Cette fonction sert généralement à copier une entrée de table d’un pool dans un sous-pool.

void ap_table_unset(table *t, const char *key)

Supprime l’entrée correspondant à la clé key dans la table. Supprimer une entrée inexistante n’est pas considéré comme une erreur.

const char *ap_table_ get(const table *t, const char *key)

Renvoie la valeur correspondant à la clé key dans la table t. Vous remarquerez que vous ne pouvez pas modifier la valeur renvoyée.

void ap_table_do(int (*comp) (void *, const char *, const char *),
void *rec, const table *t,...)

Si la liste vararg (qui doit se terminer par NULL ) est vide, parcourt toute la table et lance la fonction comp(rec,key,value) sur chaque paire clé/valeur. Si vararg n’est pas vide, parcourt les clés qui lui correspondent (au sens de strcasecmp( ) ) et lance la fonction sur les entrées concernées. Les parcours se terminent lorsque la fonction comp( ) renvoie la valeur 0.

Dans les deux cas, il peut arriver que la fonction comp( ) soit appelée plusieurs fois pour la même clé. La table pouvant contenir plusieurs entrées ayant la même clé, si la liste vararg n’est pas vide, le parcours est répété pour chaque élément de cette liste, même s’ils sont égaux.

table *ap_overlay_tables(pool *p, const table *overlay, const table *base)

Crée une table formée de la concaténation des tables overlay et base -- overlay étant la première. On ne tente ni de fusionner, ni d’écraser les clés existantes dans l’une des tables mais, comme overlay vient en premier, toute récupération par ap_table_get sur la nouvelle table renverra l’entrée de overlay si elle existe. Renvoie un pointeur vers la nouvelle table.

API_EXPORT(void) ap_clear_table(table *t)

Réinitialise la table sans supprimer aucun élément (le mécanisme de pool ne le permet pas, de toutes façons), bien qu’ils ne soient plus accessibles.

void ap_register_cleanup(pool *p, void *data, void (*plain_cleanup)(void *),
void (*child_cleanup)(void *))

Enregistre deux fonctions qui seront appelées lorsque le pool est détruit. Un pool peut être détruit pour deux raisons : lorsque le serveur n’en a plus besoin, auquel cas il le détruit et appelle la fonction plain_cleanup, ou lorsque le serveur a créé un processus fils et qu’il se prépare à appeler exec pour lancer un autre programme, auquel cas il appelle la fonction child_cleanup. Dans les deux cas, data est le seul paramètre passé à ces fonctions. Si l’une d’elle n’est pas nécessaire, utilisez ap_null_cleanup.

void ap_kill_cleanup(pool *p, void *data, void (*plain_cleanup)(void *))

Supprime du pool la fonction de nettoyage identifiée par plain_cleanup et par le pointeur data, enregistrés précédemment par un appel à register_cleanup. data doit pointer vers la même zone mémoire que celle utilisée dans register_cleanup.

void ap_cleanup_for_exec(void)

Supprime tous les pools en utilisant des appels child_cleanup. Il va sans dire que cela ne doit être fait qu’après la création d’un processus fils non serveur, et avant de lancer son exécution. Un appel de cette fonction sur un serveur en cours d’exécution le stoppera certainement ! Sous Win32, cette fonction n’a aucun effet car il n’y a pas de processus fils. Malheureusement, il n’y a pas beaucoup d’alternatives.

void ap_note_cleanups_for_fd(pool *p, int fd)

Enregistre une fonction de nettoyage qui fermera le descripteur de fichier à la destruction du poll. Généralement, l’une des fonctions d’ouverture de fichier le fera pour vous, mais il est parfois nécessaire de le faire « manuellement ». Notez que les sockets ont leurs propres fonctions de nettoyage.

void ap_kill_cleanups_for_fd(pool *p, int fd)

Supprime les fonctions de nettoyage d’un descripteur de fichier enregistrées par ap_popenf( ), ap_pfopen( ), ap_pfdopen( ), ou ap_note_cleanups_for_fd( ). Généralement, cela est automatique lors de la fermeture du fichier, mais il peut être nécessaire de l’appeler explicitement.

void ap_note_cleanups_for_socket(pool *p, int fd)

Enregistre une fonction de nettoyage qui fermera la socket à la destruction du pool. Cette fonction est distincte de ap_note_cleanups_for_fd( ) car, sous Win32, les sockets et les descripteurs de fichiers ne sont pas équivalents.

void ap_kill_cleanups_for_socket(pool *p, int sock)

Supprime la fonction de nettoyage de la socket sock. Généralement, cette suppression est automatique lorsque la socket est fermée par ap_pclosesocket( ) mais, en certaines occasion, il peut être nécessaire de l’appeler explicitement.

void ap_note_cleanups_for_file(pool *p, FILE *f)

Enregistre une fonction de nettoyage qui ferme le flux lorsque le pool est détruit. Curieusement, il n’existe pas de fonction ap_kill_cleanups_for_file( ).

void ap_run_cleanup(pool *p, void *data, void (*cleanup)(void *))

Lance une fonction de nettoyage en lui passant les données data et en bloquant les signaux d’alarme. Il n’est habituellement pas nécessaire de l’appeler car les fonctions de nettoyage sont lancées automatiquement, mais cela peut servir pour du code de nettoyage personnalisé. La fonction de nettoyage est supprimée du pool p.

int ap_popenf(pool *p, const char *name, int flg, int mode)

Équivaut à l’appel système open( ), sauf qu’elle vérifie que le fichier est fermé lorsque le pool est détruit. Renvoie le descripteur du fichier ouvert, ou -1 en cas d’erreur.

int ap_pclosef(pool *p, int fd)

Ferme un fichier ouvert par ap_popenf( ). Renvoie la même valeur que l’appel système close( ) et supprime la fonction de nettoyage du fichier.

FILE *ap_pfopen(pool *p, const char *name, const char *mode)

Équivaut à la fonction fopen( ) de la bibliothèque standard du langage C, sauf qu’elle vérifie que le flux est fermé lorsque le pool est détruit. Renvoie un pointeur vers le nouveau flux, ou NULL en cas d’erreur.

FILE *ap_pfdopen(pool *p, int fd, const char *mode)

Équivaut à la fonction fdopen( ) de la bibliothèque standard du langage C, sauf qu’elle vérifie que le flux est fermé lorsque le pool est détruit. Renvoie un pointeur vers le nouveau flux, ou NULL en cas d’erreur.

int ap_pfclose(pool *p, FILE *fd)

Ferme le flux par un appel à fclose( ), en supprimant du pool sa fonction de nettoyage. Renvoie le résultat d’appel à fclose( ).

int ap_psocket(pool *p, int domain, int type, int protocol)

Ouvre une socket par un appel système socket( ) et enregistre une fonction de nettoyage pour fermer cette socket à la suppression du pool.

int ap_pclosesocket(pool *a, int sock)

Ferme la socket par un appel à closesocket( ) ou, selon le système, à close( ) et supprime du pool la fonction de nettoyage. Renvoie le résultat de l’appel à la fonction de fermeture de la socket.

regex_t *ap_pregcomp(pool *p, const char *pattern, int cflags)

Équivaut à l’appel de la fonction de la bibliothèque standard du langage C, regcomp( ), sauf que la mémoire utilisée est automatiquement libérée lors de la destruction du pool et que le paramètre regex_t * de regcomp( ) est créé dans le pool et renvoyé, au lieu d’être passé en paramètre.

char *ap_pregsub(pool *p, const char *input, const char *source, size_t nmatch, regmatch_t pmatch[])

Substitue les $0-$9 de input en utilisant source comme source des substitutions et pmatch pour déterminer le point à partir duquel substituer. nmatch, pmatch et source doivent être identiques à ceux qui seraient passés à la fonction standard du C, regexec( ). Renvoie la version substituée de input dans la mémoire allouée à partir de p.

void ap_pregfree(pool *p, regex_t * reg)

Libère l’expression régulière par un appel à la fonction standard de C, regfree( ), et supprime du pool sa fonction de nettoyage.

void ap_note_subprocess(pool *p, int pid, enum kill_conditions how)

Enregistre un processus fils pour qu’il soit supprimé lors de la destruction du pool. La façon dont il sera supprimé dépend du paramètre how :

int ap_spawn_child(pool *p, void(*func)(void *,child_info *), void *data, enum kill_conditions kill_how, FILE **pipe_in, FILE **pipe_out, FILE **pipe_err)

Cette fonction ne devrait pas être utilisée car elle est connue pour provoquer des erreurs avec les bibliothèques Microsoft de Win32. Utilisez plutôt ap_bspawn_child( ).

int ap_bspawn_child(pool *p, int (*func) (void *, child_info *), void *data, enum kill_conditions kill_how, BUFF **pipe_in, BUFF **pipe_out, BUFF **pipe_err)

Crée un processus fils en connectant éventuellement des tubes à son entrée, sa sortie et sa sortie des erreurs standard. Cette fonction s’occupe des détails du fork (si la plateforme en dispose) et de la configuration des tubes. func est appelée dans le processus fils avec les paramètres data et child_info. Cette dernière structure contient les informations nécessaires à la création d’un processus fils sous Win32 ; elle est normalement passée directement à ap_call_exec( ). Si func( ) veut qu’il y ait un nettoyage, elle appelle ap_cleanup_for_exec( ). func( ) exécutera normalement le processus fils par un appel à ap_call_exec( ). Si pipe_in, pipe_out, ou pipe_err vaut NULL, le tube correspondant n’est pas créé ; sinon, ils sont remplis par des pointeurs vers les BUFF connectés, respectivement, à l’entrée, la sortie et la sortie des erreurs standard.

Notez que, sous Win32, les tubes utilisent les descripteurs natifs de Win32 plutôt que des descripteurs de fichiers C. Cette fonction ne renvoie une valeur qu’au processus père : le PID du processus fils, ou -1 en cas d’erreur. Dans les versions précédentes d’Apache, cette fonction s’appelait spawn_child_err_buff( ).

int ap_call_exec(request_rec *r, child_info *pinfo, char *argv0, char **env,
int shellcmd)

Appelle exec( ) (ou une fonction de création de processus appropriée sur les plateformes ne disposant pas du fork) ou un wrapper setuid, selon que les wrappers setuid soient activés ou non. argv0 est le nom du programme à exécuter, env est un tableau terminé par NULL de chaînes qui seront utilisées comme environnement du programme lancé par exec( ). Si shellcmd est non-nul, la commande est lancée par un shell. Si r->args est configuré et ne contient pas de signe égale, il est passé comme un paramètre de la ligne de commande. pinfo doit être la structure passée par ap_bspawn_child( ). Cette fonction ne devrait rien renvoyer sur les plateformes disposant du fork. Elle renvoie le PID du nouveau processus sur les autres.

int ap_can_exec(const struct stat *finfo)

Renvoie une valeur non nulle si le fichier décrit par la structure finfo (telle qu’elle est renseignée par stat( ), etc.) peut être exécuté.

void ap_add_cgi_vars(request_rec *r)

Ajoute les variables d’environnement requises par la spécification CGI (celles-ci sont distinctes de celles ajoutées par ap_add_common_vars( ) ). On appelle cette fonction avant d’ exec( ) uter un CGI. ap_add_common_vars( ) devrait également être appelée.

void ap_add_common_vars(request_rec *r)

Ajoute les variables d’environnement communes à tous les sous-programmes lancés à la suite d’une requête. Habituellement, ap_add_cgi_vars( ) devrait également être appelée : la seule exception à notre connaissance concerne les programmes ISAPI.

int ap_scan_script_header_err(request_rec *r, FILE *f, char *buffer)

Lit les en-têtes provenant d’un CGI sur f et vérifie qu’ils sont corrects. La plupart des en-têtes sont simplement stockés dans r->headers_out, ce qui signifie qu’il seront finalement envoyés au client. Certains bénéficient d’un traitement spécial :

int ap_scan_script_header_err_buff(request_rec *r, BUFF *fb, char *buffer)

Cette fonction est similaire à ap_scan_script_header_err( ), sauf que le script CGI est connecté à un BUFF * au lieu d’un FILE *.

int ap_scan_script_header(request_rec *r, FILE *f)

Cette fonction est similaire à ap_scan_script_header_err( ), sauf qu’on ne lui passe pas de tampon d’erreur.

char *ap_md5(pool *p, unsigned char *string)

Calcule la valeur de hachage MD5 de string et renvoie la représentation ASCII héxadécimale de cette valeur (qui fait 33 octets, le caractère NUL final compris) allouée dans le pool p.

char *ap_md5contextTo64(pool *a, AP_MD5_CTX * context)

Prend la valeur de hachage MD5 contenue dans context (qui ne doit pas avoir été passé à une fonction ap_MD5Final ) et produit une représentation base-64 de celle-ci dans le pool a.

char *ap_md5digest(pool *p, FILE *infile)

Lit le fichier infile à partir de sa position courante jusqu’à la fin et renvoie un digest MD5 base-64 alloué dans le pool p. La position courante du fichier est remise au début après le calcul du digest.

void ap_MD5Init(AP_MD5_CTX *context)

Initialise context pour préparer un digest MD5.

void ap_MD5Final(unsigned char digest[16], AP_MD5_CTX *context)

Termine le traitement MD5 en écrivant le digest dans digest et en mettant context à zéro.

void ap_MD5Update(AP_MD5_CTX * context, const unsigned char *input, unsigned
int inputLen)

Traite inputLen octets de input en les ajoutant au digest calculé dans context.

ap_create_mutex création d’un objet d’exclusion mutuelle

ap_open_mutex ouverture d’un objet d’exclusion mutuelle

ap_acquire_mutex verrouillage d’un objet mutex ouvert

ap_release_mutex déverrouillage d’un mutex verrouillé

ap_destroy_mutex suppression d’un mutex ouvert

create_semaphore création d’un sémaphore

acquire_semaphore acquisition d’un sémaphore

release_semaphore libération d’un sémaphore

destroy_semaphore suppression d’un sémaphore

create_event création d’un événement

open_event ouverture d’un événement existant

acquire_event attente d’un événement

set_event déclenchement d’un événement

reset_event réinitialisation d’un événement

destroy_event suppression d’un événement ouvert

create_thread création d’un thread

kill_thread suppression d’un thread

await_thread attente de la fin d’un thread

exit_thread terminaison du thread en cours

free_thread libération des ressources d’un thread

char *ap_get_time(void)

Utilise un appel à ctime( ) pour formater la date et l’heure courantes en supprimant le retour à la ligne final. Renvoie un pointeur vers une chaîne contenant la date et l’heure.

char *ap_ht_time(pool *p, time_t t, const char *fmt, int gmt)

Formate la date et l’heure par un appel à strftime( ) et renvoie une copie allouée dans le pool. Si gmt est non nul, l’heure est exprimée en GMT ; sinon, elle utilise la zone horaire locale. Renvoie un pointeur vers la chaîne contenant la date et l’heure.

char *ap_gm_timestr_822(pool *p, time_t t)

Formate la date et l’heure selon le format de la RFC 822 ( Standard for the Format of ARPA Internet Text Messages ). La date et l’heure sont toujours exprimées en GMT. Renvoie un pointeur vers la chaîne contenant la date et l’heure.

struct tm *ap_get_gmtoff(long *tz)

Renvoie la date et l’heure locales et initialise tz avec le décalage en secondes de l’heure locale par rapport à GMT.

time_t ap_tm2sec(const struct tm *t)

Renvoie la date et l’heure stockées dans t sous la forme du nombre de secondes écoulées depuis le 1er janvier 1970 à minuit GMT. t est supposé être en GMT.

time_t ap_parseHTTPdate(const char *date)

Analyse une date et une heure exprimées dans l’un des trois formats suivants et renvoie l’équivalent en nombre de secondes écoulées depuis le 1er janvier 1970 à minuit GMT. Les trois formats possibles sont les suivants :

• Sun, 06 Nov 1994 08:49:37 GMT (RFC 822, mise à jour par la RFC 1123)
• Sunday, 06-Nov-94 08:49:37 GMT (RFC 850, rendue obsolète par la RFC 1036)
• Sun Nov 6 08:49:37 1994 (format de la fonction asctime( ) du C ANSI)

HTTP exigeant que les dates soient en GMT, cette fonction ignore le champ concernant la zone horaire.

int ap_strcmp_match(const char *str, const char *exp)

Compare str à exp. Les caractères * et ? peuvent être utilisés dans exp pour représenter, respectivement, « une suite quelconque de caractères » et « un caractère quelconque ». Utilisez plutôt les expressions régulières, plus modernes et plus puissantes. Renvoie 1 en cas de succcès, 0 en cas d’échec, -1 en cas d’erreur.

int ap_strcasecmp_match(const char *str, const char *exp)

Identique à ap_strcmp_match( ), mais sans tenir compte de la casse.

int ap_is_matchexp(const char *exp)

Renvoie 1 si exp contient * ou ? ; 0 sinon.

char *ap_ getword(pool *p, const char **line, char stop)
char *ap_ getword_nc(pool *p, char **line, char stop)

Recherche la première occurrence de stop dans *line et copie tout ce qui se trouve avant dans un nouveau tampon, qu’elle renvoie. Si *line ne contient pas stop, *line est copiée entièrement. Le pointeur *line est mis à jour pour pointer après l’occurrence de stop en ignorant les autres occurrences éventuelles. ap_getword_nc( ) est une version de ap_getword( ) prenant en paramètre un pointeur non constant : en effet; certains compilateurs C se plaignent lorsqu’un char ** est passé à une fonction qui attend un const char **.

char *ap_getword_white(pool *p, const char **line)
char *ap_getword_white_nc(pool *p, char **line)

Fonctionne comme ap_getword( ), sauf que les mots sont séparés par des espaces (tels qu’ils sont reconnus par isspace( ) ).

char *ap_getword_nulls(pool *p, const char **line, char stop)
char *ap_getword_nulls_nc(pool *p, char **line, char stop)

Fonctionne comme ap_getword( ), sauf que les occurrences multiples de stop ne sont pas ignorées : les entrées vides sont donc correctement traitées.

char *ap_ getword_conf(pool *p, const char **line)
char *ap_ getword_conf_nc(pool *p, char **line)

Fonctionne comme ap_ getword( ), sauf que les mots peuvent être séparés par des espaces et utiliser des apostrophes et des anti-slashes pour protéger les caractères. Ces apostrophes et ces anti-slashes sont supprimés.

char *ap_get_token(pool *p, const char **line, int accept_white)

Extrait un token de *line, en ignorant les espaces de tête. Le token est délimité par une virgule ou un point-virgule. Si accept_white vaut zéro, l’espace est également considéré comme délimiteur. Le token peut lui-même contenir des délimiteurs s’ils sont entourés d’apostrophes doubles, qui seront ôtées du résultats. Renvoie un pointeur vers le token extrait, qui a été alloué dans le pool p.

int ap_find_token(pool *p, const char *line, const char *tok)

Recherche tok dans line. Renvoie une valeur différente de zéro s’il a été trouvé. Le token doit correspondre exactement (à la casse près) et être délimité par des caractères de contrôle (tels qu’ils sont reconnus par iscntrl( ) ), des tabulations, des espaces, ou l’un des caractères suivants :

()<>@,;\\/[]?={}

Cela correspond à la définition d’un token dans la RFC 2068.

int ap_find_last_token(pool *p, const char *line, const char *tok)

Vérifie que la fin de line correspond à tok et que ce dernier est précédé d’un espace ou d’une virgule. Renvoie 1 en cas de succès, 0 sinon.

char *ap_escape_shell_cmd(pool *p, const char *s)

Préfixe les caractères dangereux de s par un anti-slash et renvoie la chaîne modifiée. L’ensemble actuel des caractères dangereux est le suivant :

&;`'\"|*?~<>^()[]{}$\\\n

Sous OS/2, & est converti en espace.

char *ap_uudecode(pool *p, const char *coded)

Renvoie une version décodée de coded, allouée dans p.

char *ap_escape_html(pool *p, const char *s)

Traite le code HTML contenu dans s pour que les caractères <, > et & s’affichent correctement. Renvoie un pointeur vers le code HTML ainsi traité.

int ap_checkmask(const char *data, const char *mask)

Teste si data correspond au masque mask, composé des caractères suivants :

void ap_str_tolower(char *str)

Convertit sur place str en minuscules.

char *ap_psprintf(pool *p, const char *fmt, ...)

Fonctionne exactement comme la fonction standard sprintf( ), sauf qu’on ne lui fournit pas de tampon : au lieu de cela, la nouvelle chaîne est allouée dans p, ce qui immunise totalement cette fonction contre les débordements de tampon. Voir également ap_vformatter( ).

char *ap_pvsprintf(pool *p, const char *fmt, va_list ap)

Comme ap_psprintf( ), sauf que l’on utilise une liste de paramètres variable.

int ap_ind(const char *s, char c)

Renvoie l’indice de la première occurrence de c dans s, ou -1 si s ne contient aucun c.

int ap_rind(const char *s, char c)

Renvoie l’indice de la dernière occurrence de c dans s, ou -1 si s ne contient aucun c.

void ap_ getparents(char *name)

Supprime les parties « . » et « .. » d’un chemin, tel que le précise la RFC 1808 ( Relative Uniform Resource Locators ). Cela est important, non seulement pour la sécurité, mais également pour effectuer des comparaisons correctes d’URL. Notez que Apache ne devrait jamais voir un chemin contenant de telles choses, mais il se comporterait correctement si la situation se présentait.

void ap_no2slash(char *name)

Supprime les doubles slashes d’un chemin. C’est important pour effectuer des comparaisons correctes d’URL.

char *ap_make_dirstr(pool *p, const char *path, int n)

Crée une copie de path qui est assurée de se terminer par un slash. La fonction tronquera le chemin au n ième slash. Renvoie un pointeur vers cette copie, qui est allouée dans le pool p.

char * ap_make_dirstr_parent(pool *p, const char *s)

Crée une chaîne dans p, contenant le chemin du répertoire père de s terminé par un slash.

char *ap_make_dirstr_prefix(char *d, const char *s, int n)

Copie les n premiers éléments du chemin s dans d, ou s en entier s’il est formé de moins de n éléments. Le slash de tête est considéré comme un élément.

int ap_count_dirs(const char *path)

Renvoie le nombre de slashes contenus dans un chemin.

void ap_chdir_file(const char *file)

Effectue un chdir( ) vers le répertoire contenant file. Pour ce faire, la fonction trouve le dernier slash dans file et se place dans le répertoire qui le précède. S’il n’y a aucun slash, elle tente un chdir( ) vers file. La fonction ne vérifie pas que le répertoire existe, ni que chdir( ) réussit.

int ap_unescape_url(char *url)

Reconvertit en caractères originaux les séquences d’échappement ( %xx ) contenues dans une URL. La conversion s’effectue sur place. La fonction renvoie 0 en cas de succès, BAD_REQUEST si elle a rencontré une séquence erronée et NOT_FOUND si elle a rencontré %2f (qui correspond au caractère « / »), ou %00.

char *ap_construct_server(pool *p, const char *hostname, int port, request_rec *r)

Crée la partie serveur d’une URL en ajoutant :<port> à hostname si port n’est pas le port par défaut du schéma de la requête.

char *ap_construct_url(pool *p, const char *uri, const request_rec *r)

Crée une URL en ajoutant le schéma utilisé par r avant le nom de serveur et le port de r et en ajoutant uri. Renvoie un pointeur vers l’URL ainsi créée.

char *ap_escape_path_segment(pool *p, const char *segment)

Renvoie une version protégée de segment, tel que cela est précisé dans la RFC 1808.

char *ap_os_escape_path(pool *p, const char *path, int partial)

Renvoie une version protégée de path, comme il est précisé dans la RFC 1808. Si partial est non nul, le chemin est censé être un chemin partiel terminal (un « ./ » ne peut servir à cacher un « : »).

int ap_is_directory(const char *path)

Renvoie une valeur non nulle si path représente un répertoire.

int ap_os_is_path_absolute(const char *file)

Renvoie 1 si file est un chemin absolu, 0 sinon.

char *ap_make_full_path(pool *p, const char *path1, const char *path2)

Ajoute path2 à la suite de path1, en vérifiant qu’il n’y a qu’un slash entre eux. Renvoie un pointeur vers le nouveau chemin ainsi formé.

int ap_is_url(const char *url)

Renvoie une valeur non nulle si url est une URL. Ici, une URL est définie comme étant « <une chaîne de nombres, de lettres, les caractères +, - ou . (point)>:<n’importe quoi>. ».

int ap_fnmatch(const char *pattern, const char *string, int flags)

Compare string à pattern et renvoie 0 s’ils correspondent et FNM_NOMATCH sinon. pattern peut contenir les caractères suivants :

int ap_is_fnmatch(const char *pattern)

Renvoie 1 si pattern contient ?, *, ou [...] ; 0 sinon.

char *ap_server_root_relative(pool *p, char *file)

Si file n’est pas un chemin absolu, cette fonction l’ajoute à la racine du serveur dans le pool p. S’il est absolu, elle se contente de le renvoyer (ce n’est pas une copie).

char *ap_os_canonical_filename(pool *pPool, const char *szFile)

Renvoie une forme canonique d’un nom de fichier. Cela est nécessaire pour certains systèmes d’exploitation qui acceptent plusieurs chaînes pour désigner le même fichier. Win32, par exemple, n’est pas sensible à la casse, ignore les points et les espaces en début de nom, etc. Cette fonction est généralement utilisée avant de comparer un nom de fichier à un motif ou autres opérations similaires.

uid_t ap_uname2id(const char *name)

Si name commence par un « # », renvoie le nombre qui le suit ; sinon, appelle getpwnam( ) et renvoie l’UID correspondant à name. Sous Win32, cette fonction renvoie toujours 1.

gid_t ap_ gname2id(const char *name)

Si name commence par un « # », renvoie le nombre qui le suit ; sinon, appelle getgrnam( ) et renvoie le GID correspondant à name. Sous Win32, cette fonction renvoie toujours 1.

unsigned long ap_get_virthost_addr(const char *hostname, short *ports)

Convertit un nom d’hôte de la forme nom [: port ] en une adresse IP stockée selon l’ordre réseau, qui est alors renvoyée. *ports contient le numéro de port s’il n’est pas NULL. Si nom est absent ou vaut « * », la fonction renvoie INADDR_ANY. Si port est absent ou vaut « * », *ports est initialisé à 0.

Si l’hôte a plusieurs adresses IP, un message d’erreur est produit et exit( ) est appelé.

char *ap_ get_local_host(pool *p)

Renvoie un pointeur vers le nom pleinement qualifié de l’hôte local. Produit un message en cas d’erreur et appelle exit( ).

const char *ap_get_remote_host(conn_rec *conn, void *dir_config, int type)

Renvoie le nom d’hôte ou l’adresse IP (sous forme de chaîne) du client. dir_config est le champ per_dir_config de la requête courante, ou vaut NULL. type a l’une des valeurs suivantes :

long ap_send_fd(FILE *f, request_rec *r)

Envoie le flux f au client et renvoie le nombre d’octets envoyés.

long ap_send_fd_length(FILE *f, request_rec *r, long length)

N’envoie pas plus de length octets de f au client. Si length est négatif, envoie le fichier entier. Renvoie le nombre d’octets envoyés.

long ap_send_fb(BUFF *fb, request_rec *r)

Comme ap_send_fd( ), sauf que l’on envoie un BUFF * au lieu d’un FILE *.

long ap_send_fb_length(BUFF *fb, request_rec *r, long length)

Comme ap_send_fd_length( ), sauf que l’on envoie un BUFF * au lieu d’un FILE *.

size_t ap_send_mmap(void *mm, request_rec *r, size_t offset, size_t length)

Envoie length octets de mm+offset au client. Les données sont envoyées par paquets de MMAP_SEGMENT_SIZE octets et le délai d’expiration est réinitialisé entre chaque paquet. Bien que cette fonction puisse être utilisée avec n’importe quel tampon mémoire, elle est réellement conçue pour utiliser les fichiers mappés en mémoire (ce qui peut être plus performant que les autres méthodes d’envoi sur certaines plateformes).

int ap_rwrite(const void *buf, int nbyte, request_rec *r)

Envoie nbyte octets de buf au client. Renvoie le nombre d’octets envoyés ou -1 en cas d’erreur.

int ap_rputc(int c, request_rec *r)

Envoie le caractère c au client. Renvoie c, ou EOF si la connexion a été fermée.

int ap_rputs(const char *s, request_rec *r)

Envoie la chaîne s au client. Renvoie le nombre d’octets envoyés ou -1 en cas d’erreur.

int ap_rvputs(request_rec *r, ...)

Envoie la liste de chaînes au client (cette liste est terminée par NULL ). Renvoie le nombre d’octets envoyés ou -1 en cas d’erreur.

int ap_rprintf(request_rec *r, const char *fmt,...)

Formate les paramètres supplémentaires selon fmt (comme le ferait printf( ) ) et envoie la chaîne résultante au client. Renvoie le nombre d’octets envoyés ou -1 en cas d’erreur.

int ap_rflush(request_rec *r)

Force l’envoi au client de toutes les données du tampon. Renvoie 0 en cas de succès ou -1 en cas d’erreur.

int ap_setup_client_block(request_rec *r, int read_policy)

Se prépare à recevoir (ou à ne pas recevoir, selon la valeur de read_policy ) des données provenant du client, généralement parce que le client à émis une requête PUT ou POST. Vérifie que tout est prêt pour la réception et renvoie OK si c’est le cas ou un code d’état sinon. Cette fonction renverra quand même OK si la requête ne contient pas de données du client. Elle doit être appelée avant ap_should_client_block( ).

read_policy a l’une des valeurs suivantes :

int ap_should_client_block(request_rec *r)

Teste si le client enverra des données et l’invite à continuer si nécessaire (en envoyant une réponse 100 Continue si le client utilise HTTP 1.1 ou supérieur). Renvoie 1 si le client doit envoyer des données, 0 sinon. ap_setup_client_block( ) doit être appelée avant cette fonction, qui doit elle-même être appelée avant ap_get_client_block( ). Elle ne doit être utilisée qu’une seule fois et pas avant que nous ne soyons prêt à recevoir des données provenant du client.

long ap_ get_client_block(request_rec *r, char *buffer, int bufsiz)

Lit jusqu’à bufsiz caractères provenant du client dans buffer. Renvoie le nombre d’octets lus, 0 s’il n’y a plus de données, ou -1 en cas d’erreur. ap_setup_client_block( ) et ap_should_client_block( ) doivent avoir été appelées avant cette fonction. Le tampon buffer doit être suffisamment grand pour contenir une ligne d’en-tête de la taille d’un chunk (car il peut servir à en stocker une temporairement). Comme une telle ligne d’en-tête est simplement un nombre en héxadécimal, 50 octets devraient largement suffire.

void ap_send_http_header(request_rec *r)

Envoie les en-têtes (provenant essentiellement de r->headers_out ) au client. Il est essentiel d’effectuer cet appel dans un handler de requête avant d’envoyer le contenu.

void ap_send_size(size_t size, request_rec *r)

Envoie size au client en l’arrondissant au millier, million, etc. le plus proche. Si size vaut -1, ne produit qu’un signe moins.

request_rec *ap_sub_req_lookup_uri(const char *new_uri, const request_rec *r)

Fournit new_uri au système afin de produire une nouvelle structure request_rec, qui a été traitée juste avant le point où le handler de requête serait appelé. Si l’URI est relative, elle est résolue relativement à l’URI de r. Renvoie la nouvelle structure ainsi produite. Le champ status du résultat contient le code d’erreur éventuel.

request_rec *ap_sub_req_lookup_file(const char *new_file, const request_rec *r)

Comme ap_sub_req_lookup_uri( ), sauf que cette fonction traite un fichier et qu’elle n’appelle donc pas les traducteurs de nom, ni n’effectue de comparaisons avec les conteneurs <Location>.

int ap_run_sub_req(request_rec *r)

Exécute une sous-requête préparée avec ap_sub_req_lookup_file( ) ou ap_sub_req_lookup_uri( ). Renvoie le code d’état du handler de requête.

void ap_destroy_sub_req(request_rec *r)

Supprime une sous-requête créée avec ap_sub_req_lookup_file( ) ou ap_sub_req_lookup_uri( ) et libère la mémoire qui lui était associée. Il va sans dire que vous devez copiez ce que vous souhaitez obtenir d’une sous-requête avant de la détruire.

void ap_internal_redirect(const char *uri, request_rec *r)

Redirige en interne une requête pour uri. La requête est traitée immédiatement plutôt que de renvoyer un code de redirection au client.

void ap_internal_redirect_handler(const char *uri, request_rec *r)

Comme ap_internal_redirect( ), mais utilise le handler indiqué par r.

void ap_hard_timeout(char *name, request_rec *r)

Fixe une alarme qui se déclenchera lorsque le délai d’expiration configuré dans le serveur expirera. Lorsque l’alarme se déclenche, la requête en cours est abandonnée en effectuant un longjmp( ) revenant au niveau le plus haut et en supprimant tous les pools de la requête r. La chaîne name est alors inscrite dans le fichier log des erreurs.

ap_keepalive_timeout

void ap_keepalive_timeout(char *name, request_rec *r)

Fonctionne comme ap_hard_timeout( ), sauf que si la requête se poursuit, cette fonction utilise le délai d’expiration du keepalive au lieu de celui du serveur. Elle devrait normalement être utilisée lorsque l’on attend une requête d’un client et donc uniquement dans http_protocol.c, mais on l’a mise ici pour être complets.

void ap_soft_timeout(char *name, request_rec *r)

Comme ap_hard_timeout( ), sauf que la requête qui est détruite n’est pas indiquée. Le paramètre r n’est pas utilisé (il est encore là pour des raisons historiques).

void ap_reset_timeout(request_rec *r)

Réinitialise le délai d’expiration hard ou soft à ce qu’il valait initialement. C’est comme si vous aviez appelé ap_hard_timeout( ) ou ap_soft_timeout( ) une seconde fois.

void ap_kill_timeout(request_rec *r)

Annule le délai d’expiration en cours sur la requête r.

void ap_block_alarms(void)

Bloque temporairement les délais d’expiration en cours. Protège les sections critiques qui gaspilleraient des ressources (ou se comporteraient mal d’une façon ou d’une autre) si le délai qui leur est imparti expirait avant la fin de leur exécution. Les appels à cette fonction peuvent être imbriqués, mais chaque appel doit avoir un appel à ap_unblock_alarms( ) qui lui correspond.

void ap_unblock_alarms(void)

Supprime un blocage provoqué par ap_block_alarms( ).

int ap_check_alarm(void)

Comme Win32 n’a pas de fonction alarm( ), il faut vérifier les alarmes « à la main ». Cette fonction effectue cette opération en appelant la fonction d’alarme configurée avec l’une des fonctions d’expiration. Renvoie -1 si l’alarme a été déclenchée, le nombre de secondes restant avant son déclenchement, ou 0 si aucune alarme n’est configurée.

configfile_t *ap_pcfg_openfile(pool *p, const char *name)

Ouvre le fichier name (en appellant fopen( ) ). Renvoie NULL si l’ouverture a échoué, ou un pointeur vers une configuration si elle a réussi.

configfile_t *ap_pcfg_open_custom(pool *p, const char *descr, void *param,
int(*getch)(void *param), void *(*getstr) (void *buf, size_t bufsiz, void *param),
int(*close_func)(void *param))

Crée une configuration personnalisée. La fonction getch( ) doit lire un caractère de la configuration et le renvoyer (ou EOF si elle a atteint la fin). La fonction getstr( ), si elle est fournie (elle peut valoir NULL, auquel cas getch( ) sera utilisée à la place), doit lire une ligne complète et la placer dans buf en la terminant par le caractère NUL ; elle doit renvoyer buf, ou NULL si la fin de la configuration est atteinte. close_func( ), si elle est fournie (elle peut valoir NULL ), doit fermer la configuration et renvoyer une valeur supérieure ou égale à 0 en cas de succès. param est passé en paramètre à toutes ses fonctions.

int ap_cfg_getc(configfile_t *cfp)

Lit un caractère unique dans cfp. Si ce caractère est une fin de ligne, le numéro de ligne est incrémenté. Renvoie le caractère lu, ou EOF si la fin de la configuration a été atteinte.

int ap_cfg_getline(char *s, int n, configfile_t *cfp)

Lit une ligne (jusqu’à n caractères) de cfp et la place dans s en supprimant les espaces de tête et de fin et en convertissant les espaces internes en caractères espaces uniques. Les lignes de continuation (indiquées par un antislash en fin de ligne) sont concaténées. Renvoie normalement 0, ou 1 si la fin de la configuration a été atteinte.

int ap_cfg_closefile(configfile_t *cfp)

Ferme la configuration cfp. Renvoie une valeur négative en cas d’erreur.

const char *ap_check_cmd_context(cmd_parms *cmd, unsigned forbidden)

Vérifie si la commande cmd est autorisée dans le contexte de configuration en cours, selon la valeur de forbidden. Renvoie NULL si elle est autorisée ou un message d’erreur approprié sinon. forbidden doit être une combinaison des valeurs suivantes :

const char *ap_set_file_slot(cmd_parms *cmd, char *struct_ptr, char *arg)

Cette fonction est conçue pour être utilisée dans un command_rec en créant une chaîne à partir d’un fichier. Elle s’attend à être utilisée avec une commande TAKE1. Si le nom de fichier n’est pas absolu, il est considéré comme relatif à la racine du serveur. Le champ correspondant dans la structure doit évidemment être de type char *.

const char * ap_set_flag_slot(cmd_parms *cmd, char *struct_ptr, int arg)

Cette fonction est conçue pour être utilisée dans un command_rec pour initialiser une option. Elle s’attend à être utilisée avec une commande FLAG. Le champ correspondant dans la structure doit être de type int et sera initialisé à 0 ou 1.

const char *ap_set_string_slot(cmd_parms *cmd, char *struct_ptr, char *arg)

Cette fonction est conçue pour être utilisée dans un command_rec en initialisant une chaîne. Elle s’attend à être utilisée avec une commande TAKE1. Le champ correspondant dans la structure doit évidemment être de type char *.

const char *ap_set_string_slot_lower(cmd_parms *cmd, char *struct_ptr, char *arg)

Comme ap_set_string_slot( ), sauf que la chaîne est mise en minuscules.

int ap_allow_options (request_rec *r)

Renvoie l’ensemble des options de la requête r. Le résultat est une suite de bits formée par le OU bit à bit des valeurs suivantes :

int ap_allow_overrides (request_rec *r)

Renvoie les surcharges autorisées pour la requête r. Le résultat est le OU bit à bit des valeurs suivantes :

const char *ap_auth_type (request_rec *r)

Renvoie le type d’authentification (tel qu’il est configuré par la directive AuthType ) pour la requête r. Actuellement, il ne peut s’agir que de Basic, Digest, ou NULL.

const char *ap_auth_name (request_rec *r)

Renvoie le nom du domaine d’authentification (tel qu’il est configuré par la directive AuthName ) pour la requête r.

const array_header *ap_requires (request_rec *r)

Renvoie le tableau des require_line de la requête r correspondant à la directive require. Un require_line est définie de la façon suivante :

typedef struct {

int method_mask;

char *requirement;

} require_line;

method_mask est un OU bit à bit des valeurs suivantes :

1 << M_GET

1 << M_PUT

1 << M_POST

1 << M_DELETE

1 << M_CONNECT

1 << M_OPTIONS

1 << M_TRACE

1 << M_INVALID

telles qu’elles sont configurées par une directive Limit.

int ap_satisfies (request_rec *r)

Renvoie la configuration de satisfy pour la requête r. Cela peut être l’une des valeurs suivantes :

const char *ap_ get_server_built(void)

Renvoie une chaîne contenant la date et l’heure de compilation du serveur. Comme cette fonction utilise les variables __DATE__ et __TIME__ du préprocesseur C, le format dépend du système. Si le préprocesseur ne reconnaît pas __DATE__ ou __TIME__, la chaîne renvoyée est « unknown ».

const char *ap_get_server_version( )

Renvoie une chaîne contenant la version d’Apache (ainsi que les chaînes de version des modules qui ont été ajoutés).

void ap_add_version_component(const char *component)

Ajoute une chaîne à la chaîne de version du serveur. Cette fonction n’a d’effet qu’au démarrage, après que la chaîne de version ait été verrouillée. Les chaînes de version sont de la forme nom du module / numéro de version, MonModule/1.3 par exemple. Beaucoup de modules n’ajoutent pas de chaîne de version.

void ap_error_log2stderr (server_rec *s)

Utilise stderr comme fichier log des erreurs du serveur s. Cela est notamment utile lorsque l’on lance un sous-processus.

void ap_log_error (const char *file, int line, int level, const server_rec *s,
const char *fmt, ...)

Inscrit une erreur dans les logs (si level est supérieur au niveau configuré par la directive LogLevel ). file et line ne sont mentionnés que si level vaut APLOG_DEBUG. Ces deux paramètres sont généralement initialisés par un appel à ap_log_error( ) :

ap_log_error(APLOG_MARK, APLOG_ERR, conf_server_conf, "une erreur");

APLOG_MARK est une macro #define qui utilise __FILE__ et __LINE__ pour produire le nom de fichier et le numéro de ligne de l’appel.

level est une des valeurs suivantes :

void ap_log_reason (const char *reason, const char *file, request_rec *r)

Inscrit dans les logs un message de la forme « access to file failed for remotehost, reason: reason ». L’hôte distant remotehost est extrait de r. Le message est écrit par ap_log_error( ) avec un niveau APLOG_ERR.

piped_log *ap_open_piped_log (pool *p, const char *program)

Lance le programme program avec les tubes appropriés. program peut contenir des paramètres.

void ap_close_piped_log (piped_log *pl)

Ferme pl mais n’interrompt pas le processus fils qui a été lancé.

int ap_piped_log_write_fd(piped_log *pl)

Renvoie le descripteur de fichier d’un log pipeliné ouvert.

BUFF *ap_bcreate(pool *p, int flags)

Crée un flux tamponné dans p. Pour le moment, le flux n’est associé à aucun fichier ni à aucune socket. flags peut prendre l’une des valeurs suivantes :

void ap_bpushfd(BUFF *fb, int fd_in, int fd_out)

Configure le descripteur de fichier d’entrée à fd_in et celui de sortie à fd_out. Utilisez -1 pour les descripteurs de fichiers que vous ne souhaitez pas initialiser. Ces descripteurs doivent être lisibles par read( ) et on doit pouvoir y écrire par write( ).

void ap_bpushh(BUFF *fb, HANDLE hFH)

Configure un descripteur de fichier Win32 à la fois pour l’entrée et la sortie. On écrira dans le descripteur avec WriteFile( ) et on y lira avec ReadFile( ). Cette fonction ne doit pas être utilisée pour une socket, bien qu’une socket soit un descripteur Win32 : il faut utiliser ap_bpushfd( ).

int ap_bsetopt(BUFF *fb, int optname, const void *optval)

Configure l’option optname avec la valeur pointée par optval. Il n’y a, actuellement, qu’une seule option : le nombre d’octets envoyés dans le flux, configuré avec BO_BYTECT. Dans ce cas, optval doit pointer vers un long. Cette fonction sert aux logs et aux statistiques et n’est généralement pas appelée par les modules. Son utilisation principale consiste à remettre à zéro ce nombre après l’envoi des en-têtes à un client. Elle renvoie 0 en cas de succès, -1 sinon.

int ap_bgetopt(BUFF *fb, int optname, void *optval)

Récupère la valeur de l’option optname dans l’emplacement pointé par optval. La seule option reconnue est BO_BYTECT (voir ap_bsetopt( ) ).

int ap_bsetflag(BUFF *fb, int flag, int value)

Si value vaut 0, supprime flag ; le positionne, sinon. flag est l’un des indicateurs suivants :

int ap_bgetflag(BUFF *fb, int flag)

Renvoie 0 si flag n’est pas positionné ; une valeur différente de zéro sinon. Voir ap_bsetflag( ) pour la liste des différents indicateurs.

void ap_bonerror(BUFF *fb, void (*error) (BUFF *, int, void *),void *data)

Si une erreur survient sur fb, appelle error() avec les paramètres fb, la direction ( B_RD ou B_WR ) et data.

int ap_bnonblock(BUFF *fb, int direction)

direction vaut B_RD ou B_WR. Configure le descripteur de fichier indiqué en mode non bloquant. Renvoie le résultat de l’appel à fcntl( ).

int ap_bfileno(BUFF *fb, int direction)

direction vaut B_RD ou B_WR. Renvoie le descripteur de fichier correspondant à fb.

int ap_bread(BUFF *fb, void *buf, int nbyte)

Lit jusqu’à nbyte octets dans fb et les place dans buf. Renvoie le nombre d’octets lus, 0 en cas de fin de fichier (EOF), ou -1 en cas d’erreur. Ne lit que les données disponibles au moment de l’appel.

int ap_bgetc(BUFF *fb)

Lit un seul caractère dans fb. Renvoie ce caractère en cas de succès, ou EOF en cas d’erreur ou de rencontre de la fin de fichier. Si ce EOF résulte d’une fin de fichier, errno vaudra zéro.

int ap_bgets(char *buff, int n, BUFF *fb)

Lit jusqu’à n-1 octets dans fb et les place dans buff. La lecture s’arrête à la rencontre d’un caractère LF ( Line Feed ) ou de la fin de fichier. Si le LF est précédé d’un caractère CR ( Carriage Return ), ce CR est supprimé. Le tampon est ensuite terminé par un caractère NUL. Renvoie le nombre d’octets stockés dans le tampon, non compté le caractère NUL.

int ap_blookc(char *buff, BUFF *fb)

Place le caractère suivant du flux dans le tampon *buff, sans le supprimer du flux. Renvoie 1 en cas de succès, 0 si l’on a rencontré la fin du fichier et -1 en cas d’erreur.

int ap_bskiplf(BUFF *fb)

Supprime les entrées jusqu’à la lecture d’un LF. Renvoie 1 en cas de succès, 0 si l’on a rencontré la fin de fichier et -1 en cas d’erreur. Le flux doit être tamponné en lecture (c’est-à-dire dans le mode B_RD ou B_RDWR )

int ap_bwrite(BUFF *fb, const void *buf, int nbyte)

Écrit nbyte octets du tampon buf dans fb. Renvoie le nombre d’octets écrits, qui ne peut qu’être inférieur à nbyte s’il y a eu une erreur. Si l’indicateur B_CHUNK est positionné, cette fonction prend en compte l’encodage chunked.

int ap_bputc(char c, BUFF *fb)

Écrit c dans fb et renvoie 0 en cas de succès, ou -1 en cas d’erreur.

int ap_bputs(const char *buf, BUFF *fb)

Écrit le contenu de buf jusqu’au premier caractère NUL (non inclus). Renvoie le nombre d’octets écrits, ou -1 en cas d’erreur.

int ap_bvputs(BUFF *fb,...)

Écrit le contenu d’une liste de tampons comme le fait ap_bputs( ). La liste des tampons est terminée par NULL. Renvoie le nombre total d’octets écrits, ou -1 en cas d’erreur. Exemple d’utilisation :

if(ap_bvputs(fb, buf1, buf2, buf3, NULL) < 0)
...

int ap_bprintf(BUFF *fb, const char *fmt, ...)

Écrit dans le flux fb en utilisant le format défini par fmt. Renvoie le nombre d’octets envoyés au flux.

int ap_vbprintf(BUFF *fb, const char *fmt, va_list ap)

Comme ap_bprintf( ), mais utilise une liste de paramètres variables au lieu de « ... ».

int ap_bflush(BUFF *fb)

Force les tampons de sortie de fb. Renvoie 0 en cas de succès, ou -1 en cas d’erreur. Le fichier doit être tamponné en écriture (c’est-à-dire dans le mode B_WR ou B_RDWR ).

int ap_bclose(BUFF *fb)

Force le tampon de sortie et ferme le descripteurs de fichier/socket sous-jacent. Renvoie 0 en cas de succès, ou -1 en cas d’erreur.

int ap_parse_uri_components(pool *p, const char *uri, uri_components *uptr)

Découpe l’URI uri en ses différentes composantes, qui sont alors placées dans uptr. Chaque composante est allouée dans p et toute partie manquante est initialisée à NULL. uptr->is_initialized est initialisé à 1.

int ap_parse_hostinfo_components(pool *p, const char *hostinfo, uri_components *uptr)

Il est parfois nécessaire d’analyser host:port -- lorsque, par exemple, on traite une requête CONNECT. Cette fonction le fait en initialisant uptr->hostname, uptr->port_str et uptr->port (si la composante port est présente). Tous les autres éléments sont initialisés à NULL.

char *ap_unparse_uri_components(pool *p, const uri_components *uptr, unsigned flags)

Prend en paramètre une structure uri_components remplie, uptr, et crée une chaîne contenant l’URI correspondante. La chaîne est allouée dans p. Le paramètre flags est nul ou est une combinaison des valeurs suivantes :

struct hostent *ap_pgethostbyname(pool *p, const char *hostname)

Effectue essentiellement le même traitement que la fonction standard gethostbyname( ), sauf que le résultat est alloué dans p au lieu d’être temporaire.

struct hostent *ap_pduphostent(pool *p, const struct hostent *hp)

Duplique hp (et tout ce vers quoi il pointe) dans le pool p.

void ap_child_terminate(request_rec *r)

Termine cette instance d’Apache après le traitement de la requête en cours. Si la connexion est persistante, la persistance est annulée.

unsigned short ap_default_port(request_rec *r)

Renvoie le numéro du port par défaut pour la requête gérée par r. En Apache standard, il s’agit toujours d’une requête HTTP : le résultat doit donc toujours être 80 mais, avec Apache-SSL par exemple, il dépend du protocole utilisé, qui peut être HTTP ou HTTPS.

int ap_is_default_port(int port, request_rec *r)

Renvoie 1 si port est le port par défaut pour r ; 0 sinon.

unsigned short ap_default_port_for_scheme(const char *scheme_str)

Renvoie le port par défaut du schéma scheme.

const char *ap_http_method(request_rec *r)

Renvoie le schéma par défaut pour la requête gérée par r. En Apache standard, il s’agit toujours d’une requête HTTP : le résultat est donc toujours http mais, avec Apache-SSL par exemple, il dépend du protocole utilisé, qui peut être HTTP ou HTTPS.

const char *ap_default_type(request_rec *r)

Renvoie le type de contenu par défaut pour la requête r. Il est configuré par la directive DefaultType ou vaut text/plain.

int ap_get_basic_auth_pw(request_rec *r, const char **pw)

Si un mot de passe a été mis en place pour l’authentification de base (par le client), son adresse est mise dans *pw. La fonction renvoie une des valeurs suivantes :

void *ap_get_module_config(void *conf_vector, module *m)

Récupère la configuration spécifique à un module, qu’il a mise en place au démarrage. conf_vector est généralement soit le per_dir_config d’une structure request_rec, soit le module_config d’une structure server_rec. Voir le chapitre 21 pour plus d’informations.

const char *ap_get_remote_logname(request_rec *r)

Renvoie le nom de connexion de l’utilisateur du client si elle peut le trouver et si cette fonctionnalité a été activée par la directive IdentityCheck. Sinon, cette fonction renvoie NULL.

const char *ap_get_server_name(const request_rec *r)

Récupère le nom du serveur qui traite r. Si la directive UseCanonicalName est activée, cette fonction renvoie le nom configuré dans le fichier de configuration. Sinon, elle renvoie celui utilisé dans la requête, s’il y en a un, ou le nom configuré sinon.

unsigned ap_get_server_port(const request_rec *r)

Si UseCanonicalName est activée, cette fonction renvoie le port configuré pour le serveur qui traite r. Sinon, elle renvoie le port de la connexion si la requête contient un nom d’hôte, ou le port configuré sinon.

int ap_is_initial_req(request_rec *r)

Renvoie 1 si r est la structure request_rec principale (et non une sous-requête ou une redirection interne), 0 sinon.

int ap_matches_request_vhost(request_rec *r, const char *host, unsigned port)

Renvoie 1 si host : port correspond à l’hôte virtuel qui traite r, 0 sinon.

void *ap_os_dso_load(const char *path)

Charge l’objet partagé dynamique (une DLL, une bibliothèque partagée, etc.) désigné par path. Ces objets ont des implémentations dépendantes de la plateforme. La valeur renvoyée est un descripteur pouvant être utilisé avec les autres fonctions sur les DSO. Renvoie NULL si path n’a pas pu être chargé.

void *ap_os_dso_sym(void *handle, const char *symname)

Renvoie l’adresse de symname dans l’objet partagé dynamique désigné par handle. Si la plateforme modifie les symboles d’une façon ou d’une autre (en les préfixant d’un blanc souligné, par exemple), cette fonction fait la même modification avant d’effectuer la recherche. Renvoie NULL si symname n’a pas été trouvé ou si une erreur est survenue.

const char *ap_os_dso_error(void)

Renvoie la chaîne décrivant le problème si une erreur est survenue dans une fonction DSO, NULL sinon.

DIR *ap_popendir(pool *p, const char *name)

Cette fonction est quasiment identique à la fonction standard opendir( ), sauf qu’elle enregistre une fonction de nettoyage qui effectuera un closedir( ). Un DIR créé par cette fonction devrait être fermé par ap_pclosedir( ) (ou fermé par la fonction de nettoyage). Cela mis à part, on utilisera les fonctions standard.

void ap_pclosedir(pool *p, DIR * d)

Appelle closedir( ) et annule la fonction de nettoyage enregistrée par ap_popendir( ). Cette fonction ne doit être appelée que sur un DIR créé par ap_popendir( ).

const char *ap_psignature(const char *prefix, request_rec *r)

Crée une « signature » pour le serveur qui traite r. Selon la valeur de la directive ServerSignature, cette signature peut être vide, contenir le nom et le port du serveur, ou le nom du serveur et un lien vers l’adresse de courrier électronique de l’administrateur. Si ServerSignature est activée, la chaîne renvoyée est préfixée par prefix.

int ap_vformatter(int (*flush_func)(ap_vformatter_buff *),
ap_vformatter_buff *vbuff, const char *fmt, va_list ap)

Comme Apache utilise différentes fonctions de formatage ( ap_bprintf( ), ap_psprintf( ) ) et qu’il n’est pas possible de les implémenter de façon sûre avec les fonctions standard, Apache possède ses propres fonction à la printf( ), que l’on accède via celle-ci. Elle prend en paramètre une fonction de forçage de tampon et une structure ap_vformatter_buff, qui est définie de la façon suivante :

typedef struct {

char *curpos;

char *endpos;

} ap_vformatter_buff;

Elle prend également en paramètre la chaîne de format habituelle, fmt, et une liste variable de paramètres, ap. ap_vformatter( ) remplit le tampon (pointé par vbuff->curpos ) jusqu’à ce que vbuff->curpos == vbuff->endpos. Puis, elle appelle flush_func( ) en lui passant vbuff en paramètre. flush_func( ) doit vider le tampon et réinitialiser les champs de vbuff pour permettre au formatage de s’effectuer ; elle n’est pas appelée lorsque le formatage est terminé (sauf si le tampon est plein). Il est de la responsabilité de l’appelant de tout terminer.

Comme flush_func( ) a quasiment toujours besoin de plus d’informations que celles se trouvant dans vbuff, on utilise souvent l’horrible bidouille suivante : on définit une structure contenant un ap_vformatter_buff comme premier champ :

struct donnees_supp {

ap_vformatter_buff vbuff;

int donnees_supplementaires;

...

};

Puis, la fonction à la printf( ) appelle ap_vformatter( ) en lui passant une instance de cette structure :

struct donnees_supp amoi;

...

amoi.donnees_supplementaires=123;

ap_vformatter(mon_flush, &amoi.vbuff, fmt, ap);

...

Enfin, mon_flush( ) exécute ce code :

API_EXPORT(int) mon_flush(ap_vformatter_buff *vbuff)

{

truct donnees_supp *pamoi = (struct donnees_supp *)vbuff;

assert(pamoi->donnees_supplementaires == 123);

...

Comme vous vous en doutez sûrement, nous n’approuvons pas totalement cette technique, mais elle fonctionne.

ap_vformatter( ) utilise les spécificateurs de format habituels, sauf que %p a été remplacé par %pp, %pA formate une struct in_addr * sous la forme a.b.c.d, et %pI formate une struct sockaddr_in * sous la forme a.b.c.d:port. La raison de la présence de ces étranges spécificateurs de format est qu’ils tirent parti des vérifications effectuées par gcc sur la chaîne de format, qui garantissent que %p correspond à un pointeur.