From: Daniel Gruno Date: Tue, 24 Apr 2012 18:12:25 +0000 (+0000) Subject: Changing to the new syntax highlighting WRT C source code X-Git-Tag: 2.5.0-alpha~7060 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=61aa7600bf1aa74f1acd0364258c23ebefef5435;p=thirdparty%2Fapache%2Fhttpd.git Changing to the new syntax highlighting WRT C source code git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1329909 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/developer/hooks.html.en b/docs/manual/developer/hooks.html.en index e6fd42cddc9..9e9e71e9f1b 100644 --- a/docs/manual/developer/hooks.html.en +++ b/docs/manual/developer/hooks.html.en @@ -49,9 +49,10 @@ arguments. For example, if the hook returns an int and takes a request_rec * and an int and is called do_something, then declare it like this:

-

+ 

         AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))
-
+ +

This should go in a header which modules will include if they want to use the hook.

@@ -62,14 +63,13 @@ which is used to record the module functions that use the hook. This is declared as follows:

-

- APR_HOOK_STRUCT(
- - APR_HOOK_LINK(do_something)
- ...
- + 

+        APR_HOOK_STRUCT(
+          APR_HOOK_LINK(do_something)
+          ...
         )
-
+ +

Implement the hook caller

@@ -82,33 +82,34 @@

If the return value of a hook is void, then all the hooks are called, and the caller is implemented like this:

-

+ 

           AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))
-
+ +

The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:

-

- void ap_run_do_something(request_rec *r, int n)
- {
- - ...
- do_something(r, n);
- + 

+          void ap_run_do_something(request_rec *r, int n)
+          {
+            ...
+            do_something(r, n);
           }
-
+ +

Hooks that return a value

If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:

-

+ 

           AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)
-
+ +

The first hook that does not return DECLINED stops the loop and its return value is returned from the hook @@ -123,9 +124,10 @@ value other than one of those two stops the loop, and its return is the return value. Declare these like so:

-

+ 

           AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)
-
+ +

Again, OK and DECLINED are the traditional values. You can use what you want.

@@ -136,12 +138,13 @@

At appropriate moments in the code, call the hook caller, like so:

-

- int n, ret;
- request_rec *r;
-
+ 

+        int n, ret;
+        request_rec *r;
+
         ret=ap_run_do_something(r, n);
-
+ +
top
@@ -153,15 +156,14 @@

Include the appropriate header, and define a static function of the correct type:

-

+ 

         static int my_something_doer(request_rec *r, int n)

-        {

-        
-          ...

-          return OK;

-        
+        {
+          ...
+          return OK;
         }
-
+ +

Add a hook registering function

@@ -169,22 +171,19 @@ registering function, which is included in the module structure:

-

- static void my_register_hooks()
- {
- - ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
- - }
-
- mode MODULE_VAR_EXPORT my_module =
- {
- - ...
- my_register_hooks /* register hooks */
- + 

+        static void my_register_hooks()
+        {
+          ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
+        }
+
+        mode MODULE_VAR_EXPORT my_module =
+        {
+          ...
+          my_register_hooks       /* register hooks */
         };
-
+ +

Controlling hook calling order

@@ -216,16 +215,15 @@ example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:

-

- static void register_hooks()
- {
- - static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };
-
- ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
- + 

+        static void register_hooks()
+        {
+          static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };
+
+          ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
         }
-
+ +

Note that the sort used to achieve this is stable, so ordering set by APR_HOOK_ORDER is preserved, as far diff --git a/docs/manual/developer/hooks.xml b/docs/manual/developer/hooks.xml index 46d778c307c..fe6a1e14a8d 100644 --- a/docs/manual/developer/hooks.xml +++ b/docs/manual/developer/hooks.xml @@ -47,9 +47,9 @@ arguments. For example, if the hook returns an int and takes a request_rec * and an int and is called do_something, then declare it like this:

- + AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n)) - +

This should go in a header which modules will include if they want to use the hook.

@@ -60,14 +60,12 @@ which is used to record the module functions that use the hook. This is declared as follows:

- - APR_HOOK_STRUCT(
- - APR_HOOK_LINK(do_something)
- ...
- + + APR_HOOK_STRUCT( + APR_HOOK_LINK(do_something) + ... ) - +
Implement the hook caller @@ -80,33 +78,31 @@

If the return value of a hook is void, then all the hooks are called, and the caller is implemented like this:

- + AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n)) - +

The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:

- - void ap_run_do_something(request_rec *r, int n)
- {
- - ...
- do_something(r, n);
- + + void ap_run_do_something(request_rec *r, int n) + { + ... + do_something(r, n); } - +
Hooks that return a value

If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:

- + AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED) - +

