docs: enable syntax highlighting in several docs files

... for better readability

Closes #6286
This commit is contained in:
0xflotus 2020-12-07 18:09:37 +01:00 committed by Daniel Stenberg
parent eddae97406
commit 5253444090
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
7 changed files with 260 additions and 164 deletions

View File

@ -36,18 +36,22 @@ library-global symbols.
We use only spaces for indentation, never TABs. We use two spaces for each new We use only spaces for indentation, never TABs. We use two spaces for each new
open brace. open brace.
```c
if(something_is_true) { if(something_is_true) {
while(second_statement == fine) { while(second_statement == fine) {
moo(); moo();
} }
} }
```
## Comments ## Comments
Since we write C89 code, **//** comments are not allowed. They weren't Since we write C89 code, **//** comments are not allowed. They weren't
introduced in the C standard until C99. We use only **/* comments */**. introduced in the C standard until C99. We use only **/* comments */**.
```c
/* this is a comment */ /* this is a comment */
```
## Long lines ## Long lines
@ -69,42 +73,52 @@ In if/while/do/for expressions, we write the open brace on the same line as
the keyword and we then set the closing brace on the same indentation level as the keyword and we then set the closing brace on the same indentation level as
the initial keyword. Like this: the initial keyword. Like this:
```c
if(age < 40) { if(age < 40) {
/* clearly a youngster */ /* clearly a youngster */
} }
```
You may omit the braces if they would contain only a one-line statement: You may omit the braces if they would contain only a one-line statement:
```c
if(!x) if(!x)
continue; continue;
```
For functions the opening brace should be on a separate line: For functions the opening brace should be on a separate line:
```c
int main(int argc, char **argv) int main(int argc, char **argv)
{ {
return 1; return 1;
} }
```
## 'else' on the following line ## 'else' on the following line
When adding an **else** clause to a conditional expression using braces, we When adding an **else** clause to a conditional expression using braces, we
add it on a new line after the closing brace. Like this: add it on a new line after the closing brace. Like this:
```c
if(age < 40) { if(age < 40) {
/* clearly a youngster */ /* clearly a youngster */
} }
else { else {
/* probably grumpy */ /* probably grumpy */
} }
```
## No space before parentheses ## No space before parentheses
When writing expressions using if/while/do/for, there shall be no space When writing expressions using if/while/do/for, there shall be no space
between the keyword and the open parenthesis. Like this: between the keyword and the open parenthesis. Like this:
```c
while(1) { while(1) {
/* loop forever */ /* loop forever */
} }
```
## Use boolean conditions ## Use boolean conditions
@ -112,40 +126,50 @@ Rather than test a conditional value such as a bool against TRUE or FALSE, a
pointer against NULL or != NULL and an int against zero or not zero in pointer against NULL or != NULL and an int against zero or not zero in
if/while conditions we prefer: if/while conditions we prefer:
```c
result = do_something(); result = do_something();
if(!result) { if(!result) {
/* something went wrong */ /* something went wrong */
return result; return result;
} }
```
## No assignments in conditions ## No assignments in conditions
To increase readability and reduce complexity of conditionals, we avoid To increase readability and reduce complexity of conditionals, we avoid
assigning variables within if/while conditions. We frown upon this style: assigning variables within if/while conditions. We frown upon this style:
```c
if((ptr = malloc(100)) == NULL) if((ptr = malloc(100)) == NULL)
return NULL; return NULL;
```
and instead we encourage the above version to be spelled out more clearly: and instead we encourage the above version to be spelled out more clearly:
```c
ptr = malloc(100); ptr = malloc(100);
if(!ptr) if(!ptr)
return NULL; return NULL;
```
## New block on a new line ## New block on a new line
We never write multiple statements on the same source line, even for very We never write multiple statements on the same source line, even for very
short if() conditions. short if() conditions.
```c
if(a) if(a)
return TRUE; return TRUE;
else if(b) else if(b)
return FALSE; return FALSE;
```
and NEVER: and NEVER:
```c
if(a) return TRUE; if(a) return TRUE;
else if(b) return FALSE; else if(b) return FALSE;
```
## Space around operators ## Space around operators
@ -155,6 +179,7 @@ have no space.
Examples: Examples:
```c
bla = func(); bla = func();
who = name[0]; who = name[0];
age += 1; age += 1;
@ -166,22 +191,27 @@ Examples:
contents = *pointer; contents = *pointer;
complement = ~bits; complement = ~bits;
empty = (!*string) ? TRUE : FALSE; empty = (!*string) ? TRUE : FALSE;
```
## No parentheses for return values ## No parentheses for return values
We use the 'return' statement without extra parentheses around the value: We use the 'return' statement without extra parentheses around the value:
```c
int works(void) int works(void)
{ {
return TRUE; return TRUE;
} }
```
## Parentheses for sizeof arguments ## Parentheses for sizeof arguments
When using the sizeof operator in code, we prefer it to be written with When using the sizeof operator in code, we prefer it to be written with
parentheses around its argument: parentheses around its argument:
```c
int size = sizeof(int); int size = sizeof(int);
```
## Column alignment ## Column alignment
@ -195,32 +225,40 @@ the statement it is. Operators should not start continuation lines. In other
cases follow the 2-space indent guideline. Here are some examples from cases follow the 2-space indent guideline. Here are some examples from
libcurl: libcurl:
```c
if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) && if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) &&
(handle->set.httpversion != CURL_HTTP_VERSION_1_0) && (handle->set.httpversion != CURL_HTTP_VERSION_1_0) &&
(handle->set.httpreq == HTTPREQ_GET || (handle->set.httpreq == HTTPREQ_GET ||
handle->set.httpreq == HTTPREQ_HEAD)) handle->set.httpreq == HTTPREQ_HEAD))
/* didn't ask for HTTP/1.0 and a GET or HEAD */ /* didn't ask for HTTP/1.0 and a GET or HEAD */
return TRUE; return TRUE;
```
If no parenthesis, use the default indent: If no parenthesis, use the default indent:
```c
data->set.http_disable_hostname_check_before_authentication = data->set.http_disable_hostname_check_before_authentication =
(0 != va_arg(param, long)) ? TRUE : FALSE; (0 != va_arg(param, long)) ? TRUE : FALSE;
```
Function invoke with an open parenthesis: Function invoke with an open parenthesis:
```c
if(option) { if(option) {
result = parse_login_details(option, strlen(option), result = parse_login_details(option, strlen(option),
(userp ? &user : NULL), (userp ? &user : NULL),
(passwdp ? &passwd : NULL), (passwdp ? &passwd : NULL),
NULL); NULL);
} }
```
Align with the "current open" parenthesis: Align with the "current open" parenthesis:
```c
DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing " DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing "
"server response left\n", "server response left\n",
(int)clipamount)); (int)clipamount));
```
## Platform dependent code ## Platform dependent code
@ -234,6 +272,7 @@ to constants when libcurl is built without that feature, to make the code
seamless. Like this example where the **magic()** function works differently seamless. Like this example where the **magic()** function works differently
depending on a build-time conditional: depending on a build-time conditional:
```c
#ifdef HAVE_MAGIC #ifdef HAVE_MAGIC
void magic(int a) void magic(int a)
{ {
@ -244,22 +283,27 @@ depending on a build-time conditional:
#endif #endif
int content = magic(3); int content = magic(3);
```
## No typedefed structs ## No typedefed structs
Use structs by all means, but do not typedef them. Use the `struct name` way Use structs by all means, but do not typedef them. Use the `struct name` way
of identifying them: of identifying them:
```c
struct something { struct something {
void *valid; void *valid;
size_t way_to_write; size_t way_to_write;
}; };
struct something instance; struct something instance;
```
**Not okay**: **Not okay**:
```c
typedef struct { typedef struct {
void *wrong; void *wrong;
size_t way_to_write; size_t way_to_write;
} something; } something;
something instance; something instance;
```

