Browse code

- minor updates

Jan Janak authored on 06/05/2003 14:11:39
Showing 2 changed files
... ...
@@ -10,39 +10,48 @@
10 10
 	<section>
11 11
 	    <title>Why use it ?</title>
12 12
 	    <para>
13
-		The main reason in creating it was to have a single transparent interface to various locking methods. For example right now &ser; uses the
14
-		following locking methods, depending on their availability on the target system.
13
+		The main reason in creating it was to have a single transparent interface to various
14
+		locking methods. For example right now &ser; uses the following locking methods,
15
+		depending on their availability on the target system.
15 16
 	    </para>
16 17
 	    <itemizedlist>
17 18
 		<listitem>
18 19
 		    <simpara><emphasis>FAST_LOCK</emphasis></simpara>
19 20
 		    <simpara>
20
-			Fast inline assembly locks, defined in <filename moreinfo="none">fast_lock.h</filename>. They are currently available for x86, sparc64,
21
-			strongarm (amv4l) and ppc (external untested contributed code). In general if the assembly code exists for a given architecture and the
22
-			compiler knows inline assembly (for example sun cc does not) FAST_LOCK is prefered. The main advantage of using FAST_LOCK is very low
23
-			memory overhead and extremely fast lock/unlock operations (like 20 times faster then SYSV semaphores on linux & 40 times on
24
-			solaris). The only thing that comes close to them are pthread mutexes (which are about 3-4 times slower).
21
+			Fast inline assembly locks, defined in <filename
22
+			moreinfo="none">fast_lock.h</filename>. They are currently available for
23
+			x86, sparc64, strongarm (amv4l) and ppc (external untested contributed
24
+			code). In general if the assembly code exists for a given architecture and
25
+			the compiler knows inline assembly (for example sun cc does not) FAST_LOCK
26
+			is prefered. The main advantage of using FAST_LOCK is very low memory
27
+			overhead and extremely fast lock/unlock operations (like 20 times faster
28
+			then SYSV semaphores on linux & 40 times on solaris). The only thing that
29
+			comes close to them are pthread mutexes (which are about 3-4 times slower).
25 30
 		    </simpara>
26 31
 		</listitem>
27 32
 		<listitem>
28 33
 		    <simpara><emphasis>PHTREAD_MUTEX</emphasis></simpara>
29 34
 		    <simpara>
30
-			Uses pthread_mutex_lock/unlock. They are quite fast but they work between processes only on some systems (they do not work on linux).
35
+			Uses pthread_mutex_lock/unlock. They are quite fast but they work between
36
+			processes only on some systems (they do not work on linux).
31 37
 		    </simpara>
32 38
 		</listitem>
33 39
 		<listitem>
34 40
 		    <simpara><emphasis>POSIX_SEM</emphasis></simpara>
35 41
 		    <simpara>
36
-			Uses posix semaphores (<function moreinfo="none">sem_wait</function>/<function moreinfo="none">sem_post</function>). They are slower
37
-			then the previous methods but still way faster then SYSV sempahores. Unfortunately they also do not work on all the systems
38
-			(e.g. linux).
42
+			Uses posix semaphores (<function
43
+			moreinfo="none">sem_wait</function>/<function
44
+			moreinfo="none">sem_post</function>). They are slower then the previous
45
+			methods but still way faster then SYSV sempahores. Unfortunately they also
46
+			do not work on all the systems (e.g. linux).
39 47
 		    </simpara>
40 48
 		</listitem>
41 49
 		<listitem>
42 50
 		    <simpara><emphasis>SYSV_SEM</emphasis></simpara>
43 51
 		    <simpara>
44
-			This is the most portable but also the slowest locking method. Another problem is that the number of semaphores that can be alocated by
45
-			a process is limited. One also has to free them before exiting.
52
+			This is the most portable but also the slowest locking method. Another
53
+			problem is that the number of semaphores that can be alocated by a process
54
+			is limited. One also has to free them before exiting.
46 55
 		    </simpara>
47 56
 		</listitem>
48 57
 	    </itemizedlist>
... ...
@@ -50,28 +59,35 @@
50 50
 	<section>