The first hook that does not return DECLINED stops the loop and its return value is returned from the hook @@ -121,9 +117,9 @@ value other than one of those two stops the loop, and its return is the return value. Declare these like so:

- + AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED) - +

Again, OK and DECLINED are the traditional values. You can use what you want.

@@ -134,12 +130,12 @@

At appropriate moments in the code, call the hook caller, like so:

- - int n, ret;
- request_rec *r;
-
+ + int n, ret; + request_rec *r; + ret=ap_run_do_something(r, n); - +
@@ -151,15 +147,13 @@

Include the appropriate header, and define a static function of the correct type:

- + static int my_something_doer(request_rec *r, int n)
- {
- - ...
- return OK;
- + { + ... + return OK; } - +
Add a hook registering function @@ -167,22 +161,18 @@ registering function, which is included in the module structure:

- - static void my_register_hooks()
- {
- - ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
- - }
-
- mode MODULE_VAR_EXPORT my_module =
- {
- - ...
- my_register_hooks /* register hooks */
- + + static void my_register_hooks() + { + ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE); + } + + mode MODULE_VAR_EXPORT my_module = + { + ... + my_register_hooks /* register hooks */ }; - +
Controlling hook calling order @@ -214,16 +204,14 @@ example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:

- - static void register_hooks()
- {
- - static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };
-
- ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
- + + static void register_hooks() + { + static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL }; + + ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE); } - +

Note that the sort used to achieve this is stable, so ordering set by APR_HOOK_ORDER is preserved, as far diff --git a/docs/manual/developer/modguide.html.en b/docs/manual/developer/modguide.html.en index 00d78a0008a..2dbddf587d8 100644 --- a/docs/manual/developer/modguide.html.en +++ b/docs/manual/developer/modguide.html.en @@ -1100,7 +1100,7 @@ different meanings to the user of the server, and thus different contexts within which modules must operate. For example, let's assume you have this configuration set up for mod_rewrite:

-
+
 <Directory "/var/www">
     RewriteCond %{HTTP_HOST} ^example.com$
     RewriteRule (.*) http://www.example.com/$1
@@ -1108,7 +1108,8 @@ configuration set up for mod_rewrite:
 <Directory "/var/www/sub">
     RewriteRule ^foobar$ index.php?foobar=true
 </Directory>
-
+ +

In this example, you will have set up two different contexts for mod_rewrite:

@@ -1654,7 +1655,8 @@ static int example_handler(request_req *r) ap_rprintf(r, "<b>%s</b>: %s<br/>", e[i].key, e[i].val); } return OK; -} +} + @@ -1718,6 +1720,7 @@ static int example_handler(request_req* r) +
diff --git a/docs/manual/developer/output-filters.html.en b/docs/manual/developer/output-filters.html.en index 8b61fc7685d..c051b022067 100644 --- a/docs/manual/developer/output-filters.html.en +++ b/docs/manual/developer/output-filters.html.en @@ -130,16 +130,15 @@ private to the filter).

How to handle an empty brigade

+ 

     apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)

-    {

-    
-        if (APR_BRIGADE_EMPTY(bb)) {

-        
-            return APR_SUCCESS;

-        
-        }

-        ....

-    
+    {
+        if (APR_BRIGADE_EMPTY(bb)) {
+            return APR_SUCCESS;
+        }
+        ....
+
+

top
@@ -258,18 +257,20 @@ follows:

Bad output filter -- do not imitate!

- apr_bucket *e = APR_BRIGADE_FIRST(bb);
-const char *data;
-apr_size_t len;
-
-while (e != APR_BRIGADE_SENTINEL(bb)) {
- - apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
- e = APR_BUCKET_NEXT(e);
- -}
-
+ 

+apr_bucket *e = APR_BRIGADE_FIRST(bb);
+const char *data;
+apr_size_t len;
+
+while (e != APR_BRIGADE_SENTINEL(bb)) {
+    apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
+    e = APR_BUCKET_NEXT(e);
+
+}
+
 return ap_pass_brigade(bb);
+
+

The above implementation would consume memory proportional to @@ -283,24 +284,25 @@ return ap_pass_brigade(bb); needed and must be allocated only once per response, see the Maintaining state section.

Better output filter

-apr_bucket *e;
-const char *data;
-apr_size_t len;
-
-while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
- - rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
- if (rv) ...;
- /* Remove bucket e from bb. */
- APR_BUCKET_REMOVE(e);
- /* Insert it into temporary brigade. */
- APR_BRIGADE_INSERT_HEAD(tmpbb, e);
- /* Pass brigade downstream. */
- rv = ap_pass_brigade(f->next, tmpbb);
- if (rv) ...;
- apr_brigade_cleanup(tmpbb);
- +

+apr_bucket *e;
+const char *data;
+apr_size_t len;
+
+while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
+   rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
+   if (rv) ...;
+   /* Remove bucket e from bb. */
+   APR_BUCKET_REMOVE(e);
+   /* Insert it into  temporary brigade. */
+   APR_BRIGADE_INSERT_HEAD(tmpbb, e);
+   /* Pass brigade downstream. */
+   rv = ap_pass_brigade(f->next, tmpbb);
+   if (rv) ...;
+   apr_brigade_cleanup(tmpbb);
 }
+
+

top
@@ -316,32 +318,32 @@ while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
a new brigade per invocation as described in the Brigade structure section.

Example code to maintain filter state

-struct dummy_state {
- - apr_bucket_brigade *tmpbb;
- int filter_state;
- ....
- -};
-
-apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
-{
- - struct dummy_state *state;
-
- state = f->ctx;
- if (state == NULL) {
- + 

+struct dummy_state {
+   apr_bucket_brigade *tmpbb;
+   int filter_state;
+   ....
+};
+
+apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
+{
+
+    struct dummy_state *state;
+    
+    state = f->ctx;
+    if (state == NULL) {
+    
        /* First invocation for this response: initialise state structure.
-        */

-       f->ctx = state = apr_palloc(sizeof *state, f->r->pool);

-

-       state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);

-       state->filter_state = ...;

-    
-    }

+        */
+       f->ctx = state = apr_palloc(sizeof *state, f->r->pool);
+
+       state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);
+       state->filter_state = ...;
+
+    }
     ...
-
+
+

top
@@ -418,37 +420,35 @@ apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)