View File

@ -11,7 +11,9 @@ without using the dedicated dynbuf API.
## init ## init
```c
void Curl_dyn_init(struct dynbuf *s, size_t toobig); void Curl_dyn_init(struct dynbuf *s, size_t toobig);
```
This inits a struct to use for dynbuf and it can't fail. The `toobig` value This inits a struct to use for dynbuf and it can't fail. The `toobig` value
**must** be set to the maximum size we allow this buffer instance to grow to. **must** be set to the maximum size we allow this buffer instance to grow to.
@ -19,44 +21,58 @@ The functions below will return `CURLE_OUT_OF_MEMORY` when hitting this limit.
## free ## free
```c
void Curl_dyn_free(struct dynbuf *s); void Curl_dyn_free(struct dynbuf *s);
```
Free the associated memory and clean up. After a free, the `dynbuf` struct can Free the associated memory and clean up. After a free, the `dynbuf` struct can
be re-used to start appending new data to. be re-used to start appending new data to.
## addn ## addn
```c
CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len); CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len);
```
Append arbitrary data of a given length to the end of the buffer. Append arbitrary data of a given length to the end of the buffer.
## add ## add
```c
CURLcode Curl_dyn_add(struct dynbuf *s, const char *str); CURLcode Curl_dyn_add(struct dynbuf *s, const char *str);
```
Append a C string to the end of the buffer. Append a C string to the end of the buffer.
## addf ## addf
```c
CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...); CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...);
```
Append a `printf()`-style string to the end of the buffer. Append a `printf()`-style string to the end of the buffer.
## vaddf ## vaddf
```c
CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap); CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap);
```
Append a `vprintf()`-style string to the end of the buffer. Append a `vprintf()`-style string to the end of the buffer.
## reset ## reset
```c
void Curl_dyn_reset(struct dynbuf *s); void Curl_dyn_reset(struct dynbuf *s);
```
Reset the buffer length, but leave the allocation. Reset the buffer length, but leave the allocation.
## tail ## tail
CURLcode Curl_dyn_tail(struct dynbuf *s, size_t length) ```c
CURLcode Curl_dyn_tail(struct dynbuf *s, size_t length);
```
Keep `length` bytes of the buffer tail (the last `length` bytes of the Keep `length` bytes of the buffer tail (the last `length` bytes of the
buffer). The rest of the buffer is dropped. The specified `length` must not be buffer). The rest of the buffer is dropped. The specified `length` must not be
@ -64,7 +80,9 @@ larger than the buffer length.
## ptr ## ptr
```c
char *Curl_dyn_ptr(const struct dynbuf *s); char *Curl_dyn_ptr(const struct dynbuf *s);
```
Returns a `char *` to the buffer if it has a length, otherwise a NULL. Since Returns a `char *` to the buffer if it has a length, otherwise a NULL. Since
the buffer may be reallocated, this pointer should not be trusted or used the buffer may be reallocated, this pointer should not be trusted or used
@ -72,7 +90,9 @@ anymore after the next buffer manipulation call.
## uptr ## uptr
```c
unsigned char *Curl_dyn_uptr(const struct dynbuf *s); unsigned char *Curl_dyn_uptr(const struct dynbuf *s);
```
Returns an `unsigned char *` to the buffer if it has a length, otherwise a Returns an `unsigned char *` to the buffer if it has a length, otherwise a
NULL. Since the buffer may be reallocated, this pointer should not be trusted NULL. Since the buffer may be reallocated, this pointer should not be trusted
@ -80,7 +100,9 @@ or used anymore after the next buffer manipulation call.
## len ## len
```c
size_t Curl_dyn_len(const struct dynbuf *s); size_t Curl_dyn_len(const struct dynbuf *s);
```
Returns the length of the buffer in bytes. Does not include the terminating Returns the length of the buffer in bytes. Does not include the terminating
zero byte. zero byte.