51 51
 	    <title>How to use it ?</title>
52 52
 	    <simpara>
53
-		First of all you have to include <filename moreinfo="none">locking.h</filename>. Then when compiling the code one or all of FAST_LOCK,
54
-		USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the ser <filename moreinfo="none">Makefile.defs</filename> takes care of
55
-		this, you should need to change it only for new architectures or compilers). <filename moreinfo="none">locking.h</filename> defines 2 new types:
53
+		First of all you have to include <filename
54
+		moreinfo="none">locking.h</filename>. Then when compiling the code one or all of
55
+		FAST_LOCK, USE_PTHREAD_MUTEX, USE_PTHREAD_SEM or USE_SYSV_SEM must be defined (the
56
+		ser <filename moreinfo="none">Makefile.defs</filename> takes care of this, you
57
+		should need to change it only for new architectures or compilers). <filename
58
+		moreinfo="none">locking.h</filename> defines 2 new types:
56 59
 		<structname>gen_lock_t</structname> and <structname>lock_set_t</structname>.
57 60
 	    </simpara>
58 61
 	</section>
59 62
 	<section>
60 63
 	    <title>Simple Locks</title>
61 64
 	    <simpara>
62
-		The simple locks are simple mutexes. The type is <structname>gen_lock_t</structname>.  
65
+		The simple locks are simple mutexes. The type is
66
+		<structname>gen_lock_t</structname>.
63 67
 	    </simpara>
64 68
 	    <warning>
65 69
 		<simpara>
66
-		    Do not make any assumptions on <structname>gen_lock_t</structname> base type, it does not have to be always an int.
70
+		    Do not make any assumptions on <structname>gen_lock_t</structname> base type, it
71
+		    does not have to be always an int.
67 72
 		</simpara>
68 73
 	    </warning>
69 74
 	    <section>
70 75
 		<title>Allocation & Initialization</title>
71 76
 		<simpara>
72
-		    The locks are allocated with: <function moreinfo="none">gen_lock_t* lock_alloc()</function> and initialized with <function
73
-		    moreinfo="none">gen_lock_t* lock_init(gen_lock_t* lock)</function>. Both functions return 0 on failure. The locks must be initialized before
74
-		    use. A proper alloc/init sequence looks like:
77
+		    The locks are allocated with: <function moreinfo="none">gen_lock_t*
78
+		    lock_alloc()</function> and initialized with <function
79
+		    moreinfo="none">gen_lock_t* lock_init(gen_lock_t* lock)</function>. Both
80
+		    functions return 0 on failure. The locks must be initialized before use. A
81
+		    proper alloc/init sequence looks like:
75 82
 		</simpara>
76 83
 		<programlisting format="linespecific">
77 84
 gen_lock_t* lock;