Example code using non-blocking bucket reads

-apr_bucket *e;
-apr_read_type_e mode = APR_NONBLOCK_READ;
-
-while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
- - apr_status_t rv;
-
- rv = apr_bucket_read(e, &data, &length, mode);
- if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {
- - /* Pass down a brigade containing a flush bucket: */
- APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));
- rv = ap_pass_brigade(f->next, tmpbb);
- apr_brigade_cleanup(tmpbb);
- if (rv != APR_SUCCESS) return rv;
-
- /* Retry, using a blocking read. */
- mode = APR_BLOCK_READ;
- continue;
- - } else if (rv != APR_SUCCESS) {
- - /* handle errors */
- - }
-
- /* Next time, try a non-blocking read first. */
- mode = APR_NONBLOCK_READ;
- ...
- + 

+apr_bucket *e;
+apr_read_type_e mode = APR_NONBLOCK_READ;
+
+while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
+    apr_status_t rv;
+
+    rv = apr_bucket_read(e, &data, &length, mode);
+    if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {
+
+        /* Pass down a brigade containing a flush bucket: */
+        APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));
+        rv = ap_pass_brigade(f->next, tmpbb);
+        apr_brigade_cleanup(tmpbb);
+        if (rv != APR_SUCCESS) return rv;
+
+        /* Retry, using a blocking read. */
+        mode = APR_BLOCK_READ;
+        continue;
+    } else if (rv != APR_SUCCESS) {
+        /* handle errors */
+    }
+
+    /* Next time, try a non-blocking read first. */
+    mode = APR_NONBLOCK_READ;
+    ...
 }
+
+

top
diff --git a/docs/manual/developer/output-filters.xml b/docs/manual/developer/output-filters.xml index 93360dce32e..ce9a9689146 100644 --- a/docs/manual/developer/output-filters.xml +++ b/docs/manual/developer/output-filters.xml @@ -121,16 +121,14 @@ private to the filter).

How to handle an empty brigade + apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
- {
- - if (APR_BRIGADE_EMPTY(bb)) {
- - return APR_SUCCESS;
- - }
- ....
- + { + if (APR_BRIGADE_EMPTY(bb)) { + return APR_SUCCESS; + } + .... + @@ -251,18 +249,19 @@ follows:

Bad output filter -- do not imitate! - apr_bucket *e = APR_BRIGADE_FIRST(bb);
-const char *data;
-apr_size_t len;
-
-while (e != APR_BRIGADE_SENTINEL(bb)) {
- - apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
- e = APR_BUCKET_NEXT(e);
- -}
-
+ +apr_bucket *e = APR_BRIGADE_FIRST(bb); +const char *data; +apr_size_t len; + +while (e != APR_BRIGADE_SENTINEL(bb)) { + apr_bucket_read(e, &data, &length, APR_BLOCK_READ); + e = APR_BUCKET_NEXT(e); + +} + return ap_pass_brigade(bb); +

The above implementation would consume memory proportional to @@ -277,24 +276,24 @@ return ap_pass_brigade(bb); href="#state">Maintaining state section.

Better output filter -apr_bucket *e;
-const char *data;
-apr_size_t len;
-
-while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
- - rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
- if (rv) ...;
- /* Remove bucket e from bb. */
- APR_BUCKET_REMOVE(e);
- /* Insert it into temporary brigade. */
- APR_BRIGADE_INSERT_HEAD(tmpbb, e);
- /* Pass brigade downstream. */
- rv = ap_pass_brigade(f->next, tmpbb);
- if (rv) ...;
- apr_brigade_cleanup(tmpbb);
- + +apr_bucket *e; +const char *data; +apr_size_t len; + +while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) { + rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ); + if (rv) ...; + /* Remove bucket e from bb. */ + APR_BUCKET_REMOVE(e); + /* Insert it into temporary brigade. */ + APR_BRIGADE_INSERT_HEAD(tmpbb, e); + /* Pass brigade downstream. */ + rv = ap_pass_brigade(f->next, tmpbb); + if (rv) ...; + apr_brigade_cleanup(tmpbb); } + @@ -311,32 +310,31 @@ while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
href="#brigade">Brigade structure section.