View File

@ -148,7 +148,9 @@ debug multithreaded dynamic C runtime.
Make sure that MinGW32's bin dir is in the search path, for example: Make sure that MinGW32's bin dir is in the search path, for example:
```cmd
set PATH=c:\mingw32\bin;%PATH% set PATH=c:\mingw32\bin;%PATH%
```
then run `mingw32-make mingw32` in the root dir. There are other then run `mingw32-make mingw32` in the root dir. There are other
make targets available to build libcurl with more features, use: make targets available to build libcurl with more features, use:
@ -164,20 +166,26 @@ to verify that the provided `Makefile.m32` files use the proper paths, and
adjust as necessary. It is also possible to override these paths with adjust as necessary. It is also possible to override these paths with
environment variables, for example: environment variables, for example:
```cmd
set ZLIB_PATH=c:\zlib-1.2.8 set ZLIB_PATH=c:\zlib-1.2.8
set OPENSSL_PATH=c:\openssl-1.0.2c set OPENSSL_PATH=c:\openssl-1.0.2c
set LIBSSH2_PATH=c:\libssh2-1.6.0 set LIBSSH2_PATH=c:\libssh2-1.6.0
```
It is also possible to build with other LDAP SDKs than MS LDAP; currently It is also possible to build with other LDAP SDKs than MS LDAP; currently
it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP
SDK. If you want to use these you need to set these vars: SDK. If you want to use these you need to set these vars:
```cmd
set LDAP_SDK=c:\openldap set LDAP_SDK=c:\openldap
set USE_LDAP_OPENLDAP=1 set USE_LDAP_OPENLDAP=1
```
or for using the Novell SDK: or for using the Novell SDK:
```cmd
set USE_LDAP_NOVELL=1 set USE_LDAP_NOVELL=1
```
If you want to enable LDAPS support then set LDAPS=1. If you want to enable LDAPS support then set LDAPS=1.
@ -280,9 +288,11 @@ the same curl binary is executed on older cats. For example, running these
commands in curl's directory in the shell will build the code such that it commands in curl's directory in the shell will build the code such that it
will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash): will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash):
```bash
export MACOSX_DEPLOYMENT_TARGET="10.6" export MACOSX_DEPLOYMENT_TARGET="10.6"
./configure --with-secure-transport ./configure --with-secure-transport
make make
```
# Android # Android
@ -295,6 +305,7 @@ where it has been installed and then set up some environment variables before
launching `configure`. On macOS, those variables could look like this to compile launching `configure`. On macOS, those variables could look like this to compile
for `aarch64` and API level 29: for `aarch64` and API level 29:
```bash
export NDK=~/Library/Android/sdk/ndk/20.1.5948944 export NDK=~/Library/Android/sdk/ndk/20.1.5948944
export HOST_TAG=darwin-x86_64 export HOST_TAG=darwin-x86_64
export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/$HOST_TAG export TOOLCHAIN=$NDK/toolchains/llvm/prebuilt/$HOST_TAG
@ -305,6 +316,7 @@ for `aarch64` and API level 29:
export LD=$TOOLCHAIN/bin/aarch64-linux-android-ld export LD=$TOOLCHAIN/bin/aarch64-linux-android-ld
export RANLIB=$TOOLCHAIN/bin/aarch64-linux-android-ranlib export RANLIB=$TOOLCHAIN/bin/aarch64-linux-android-ranlib
export STRIP=$TOOLCHAIN/bin/aarch64-linux-android-strip export STRIP=$TOOLCHAIN/bin/aarch64-linux-android-strip
```
When building on Linux or targeting other API levels or architectures, you need When building on Linux or targeting other API levels or architectures, you need
to adjust those variables accordingly. After that you can build curl like this: to adjust those variables accordingly. After that you can build curl like this:
@ -337,6 +349,7 @@ configure with any options you need. Be sure and specify the `--host` and
example of cross-compiling for the IBM 405GP PowerPC processor using the example of cross-compiling for the IBM 405GP PowerPC processor using the
toolchain from MonteVista for Hardhat Linux. toolchain from MonteVista for Hardhat Linux.
```bash
#! /bin/sh #! /bin/sh
export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin export PATH=$PATH:/opt/hardhat/devkit/ppc/405/bin
@ -353,6 +366,7 @@ toolchain from MonteVista for Hardhat Linux.
--build=i586-pc-linux-gnu --build=i586-pc-linux-gnu
--prefix=/opt/hardhat/devkit/ppc/405/target/usr/local --prefix=/opt/hardhat/devkit/ppc/405/target/usr/local
--exec-prefix=/usr/local --exec-prefix=/usr/local
```
You may also need to provide a parameter like `--with-random=/dev/urandom` to You may also need to provide a parameter like `--with-random=/dev/urandom` to
configure as it cannot detect the presence of a random number generating configure as it cannot detect the presence of a random number generating

