Skip to content
Permalink
Browse files

more fix the docs

perl -p -i -e 's/`\+(.*?)\+`/`$1`/g' $(find . -name "*.adoc" -print)
  • Loading branch information
alandekok committed Aug 16, 2019
1 parent 622094c commit f825e8e45ab9c718117a623b35b24d5aedfac8d6
@@ -55,7 +55,7 @@ When it core dumps, do:
$ gdb /path/to/executable /path/to/core/file
```

Enable logging in `+gdb+` via the following commands:
Enable logging in `gdb` via the following commands:

```
(gdb) set logging file gdb-radiusd.log
@@ -65,7 +65,7 @@ Enable logging in `+gdb+` via the following commands:
and follow the instructions in the proceeding section.

You can also enable the ``panic_action'' given in
`+raddb/radiusd.conf+`. See the comments in that file for more details
`raddb/radiusd.conf`. See the comments in that file for more details
about automatically collecting gdb debugging information when the server
crashes.

@@ -81,14 +81,14 @@ the server under gdb as follows:
$ gdb radiusd
```

Enable logging in `+gdb+` via the following commands:
Enable logging in `gdb` via the following commands:

```
(gdb) set logging file gdb-radiusd.log
(gdb) set logging on
```

Tell `+gdb+` to pass any necessary command-line arguments to the server:
Tell `gdb` to pass any necessary command-line arguments to the server:

```
(gdb) set args ...
@@ -144,7 +144,7 @@ The output should be printed to the screen, and also sent to the
gdb-radiusd.log file.

You should then submit the information from the log file, along with any
server output, the output of `+radiusd -xv+`, and information about your
server output, the output of `radiusd -xv`, and information about your
operating system to:

https://bugs.freeradius.org/
@@ -168,25 +168,25 @@ number of errors related to OpenSSL, dlopen(), or libtldl. We cannot do
anything about those problems. However, any errors that are inside of
the FreeRADIUS source should be brought to our attention.

== Running with `+screen+`
== Running with `screen`

If the bug is a crash of the server, and it takes a long time for the
crash to happen, perform the following steps:

* Log in as root.
* Open a screen session (https://www.gnu.org/software/screen/)
`+$ screen bash+`.
`$ screen bash`.
* Make sure FreeRADIUS is not running.
* Make sure you have all the debug symbols about, or a debugable version
of the server installed (one built with `+--enable developer+`).
of the server installed (one built with `--enable developer`).
* Configure screen to log to a file; Ctrl+a,h
* Type `+gdb /path/to/radius+` (or /path/to/freeradius on Debian).
* At the `+(gdb)+` prompt, type `+run -X+`.
* Type `gdb /path/to/radius` (or /path/to/freeradius on Debian).
* At the `(gdb)` prompt, type `run -X`.
* Detach from screen Ctrl+a,d.
* When you notice FreeRADIUS has died, reconnect to your screen session
`+$ screen -D -r+`.
* At the `+(gdb)+` prompt type `+where+` or for _lots_ of info try
`+thread apply all bt full+`.
`$ screen -D -r`.
* At the `(gdb)` prompt type `where` or for _lots_ of info try
`thread apply all bt full`.
* Tell screen to stop logging, Ctrl+a,h.
* Logout from screen.

@@ -20,12 +20,12 @@ no clue as to what it’s doing.
If someone _really_ hates you, you’ll be forced to debug un-commented
code that someone else wrote. You don’t want to do that.
+
For FreeRADIUS use doxygen `+@+`-style comments so you get the benefits
For FreeRADIUS use doxygen `@`-style comments so you get the benefits
of https://doc.freeradius.org.
. *Give things reasonable names.*
+
Variables and functions should have names. Calling them `+x+`, `+xx+`,
and `+xxx+` makes your life hell. Even `+foo+` and `+i+` are
Variables and functions should have names. Calling them `x`, `xx`,
and `xxx` makes your life hell. Even `foo` and `i` are
problematic.
+
Avoid smurfs. Don’t re-use struct names in field names, i. e.
@@ -45,7 +45,7 @@ If your code reads as full English sentences, you’re doing it right.
Your function _cannot_ do anything right if the user passed in garbage
and you were too lazy to check for garbage input.
+
`+assert()+` (`+rad_assert()+`) is ugly. Use it.
`assert()` (`rad_assert()`) is ugly. Use it.
+
NOTE: GIGO is wrong. If your function gets garbage input, it should
complain loudly and with great descriptiveness.
@@ -70,7 +70,7 @@ fp = fopen(...);
fgetc(fp); /* core dumps! */
----

If the programmer had bothered to check for a `+NULL+` fp (error
If the programmer had bothered to check for a `NULL` fp (error
condition), then they could have produced a descriptive error message
instead of having the program core dump.

@@ -81,13 +81,13 @@ If your program core dumps accidentally, you’re a bad programmer. You
don’t know what your program is doing, or what it’s supposed to be doing
when anything goes wrong.
+
If it hits an `+assert()+` and calls `+abort()+`, you’re a genius.
If it hits an `assert()` and calls `abort()`, you’re a genius.
You’ve thought ahead to what _might_ go wrong, and put in an assertion
to ensure that it fails in a _known manner_ when something _does_ go
wrong. (As it usually does…)
. *Initialize your variables.*
+
`+memset()+` (`+talloc_zero()+`) is your friend. `+ptr = NULL+` is nice,
`memset()` (`talloc_zero()`) is your friend. `ptr = NULL` is nice,
too.
+
Having variables containing garbage values makes it easy for the code to
@@ -98,18 +98,18 @@ It’s also nearly impossible for you to debug any problems, as you can’t
tell the variables with garbage values from the real ones.
. *Don’t allow buffer over-runs.*
+
They’re usually accidental, but they cause core dumps. `+strcpy()+` and
`+strcat()+` are ugly. Use them under duress.
They’re usually accidental, but they cause core dumps. `strcpy()` and
`strcat()` are ugly. Use them under duress.
+
`+sizeof()+` is your friend.
. *`+const+` is your friend.*
`sizeof()` is your friend.
. *`const` is your friend.*
+
If you don’t mean to modify an input structure to your function, declare
it `+const+`. Declare string constants `+const+`. It can’t hurt, and it
it `const`. Declare string constants `const`. It can’t hurt, and it
allows more errors to be found at compile time.
+
Use `+const+` everywhere. Once you throw a few into your code, and have
it save you from stupid bugs, you’ll blindly throw in `+const+`
Use `const` everywhere. Once you throw a few into your code, and have
it save you from stupid bugs, you’ll blindly throw in `const`
everywhere. It’s a life-saver.
. *Use C compiler warnings.*
+
@@ -127,24 +127,24 @@ error messages like this, too. See #4.
You don’t know under what system someone will try to run your code.
Don’t demand that others use the same OS or character set as you use.
+
Never assign numbers to pointers. If foo is a `+char*+`, and you want it
to be be `+NULL+`, assign `+NULL+`, not `+0+`. The zeroth location is
Never assign numbers to pointers. If foo is a `char*`, and you want it
to be be `NULL`, assign `NULL`, not `0`. The zeroth location is
perfectly as addressable as any other on plenty of OSes. Not all the
world runs on Unix (though it should :) ).
+
Another common mistake is to assume that the zeroth character in the
character set is the string terminator. Instead of terminating a string
with `+0+`, use `+'\0'+`, which is always right. Similarly, `+memset()+`
with the appropriate value: `+NULL+`, `+'\0'+`, or `+0+` for pointers,
with `0`, use `'\0'`, which is always right. Similarly, `memset()`
with the appropriate value: `NULL`, `'\0'`, or `0` for pointers,
chars, and numbers.
+
Don’t put tabs in string constants, either. Always use `+'\t'+` to
Don’t put tabs in string constants, either. Always use `'\t'` to
represent a tab, instead of ASCII 9. Literal tabs are presented to
readers of your code as arbitrary whitespace, and it’s easy to mess up.
. *Make conditionals explicit.*
+
Though it’s legal to test `+if (foo) {}+` if you test against the
appropriate value (like `+NULL+` or `+'\0'+`), your code is prettier and
Though it’s legal to test `if (foo) {}` if you test against the
appropriate value (like `NULL` or `'\0'`), your code is prettier and
easier for others to read without having to eyeball your prototypes
continuously to figure out what you’re doing (especially if your
variables aren’t well-named). See #2.
@@ -158,25 +158,25 @@ testable. As a result, it will look better and be easier to debug.

== Hints, Tips, and Tricks

This section lists many of the common `+rules+` associated with code
This section lists many of the common `rules` associated with code
submitted to the project. There are always exceptions… but you must have
a really good reason for doing so.

[arabic]
. *Read the Documentation and follow the CodingStyle*
+
The FreeRADIUS server has a common coding style. Use real tabs to
indent. There is whitespace in variable assignments. (`+i = 1+`, not
`+i=1+`).
indent. There is whitespace in variable assignments. (`i = 1`, not
`i=1`).
+
When in doubt, format your code to look the same as code already in the
server. If your code deviates too much from the current style, it is
likely to be rejected without further review, and without comment.
. *#ifdefs are ugly*
+
Code cluttered with `+#ifdef+` s is difficult to read and maintain.
Don’t do it. Instead, put your `+#ifdef+` s in a header, and
conditionally define `+static inline+` functions, or macros, which are
Code cluttered with `#ifdef` s is difficult to read and maintain.
Don’t do it. Instead, put your `#ifdef` s in a header, and
conditionally define `static inline` functions, or macros, which are
used in the code. Let the compiler optimize away the ``no-op'' case.
+
Simple example, of poor code:
@@ -207,7 +207,7 @@ init_my_stuff(dev);
----

[arabic, start=3]
. *`+static inline+` is better than a macro*
. *`static inline` is better than a macro*
+
Static inline functions are greatly preferred over macros. They provide
type safety, have no length limitations, no formatting limitations, and
@@ -217,8 +217,8 @@ Macros should only be used for cases where a static inline is clearly
suboptimal [there a few, isolated cases of this in fast paths], or where
it is impossible to use a static inline function [such as string-izing].
+
`+static inline+` is preferred over `+static __inline__+`,
`+extern inline+`, and `+extern __inline__+`.
`static inline` is preferred over `static __inline__`,
`extern inline`, and `extern __inline__`.
. *Don’t over-design.*
+
Don’t try to anticipate nebulous future cases which may or may not be
@@ -55,11 +55,11 @@ See the following links for more details about submitting via github:

=== 1. diff -u

Use `+diff -u+` or `+diff -urN+` to create patches.
Use `diff -u` or `diff -urN` to create patches.

All changes to the source occur in the form of patches, as generated by
diff(1). When creating your patch, make sure to create it in unified
diff format, as supplied by the `+-u+` argument to diff(1). Patches
diff format, as supplied by the `-u` argument to diff(1). Patches
should be based in the root source directory, not in any lower
subdirectory.

@@ -75,7 +75,7 @@ vi $MYFILE # make your change
diff -u $MYFILE.orig $MYFILE > /tmp/patch
```

To create a patch for multiple files, you should unpack a `+vanilla+`,
To create a patch for multiple files, you should unpack a `vanilla`,
or unmodified source tree, and generate a diff against your own source
tree. For example:

@@ -98,11 +98,11 @@ Otherwise, send the patch to
=== 3. No MIME, no links, no compression, no attachments. Just plain text

The developers need to be able to read and comment on the changes you
are submitting. It is important for a developer to be able to `+quote+`
are submitting. It is important for a developer to be able to `quote`
your changes, using standard e-mail tools, so that they may comment on
specific portions of your code.

For this reason, all patches should be submitting e-mail `+inline+`.
For this reason, all patches should be submitting e-mail `inline`.

Do not attach the patch as a MIME attachment, compressed or not. Many
popular e-mail applications will not always transmit a MIME attachment
@@ -12,11 +12,11 @@ https://talloc.samba.org/talloc/doc/html/index.html

*OSX*

`+# brew install talloc+`
`# brew install talloc`

*Debian / Ubuntu*

`+# apt-get install libtalloc-dev+`
`# apt-get install libtalloc-dev`

*RedHat*

@@ -29,15 +29,15 @@ https://talloc.samba.org/talloc/doc/html/index.html

Kqueue is an event / timer API originally written for BSD systems. It is
_much_ simpler to use than third-party event libraries. On Linux, a
`+libkqueue+` package is available.
`libkqueue` package is available.

*OSX*

_nothing to do. kqueue is available._

*Debian / Ubuntu*

`+# apt-get install libkqueue-dev+`
`# apt-get install libkqueue-dev`

*RedHat*

0 comments on commit f825e8e

Please sign in to comment.
You can’t perform that action at this time.