Example code to maintain filter state -struct dummy_state {
- - apr_bucket_brigade *tmpbb;
- int filter_state;
- ....
- -};
-
-apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
-{
- - struct dummy_state *state;
-
- state = f->ctx;
- if (state == NULL) {
- + +struct dummy_state { + apr_bucket_brigade *tmpbb; + int filter_state; + .... +}; + +apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb) +{ + + struct dummy_state *state; + + state = f->ctx; + if (state == NULL) { + /* First invocation for this response: initialise state structure. - */
- f->ctx = state = apr_palloc(sizeof *state, f->r->pool);
-
- state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);
- state->filter_state = ...;
- - }
+ */ + f->ctx = state = apr_palloc(sizeof *state, f->r->pool); + + state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc); + state->filter_state = ...; + + } ... - + @@ -414,37 +412,34 @@ apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
Example code using non-blocking bucket reads -apr_bucket *e;
-apr_read_type_e mode = APR_NONBLOCK_READ;
-
-while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
- - apr_status_t rv;
-
- rv = apr_bucket_read(e, &data, &length, mode);
- if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {
- - /* Pass down a brigade containing a flush bucket: */
- APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));
- rv = ap_pass_brigade(f->next, tmpbb);
- apr_brigade_cleanup(tmpbb);
- if (rv != APR_SUCCESS) return rv;
-
- /* Retry, using a blocking read. */
- mode = APR_BLOCK_READ;
- continue;
- - } else if (rv != APR_SUCCESS) {
- - /* handle errors */
- - }
-
- /* Next time, try a non-blocking read first. */
- mode = APR_NONBLOCK_READ;
- ...
- + +apr_bucket *e; +apr_read_type_e mode = APR_NONBLOCK_READ; + +while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) { + apr_status_t rv; + + rv = apr_bucket_read(e, &data, &length, mode); + if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) { + + /* Pass down a brigade containing a flush bucket: */ + APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...)); + rv = ap_pass_brigade(f->next, tmpbb); + apr_brigade_cleanup(tmpbb); + if (rv != APR_SUCCESS) return rv; + + /* Retry, using a blocking read. */ + mode = APR_BLOCK_READ; + continue; + } else if (rv != APR_SUCCESS) { + /* handle errors */ + } + + /* Next time, try a non-blocking read first. */ + mode = APR_NONBLOCK_READ; + ... } + diff --git a/docs/manual/developer/request.html.en b/docs/manual/developer/request.html.en index 79b894701dd..c669861cedc 100644 --- a/docs/manual/developer/request.html.en +++ b/docs/manual/developer/request.html.en @@ -150,7 +150,7 @@

The Security Phase

Needs Documentation. Code is:

- 
+    
         if ((access_status = ap_run_access_checker(r)) != 0) {
             return decl_die(access_status, "check access", r);
         }
@@ -162,7 +162,8 @@
         if ((access_status = ap_run_auth_checker(r)) != 0) {
             return decl_die(access_status, "check authorization", r);
         }
-
+ +
top

The Preparation Phase

diff --git a/docs/manual/developer/request.xml b/docs/manual/developer/request.xml index b4bc67b0a8c..e5731cee9d6 100644 --- a/docs/manual/developer/request.xml +++ b/docs/manual/developer/request.xml @@ -148,7 +148,7 @@
The Security Phase

Needs Documentation. Code is:

- 
+    
         if ((access_status = ap_run_access_checker(r)) != 0) {
             return decl_die(access_status, "check access", r);
         }
@@ -160,8 +160,7 @@
         if ((access_status = ap_run_auth_checker(r)) != 0) {
             return decl_die(access_status, "check authorization", r);
         }
-
- +
The Preparation Phase