View File

@ -773,7 +773,9 @@ Track Down Memory Leaks
Add a line in your application code: Add a line in your application code:
`curl_dbg_memdebug("dump");` ```c
curl_dbg_memdebug("dump");
```
This will make the malloc debug system output a full trace of all resource This will make the malloc debug system output a full trace of all resource
using functions to the given file name. Make sure you rebuild your program using functions to the given file name. Make sure you rebuild your program

View File

@ -307,12 +307,14 @@ Example:
(page located at `http://www.formpost.com/getthis/`) (page located at `http://www.formpost.com/getthis/`)
```html
<form action="post.cgi" method="post"> <form action="post.cgi" method="post">
<input name=user size=10> <input name=user size=10>
<input name=pass type=password size=10> <input name=pass type=password size=10>
<input name=id type=hidden value="blablabla"> <input name=id type=hidden value="blablabla">
<input name=ding value="submit"> <input name=ding value="submit">
</form> </form>
```
We want to enter user 'foobar' with password '12345'. We want to enter user 'foobar' with password '12345'.
@ -419,7 +421,9 @@ if it should be used on secure connections only (`secure`).
If you've received a page from a server that contains a header like: If you've received a page from a server that contains a header like:
```http
Set-Cookie: sessionid=boo123; path="/foo"; Set-Cookie: sessionid=boo123; path="/foo";
```
it means the server wants that first pair passed on when we get anything in a it means the server wants that first pair passed on when we get anything in a
path beginning with "/foo". path beginning with "/foo".