... ...
@@ -85,8 +101,9 @@ if (lock_init(lock)==0){
85 85
 ...
86 86
 </programlisting>
87 87
 		<simpara>
88
-		    Lock allocation can be skipped in some cases: if the lock is already in shared memory you don't need to allocate it again, you can
89
-		    initialize it directly, but keep in mind that the lock <emphasis>MUST</emphasis> be in shared memory.
88
+		    Lock allocation can be skipped in some cases: if the lock is already in shared
89
+		    memory you don't need to allocate it again, you can initialize it directly, but
90
+		    keep in mind that the lock <emphasis>MUST</emphasis> be in shared memory.
90 91
 		</simpara>
91 92
 		<simpara>
92 93
 		    Example:
... ...
@@ -118,10 +135,13 @@ if (lock_init(&amp;bar->lock)==0){
118 118
 		    </funcprototype>
119 119
 		</funcsynopsis>
120 120
 		<simpara>
121
-		    The <function moreinfo="none">lock_destroy</function> function must be called first. It removes the resources associated with the lock, but
122
-		    it does not also free the lock shared memory part. Think of sysv <command moreinfo="none">rmid</command>.  Please don't forget to call this
123
-		    function, or you can leave allocated resources in some cases (e.g sysv semaphores). Be carefull to call it in your module destroy function
124
-		    if you use any global module locks.
121
+		    The <function moreinfo="none">lock_destroy</function> function must be called
122
+		    first. It removes the resources associated with the lock, but it does not also
123
+		    free the lock shared memory part. Think of sysv <command
124
+		    moreinfo="none">rmid</command>.  Please don't forget to call this function, or
125
+		    you can leave allocated resources in some cases (e.g sysv semaphores). Be
126
+		    carefull to call it in your module destroy function if you use any global module
127
+		    locks.
125 128
 		</simpara>
126 129
 		<simpara>
127 130
 		    Example:
... ...
@@ -131,7 +151,8 @@ lock_destroy(lock);
131 131
 lock_dealloc(lock);
132 132
 </programlisting>
133 133
 		<simpara>
134
-		    Of course you don't need to call <function moreinfo="none">lock_dealloc</function> if your lock was not allocated with 
134
+		    Of course you don't need to call <function
135
+		    moreinfo="none">lock_dealloc</function> if your lock was not allocated with
135 136
 		    <function moreinfo="none">lock_alloc</function>l.
136 137
 		</simpara>
137 138
 	    </section>
... ...
@@ -152,8 +173,10 @@ lock_dealloc(lock);
152 152
 	<section>
153 153
 	    <title>Lock Sets</title>
154 154
 	    <simpara>
155
-		The lock sets are kind of sysv semaphore sets equivalent. The type is <structname>lock_set_t</structname>.  Use them when you need a lot of
156
-		mutexes. In some cases they waste less system resources than arrays of <structname>gen_lock_t</structname> (e.g. sys v semaphores).
155
+		The lock sets are kind of sysv semaphore sets equivalent. The type is
156
+		<structname>lock_set_t</structname>.  Use them when you need a lot of mutexes. In
157
+		some cases they waste less system resources than arrays of
158
+		<structname>gen_lock_t</structname> (e.g. sys v semaphores).
157 159
 	    </simpara>
158 160
 	    <section>
159 161
 		<title>Allocating & Initializing</title>
... ...
@@ -172,8 +195,9 @@ lock_dealloc(lock);
172 172
 		</simpara>
173 173
 		<warning>
174 174
 		    <simpara>
175
-			Expect the allocation function to fail for large numbers. It depends on the locking method used & the system available resources (again
176
-			the sysv semaphores example).
175
+			Expect the allocation function to fail for large numbers. It depends on the
176
+			locking method used & the system available resources (again the sysv
177
+			semaphores example).
177 178
 		    </simpara>
178 179
 		</warning>
179 180
 		<simpara>
... ...
@@ -9,57 +9,71 @@
9 9
 	<title>Module Interface</title>
10 10
 	<abstract>
11 11
 	    <para>
12
-		&ser; features modular architecture which allows us to split &ser;'s functionality across several modules. This approach gives us greater
13
-		flexibility, only required set of functions can be loaded upon startup which minimizes the server's memory footprint. Modules can be also
14
-		provided by 3rd party developers and distributed separately from the main server. Most of the functionality that &ser; provides is available
15
-		through modules, the core itself contains only minimum set of functions that is essential for proper server's behaviour or that is needed by all
16
-		modules.
12
+		&ser; features modular architecture which allows us to split &ser;'s functionality
13
+		across several modules. This approach gives us greater flexibility, only required
14
+		set of functions can be loaded upon startup which minimizes the server's memory
15
+		footprint. Modules can be also provided by 3rd party developers and distributed
16
+		separately from the main server. Most of the functionality that &ser; provides is
17
+		available through modules, the core itself contains only minimum set of functions
18
+		that is essential for proper server's behaviour or that is needed by all modules.
17 19
 	    </para>
18 20
 	    <para>
19
-		This chapter provides detailed information on module interface of &ser;, which is used to pass information on available functions and parameters
20
-		from the modules to the core.
21
+		This chapter provides detailed information on module interface of &ser;, which is
22
+		used to pass information on available functions and parameters from the modules to
23
+		the core.
21 24
 	    </para>
22 25
 	</abstract>
23 26
 	<section>
24 27
 	    <title>Shared Objects</title>
25 28
 	    <abstract>
26 29
 		<para>
27
-		    First it would be good to know how &ser; loads and uses modules before we describe the module interface in detail. This section gives a
28
-		    brief overview of &ser;'s module subsystem.
30
+		    First it would be good to know how &ser; loads and uses modules before we
31
+		    describe the module interface in detail. This section gives a brief overview of
32
+		    &ser;'s module subsystem.
29 33
 		</para>
30 34
 	    </abstract>
31 35
 	    <para>
32
-		&ser; modules are compiled as <quote>shared objects</quote>. A file containing a shared object has usually .so suffix. All modules (shared
33
-		objects) will be stored in one directory after installation. For example <abbrev>tm</abbrev> module, which contains code essential for stateful
34
-		processing, will be stored in file named <filename moreinfo="none">tm.so</filename>. By default these files are stored in 
36
+		&ser; modules are compiled as <quote>shared objects</quote>. A file containing a
37
+		shared object has usually .so suffix. All modules (shared objects) will be stored in
38
+		one directory after installation. For example <abbrev>tm</abbrev> module, which
39
+		contains code essential for stateful processing, will be stored in file named
40
+		<filename moreinfo="none">tm.so</filename>. By default these files are stored in
35 41
 		<filename moreinfo="none">&moddir;</filename> directory.
36 42
 	    </para>
37 43
 	    <para>
38
-		You can later load the modules using <command moreinfo="none">loadmodule</command> command in your configuration file. If you want to load
39
-		previously mentioned <filename moreinfo="none">tm.so</filename> module, you can do it using <command moreinfo="none">loadmodule
40
-		"&moddir;/tm.so"</command> in your configuration file. This command invokes dynamic linker provided by the operating system which opens
41
-		<filename moreinfo="none">tm.so</filename> file, loads it into memory and resolves all symbol dependencies (a module might require symbols from
42
-		the core, for example functions and variables).
44
+		You can later load the modules using <command moreinfo="none">loadmodule</command>
45
+		command in your configuration file. If you want to load previously mentioned
46
+		<filename moreinfo="none">tm.so</filename> module, you can do it using <command
47
+		moreinfo="none">loadmodule "&moddir;/tm.so"</command> in your configuration
48
+		file. This command invokes dynamic linker provided by the operating system which
49
+		opens <filename moreinfo="none">tm.so</filename> file, loads it into memory and
50
+		resolves all symbol dependencies (a module might require symbols from the core, for
51
+		example functions and variables).
43 52
 	    </para>
44 53
 	    <para>
45
-		As the last step of the module loading the core tries to find variable named <varname>exports</varname>, which describes all functions and
46
-		parameters provided by the module. These functions and parameters are later available to the server and can be used either in the configuration
47
-		file or by other modules.
54
+		As the last step of the module loading the core tries to find variable named
55
+		<varname>exports</varname>, which describes all functions and parameters provided by
56
+		the module. These functions and parameters are later available to the server and can
57
+		be used either in the configuration file or by other modules.
48 58
 	    </para>
49 59
 	</section>
50 60
 	<section>
51 61
 	    <title>Exporting Functions</title>
52 62
 	    <abstract>
53 63
 		<para>
54
-		    Each module can provide zero or more functions, which can be used in the configuration file or by other modules internally. This section
55
-		    gives a detailed description of structure describing exported functions and passing this information to the core through the module
56
-		    interface.
64
+		    Each module can provide zero or more functions, which can be used in the
65
+		    configuration file or by other modules internally. This section gives a detailed
66
+		    description of structure describing exported functions and passing this
67
+		    information to the core through the module interface.
57 68
 		</para>
58 69
 	    </abstract>
59 70
 	    <para>
60
-		Each function exported by a module must be described by <structname>cmd_export_t</structname> structure. Structures describing all exported
61
-		functions are arranged into an array and pointer to the array is then passed to the core. The last element of the array must contain 0 in all
62
-		it's fields, this element serves as the mark telling the core that this is the very last element and it must stop scanning the array.
71
+		Each function exported by a module must be described by
72
+		<structname>cmd_export_t</structname> structure. Structures describing all exported
73
+		functions are arranged into an array and pointer to the array is then passed to the
74
+		core. The last element of the array must contain 0 in all it's fields, this element
75
+		serves as the mark telling the core that this is the very last element and it must
76
+		stop scanning the array.
63 77
 	    </para>
64 78
 	    <para>
65 79
 		Each exported function is described by the following structure:
... ...
@@ -80,79 +94,100 @@ typedef struct cmd_export_ cmd_export_t;
80 80
 		<listitem>
81 81
 		    <simpara><varname>char* name</varname><simpara> 
82 82
 		    <simpara>
83
-			This is the name under which the function will be visible to the core. Usually it is the same as the name of the corresponding function.
83
+			This is the name under which the function will be visible to the
84
+			core. Usually it is the same as the name of the corresponding function.
84 85
 		    </simpara>
85 86
 		</listitem>
86 87
 		<listitem>
87 88
 		    <simpara><varname>cmd_function function</varname></simpara> 
88
-		    <para>
89
-			cmd_function type is defined as follows:
90
-		    </para> 
89
+		    <para>cmd_function type is defined as follows: </para>
91 90
 		    <programlisting format="linespecific">
92 91
 typedef int (*cmd_function)(struct sip_msg*, char*, char*); 
93 92
 </programlisting>
94 93
 		    <simpara>
95
-			The first parameter is a <acronym>SIP</acronym> message being processed, the other 2 parameters are given from the configuration file.
94
+			The first parameter is a <acronym>SIP</acronym> message being processed, the
95
+			other 2 parameters are given from the configuration file.
96 96
 		    </simpara>
97 97
 		    <note>
98 98
 			<simpara>
99
-			    From time to time you might need to export a function that has different synopsis. This can happen if you export functions
100
-			    that are supposed to be called by other modules only and must not be called from the configuration script. In this case you will
101
-			    have to do type-casting otherwise the compiler will complain and will not compile your module.
99
+			    From time to time you might need to export a function that has different
100
+			    synopsis. This can happen if you export functions that are supposed to
101
+			    be called by other modules only and must not be called from the
102
+			    configuration script. In this case you will have to do type-casting
103
+			    otherwise the compiler will complain and will not compile your module.
102 104
 			</simpara>
103 105
 			<simpara>
104
-			    Simply put (cmd_function) just before the function name, for example <function moreinfo="none">(cmd_function)my_function</function>. 
105
-			    Don't use this unless you know what are you doing ! The server might crash if you pass wrong parameters to the function later !
106
+			    Simply put (cmd_function) just before the function name, for example
107
+			    <function moreinfo="none">(cmd_function)my_function</function>.  Don't
108
+			    use this unless you know what are you doing ! The server might crash if
109
+			    you pass wrong parameters to the function later !
106 110
 			</simpara>
107 111
 		    </note>
108 112
 		</listitem>
109 113
 		<listitem>
110 114
 		    <simpara><varname>int param_no</varname></simpara>
111 115
 		    <simpara>
112
-			Number of parameters of the function. It can be 0, 1 or 2. The function will be not visible from the configuration script if you use
113
-			another value.
116
+			Number of parameters of the function. It can be 0, 1 or 2. The function will
117
+			be not visible from the configuration script if you use another value.
114 118
 		    </simpara>
115 119
 		</listitem>
116 120
 		<listitem>
117 121
 		    <simpara><varname>fixup_function fixup</varname></simpara>
118 122
 		    <simpara>
119
-			This is the function that will be used to <quote>fixup</quote> function parameters. Set this field to 0 if you don't need this.
123
+			This is the function that will be used to <quote>fixup</quote> function
124
+			parameters. Set this field to 0 if you don't need this.
120 125
 		    </simpara>
121 126
 		    <simpara>
122
-			If you provide pointer to a fixup function in this field, the fixup function will be called for each occurence of the exported function
123
-			in the configuration script.
127
+			If you provide pointer to a fixup function in this field, the fixup function
128
+			will be called for each occurence of the exported function in the
129
+			configuration script.
124 130
 		    </simpara>
125 131
 		    <simpara>
126
-			The fixup function can be used to perform some operation on the function parameters. For example, if one of the parameters is a regular
127
-			expression, you can use the fixup to compile the regular expression. The fixup functions are called only once - upon the server startup
128
-			and so the regular expression will be compiled before the server starts processing messages. When the server calls the exported function
129
-			to process a <acronym>SIP</acronym> message, the function will be given the already compiled regular expression and doesn't have to
130
-			compile it again. This is a significant performance improvement.
132
+			The fixup function can be used to perform some operation on the function
133
+			parameters. For example, if one of the parameters is a regular expression,
134
+			you can use the fixup to compile the regular expression. The fixup functions
135
+			are called only once - upon the server startup and so the regular expression
136
+			will be compiled before the server starts processing messages. When the
137
+			server calls the exported function to process a <acronym>SIP</acronym>
138
+			message, the function will be given the already compiled regular expression
139
+			and doesn't have to compile it again. This is a significant performance
140
+			improvement.
131 141
 		    </simpara>
132 142
 		    <simpara>
133
-			Fixup functions can also be used to convert string to integer. As you have might noticed, the exported functions accept up to 2
134
-			parameters of type char*. Because of that it is not possible to pass integer parameters from the script files directly. If you want to
135
-			pass an integer as a parameter, you must pass it as string (i.e. enclosed in quotes).
143
+			Fixup functions can also be used to convert string to integer. As you have
144
+			might noticed, the exported functions accept up to 2 parameters of type
145
+			char*. Because of that it is not possible to pass integer parameters from
146
+			the script files directly. If you want to pass an integer as a parameter,
147
+			you must pass it as string (i.e. enclosed in quotes).
136 148
 		    </simpara>
137 149
 		    <simpara>
138
-			Fixup function can be used to convert the string back to integer. Such a conversion should happend only once because the string
139
-			parameter doesn't change when the server is running. Fixup is therefore ideal place for the conversion, it will be converted upon the
140
-			server startup before the server starts processing <acronym>SIP</acronym> messages. After the conversion the function will get directly
141
-			the converted value. See existing modules for example of such a fixup function.
150
+			Fixup function can be used to convert the string back to integer. Such a
151
+			conversion should happend only once because the string parameter doesn't
152
+			change when the server is running. Fixup is therefore ideal place for the
153
+			conversion, it will be converted upon the server startup before the server
154
+			starts processing <acronym>SIP</acronym> messages. After the conversion the
155
+			function will get directly the converted value. See existing modules for
156
+			example of such a fixup function.
142 157
 		    </simpara>
143 158
 		</listitem>
144 159
 		<listitem>
145 160
 		    <simpara><varname>int flags</varname></simpara>
146 161
 		    <simpara>
147
-			Usage of each function can be restricted. You may want to write a function that can be used by other modules but cannot be called from
148
-			the script. If you write a function that is supposed to process <acronym>SIP</acronym> requests only, you may want to restrict it so it
149
-			will be never called for <acronym>SIP</acronym> replies and vice versa. That's what is flags field for.
162
+			Usage of each function can be restricted. You may want to write a function
163
+			that can be used by other modules but cannot be called from the script. If
164
+			you write a function that is supposed to process <acronym>SIP</acronym>
165
+			requests only, you may want to restrict it so it will be never called for
166
+			<acronym>SIP</acronym> replies and vice versa. That's what is flags field
167
+			for.
150 168
 		    </simpara>
151 169
 		    <simpara>
152
-			This field is OR value of different flags. Currently only REQUEST_ROUTE and REPLY_ROUTE flags are defined and used by the core. If you
153
-			use REQUEST_ROUTE flag, then the function can be called from the main route block. If you use REPLY_ROUTE flag, then the function can be
154
-			called from reply route blocks (More on this in the SER User's Guide). If this field is set to 0, then the function can be called
155
-			internally (i.e. from other modules) only. If you want to make your function callable anywhere in the script, you can use
170
+			This field is OR value of different flags. Currently only REQUEST_ROUTE and
171
+			REPLY_ROUTE flags are defined and used by the core. If you use REQUEST_ROUTE
172
+			flag, then the function can be called from the main route block. If you use
173
+			REPLY_ROUTE flag, then the function can be called from reply route blocks
174
+			(More on this in the SER User's Guide). If this field is set to 0, then the
175
+			function can be called internally (i.e. from other modules) only. If you
176
+			want to make your function callable anywhere in the script, you can use
156 177
 			REQUEST_ROUTE | REPLY_ROUTE.
157 178
 		    </simpara>
158 179
 		</listitem>
... ...
@@ -162,15 +197,20 @@ typedef int (*cmd_function)(struct sip_msg*, char*, char*);
162 162
 	    <title>Exporting Parameters</title>
163 163
 	    <abstract>
164 164
 		<simpara>
165
-		    Each module can provide zero or more parameters, which can affect the module's behaviour. This section gives a detailed description of
166
-		    structures describing exported parameters and passing this information to the core through the module interface.
165
+		    Each module can provide zero or more parameters, which can affect the module's
166
+		    behaviour. This section gives a detailed description of structures describing
167
+		    exported parameters and passing this information to the core through the module
168
+		    interface.
167 169
 		</simpara>
168 170
 	    </abstract>
169 171
 	    <simpara>
170
-		Each parameter exported by a module must be described by <structname>param_export_t</structname> structure. Structures describing all exported
171
-		parameters are arranged into an array and pointer to the array is then passed to the core. The last element of the array must contain 0 in all
172
-		it's fields, this element serves as the mark telling the core that this is the very last element and it must stop scanning the array (This is
173
-		same as in array of exported functions).
172
+		Each parameter exported by a module must be described by
173
+		<structname>param_export_t</structname> structure. Structures describing all
174
+		exported parameters are arranged into an array and pointer to the array is then
175
+		passed to the core. The last element of the array must contain 0 in all it's fields,
176
+		this element serves as the mark telling the core that this is the very last element
177
+		and it must stop scanning the array (This is same as in array of exported
178
+		functions).
174 179
 	    </simpara>
175 180
 	    <simpara>
176 181
 		Each exported parameter is described by the following structure:
... ...
@@ -190,22 +230,26 @@ typedef struct param_export_ param_export_t;
190 190
 		<listitem>
191 191
 		    <simpara><varname>char* name</varname></simpara>
192 192
 		    <simpara>
193
-			This is null-terminated name of the parametes as it will be used in the scripts. Usually this is the same as the name of the variable
194
-			holding the value.
193
+			This is null-terminated name of the parametes as it will be used in the
194
+			scripts. Usually this is the same as the name of the variable holding the
195
+			value.
195 196
 		    </simpara>
196 197
 		</listitem>
197 198
 		<listitem>
198 199
 		    <simpara><varname>modparam_t type</varname></simpara>
199 200
 		    <simpara>
200
-			Type of the parameter. Currently only two types are defined. INT_PARAM for integer parameters (corresponding variable must be of type
201
-			int) and STR_PARAM for string parameters (corresponding variable must be of type char*).
201
+			Type of the parameter. Currently only two types are defined. INT_PARAM for
202
+			integer parameters (corresponding variable must be of type int) and
203
+			STR_PARAM for string parameters (corresponding variable must be of type
204
+			char*).
202 205
 		    </simpara>
203 206
 		</listitem>
204 207
 		<listitem>
205 208
 		    <simpara><varname>void* param_pointer</varname></simpara>
206 209
 		    <simpara>
207
-			Pointer to the corresponding variable (stored as void* pointer, make sure that the variable has appropriate type depending on the type
208
-			of the parameter !).
210
+			Pointer to the corresponding variable (stored as void* pointer, make sure
211
+			that the variable has appropriate type depending on the type of the
212
+			parameter !).
209 213
 		    </simpara>
210 214
 		</listitem>
211 215
 	    </itemizedlist>
... ...
@@ -213,30 +257,38 @@ typedef struct param_export_ param_export_t;
213 213
 	<section>
214 214
 	    <title>Module Initialization</title>
215 215
 	    <simpara>
216
-		If you need to initialize your module before the server starts processing <acronym>SIP</acronym> messages, you should provide initialization
217
-		function. Each module can provide two initialization functions, main initialization function and child-specific initialization function.
218
-		Fields holding pointers to both initialization functions are in main export structure (will be described later). Simply pass 0 instead of
219
-		function pointer if you don't need one or both initialization functions.
216
+		If you need to initialize your module before the server starts processing
217
+		<acronym>SIP</acronym> messages, you should provide initialization function. Each
218
+		module can provide two initialization functions, main initialization function and
219
+		child-specific initialization function.  Fields holding pointers to both
220
+		initialization functions are in main export structure (will be described
221
+		later). Simply pass 0 instead of function pointer if you don't need one or both
222
+		initialization functions.
220 223
 	    </simpara>
221 224
 	    <simpara>
222
-		The main initialization function will be called before any other function exported by the module. The function will be called only once, before
223
-		the main process forks. This function is good for initialization that is common for all the children (processes). The function should return 0
224
-		if everything went OK and a negative error code otherwise. Server will abort if the function returns a negative value.
225
+		The main initialization function will be called before any other function exported
226
+		by the module. The function will be called only once, before the main process
227
+		forks. This function is good for initialization that is common for all the children
228
+		(processes). The function should return 0 if everything went OK and a negative error
229
+		code otherwise. Server will abort if the function returns a negative value.
225 230
 	    </simpara>
226 231
 	    <simpara>
227
-		Per-child initialization function will be called <emphasis>after</emphasis> the main process forks. The function will be called for each child
228
-		separately. The function should perform initialization that is specific for each child. For example each child process might open it's own
229
-		database connection to avoid locking of a single connection shared by many processes. Such connections can be opened in the per-child
230
-		initialization function. The function accepts one parameter which is rank (integer) of child for which the function is being executed. This
231
-		allows developers to distinguish different children and perform different initialization for each child. The meaning of return value is same as
232
-		in the main initialization function.
232
+		Per-child initialization function will be called <emphasis>after</emphasis> the main
233
+		process forks. The function will be called for each child separately. The function
234
+		should perform initialization that is specific for each child. For example each
235
+		child process might open it's own database connection to avoid locking of a single
236
+		connection shared by many processes. Such connections can be opened in the per-child
237
+		initialization function. The function accepts one parameter which is rank (integer)
238
+		of child for which the function is being executed. This allows developers to
239
+		distinguish different children and perform different initialization for each
240
+		child. The meaning of return value is same as in the main initialization function.
233 241
 	    </simpara>
234 242
 	</section>
235 243
 	<section>
236 244
 	    <title>Module Clean-up</title>
237 245
 	    <simpara>
238
-		A module can also export a clean-up function that will be called by the main process when the server shuts down. The function accepts no
239
-		parameters and return no value.
246
+		A module can also export a clean-up function that will be called by the main process
247
+		when the server shuts down. The function accepts no parameters and return no value.
240 248
 	    </simpara>
241 249
 	</section>
242 250
 	<section>
... ...
@@ -248,10 +300,13 @@ typedef struct param_export_ param_export_t;
248 248
 	<section>
249 249
 	    <title><structname>exports</structname> Structure - Assembling the Pieces Together</title>
250 250
 	    <simpara>
251
-		We have already described how a module can export functions and parameters, but we haven't yet described how to pass this information to the
252
-		core. Each module must have variable named <varname>exports</varname> which is structure module_exports. The variable will be looked up by the
253
-		core immediately after it loads the module. The structure contains pointers to both arrays (functions, parameters), pointers to both
254
-		initialization functions, destroy function and the callbacks. So the structure contains everything the core will need.
251
+		We have already described how a module can export functions and parameters, but we
252
+		haven't yet described how to pass this information to the core. Each module must
253
+		have variable named <varname>exports</varname> which is structure
254
+		module_exports. The variable will be looked up by the core immediately after it
255
+		loads the module. The structure contains pointers to both arrays (functions,
256
+		parameters), pointers to both initialization functions, destroy function and the
257
+		callbacks. So the structure contains everything the core will need.
255 258
 	    </simpara>
256 259
 	    <simpara>The structure looks like the follows:</simpara>
257 260
 	    <programlisting format="linespecific">