View File

@ -222,10 +222,12 @@
A GET-form uses the method GET, as specified in HTML like: A GET-form uses the method GET, as specified in HTML like:
```html
<form method="GET" action="junk.cgi"> <form method="GET" action="junk.cgi">
<input type=text name="birthyear"> <input type=text name="birthyear">
<input type=submit name=press value="OK"> <input type=submit name=press value="OK">
</form> </form>
```
In your favorite browser, this form will appear with a text box to fill in In your favorite browser, this form will appear with a text box to fill in
and a press-button labeled "OK". If you fill in '1905' and press the OK and a press-button labeled "OK". If you fill in '1905' and press the OK
@ -258,10 +260,12 @@
The form would look very similar to the previous one: The form would look very similar to the previous one:
```html
<form method="POST" action="junk.cgi"> <form method="POST" action="junk.cgi">
<input type=text name="birthyear"> <input type=text name="birthyear">
<input type=submit name=press value=" OK "> <input type=submit name=press value=" OK ">
</form> </form>
```
And to use curl to post this form with the same data filled in as before, we And to use curl to post this form with the same data filled in as before, we
could do it like: could do it like:
@ -293,10 +297,12 @@
This method is mainly designed to better support file uploads. A form that This method is mainly designed to better support file uploads. A form that
allows a user to upload a file could be written like this in HTML: allows a user to upload a file could be written like this in HTML:
```html
<form method="POST" enctype='multipart/form-data' action="upload.cgi"> <form method="POST" enctype='multipart/form-data' action="upload.cgi">
<input type=file name=upload> <input type=file name=upload>
<input type=submit name=press value="OK"> <input type=submit name=press value="OK">
</form> </form>
```
This clearly shows that the Content-Type about to be sent is This clearly shows that the Content-Type about to be sent is
`multipart/form-data`. `multipart/form-data`.
@ -315,11 +321,13 @@
A similar example form with one visible field, one hidden field and one A similar example form with one visible field, one hidden field and one
submit button could look like: submit button could look like:
```html
<form method="POST" action="foobar.cgi"> <form method="POST" action="foobar.cgi">
<input type=text name="birthyear"> <input type=text name="birthyear">
<input type=hidden name="person" value="daniel"> <input type=hidden name="person" value="daniel">
<input type=submit name="press" value="OK"> <input type=submit name="press" value="OK">
</form> </form>
```
To POST this with curl, you won't have to think about if the fields are To POST this with curl, you won't have to think about if the fields are
hidden or not. To curl they're all the same: hidden or not. To curl they're all the same:

View File

@ -41,7 +41,9 @@ Version Numbers and Releases
numbering scheme that can be used for comparison. The version number is numbering scheme that can be used for comparison. The version number is
defined as: defined as:
```c
#define LIBCURL_VERSION_NUM 0xXXYYZZ #define LIBCURL_VERSION_NUM 0xXXYYZZ
```
Where XX, YY and ZZ are the main version, release and patch numbers in Where XX, YY and ZZ are the main version, release and patch numbers in
hexadecimal. All three number fields are always represented using two digits hexadecimal. All three number fields are always represented using two digits