← Back to branch summary

~ubuntu-branches/ubuntu/hardy/openswan/hardy-updates

« back to all changes in this revision

Viewing changes to lib/libopenswan/atoul.3.xml

  • Committer: Bazaar Package Importer
  • Author(s): Rene Mayrhofer
  • Date: 2005-01-27 16:10:11 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050127161011-idgybmyz3vwhpfiq
Tags: 2.3.0-2
http://bugs.debian.org/292458
http://bugs.debian.org/291143
Urgency HIGH due to security issue and problems with build-deps in sarge.
* Fix the security issue. Please see
  http://www.idefense.com/application/poi/display?id=190&
      type=vulnerabilities&flashstatus=false
  for more details. Thanks to Martin Schulze for informing me about
  this issue.
  Closes: #292458: Openswan XAUTH/PAM Buffer Overflow Vulnerability
* Added a Build-Dependency to lynx.
  Closes: #291143: openswan: FTBFS: Missing build dependency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/libopenswan/atoul.3.xml
 
1
<?xml version="1.0" encoding="ISO-8859-1"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
4
<!-- lifted from troff+man by doclifter -->
 
5
<refentry>
 
6
<refmeta>
 
7
<refentrytitle>IPSEC_ATOUL</refentrytitle>
 
8
<manvolnum>3</manvolnum>
 
9
<refmiscinfo class='date'>11 June 2001</refmiscinfo>
 
10
</refmeta>
 
11
<refnamediv id='name'>
 
12
<refname>ipsec atoul</refname>
 
13
<refname>ultoa</refname>
 
14
<refpurpose>convert unsigned-long numbers to and from ASCII</refpurpose>
 
15
</refnamediv>
 
16
<!-- body begins here -->
 
17
<refsynopsisdiv id='synopsis'>
 
18
<funcsynopsis>
 
19
<funcsynopsisinfo>
 
20
#include &lt;freeswan.h&gt;
 
21
 
 
22
</funcsynopsisinfo>
 
23
<funcprototype>
 
24
<funcdef>const char *<function>atoul</function></funcdef>
 
25
    <paramdef>const char * <parameter>src</parameter></paramdef>
 
26
    <paramdef>size_t <parameter>srclen</parameter></paramdef>
 
27
    <paramdef>int <parameter>base</parameter></paramdef>
 
28
    <paramdef>unsigned long * <parameter>n</parameter></paramdef>
 
29
</funcprototype>
 
30
<funcsynopsisinfo>
 
31
 
 
32
</funcsynopsisinfo>
 
33
<funcprototype>
 
34
<funcdef>size_t <function>ultoa</function></funcdef>
 
35
    <paramdef>unsigned long <parameter>n</parameter></paramdef>
 
36
    <paramdef>int <parameter>base</parameter></paramdef>
 
37
    <paramdef>char * <parameter>dst</parameter></paramdef>
 
38
    <paramdef>size_t <parameter>dstlen</parameter></paramdef>
 
39
</funcprototype>
 
40
</funcsynopsis>
 
41
</refsynopsisdiv>
 
42
 
 
43
 
 
44
<refsect1 id='description'><title>DESCRIPTION</title>
 
45
<para>These functions are obsolete; see
 
46
<citerefentry><refentrytitle>ipsec_ttoul</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 
47
for their replacements.</para>
 
48
 
 
49
<para><emphasis remap='I'>Atoul</emphasis>
 
50
converts an ASCII number into a binary
 
51
<emphasis remap='B'>unsigned long</emphasis>
 
52
value.
 
53
<emphasis remap='I'>Ultoa</emphasis>
 
54
does the reverse conversion, back to an ASCII version.</para>
 
55
 
 
56
<para>Numbers are specified in ASCII as
 
57
decimal (e.g.
 
58
<literal>123</literal>),
 
59
octal with a leading zero (e.g.
 
60
<literal>012</literal>,
 
61
which has value 10),
 
62
or hexadecimal with a leading
 
63
<emphasis remap='B'>0x</emphasis>
 
64
(e.g.
 
65
<emphasis remap='B'>0x1f</emphasis>,
 
66
which has value 31)
 
67
in either upper or lower case.</para>
 
68
 
 
69
<para>The
 
70
<varname role='parameter'>srclen</varname>
 
71
parameter of
 
72
<function>atoul</function>
 
73
specifies the length of the ASCII string pointed to by
 
74
<varname role='parameter'>src</varname>;
 
75
it is an error for there to be anything else
 
76
(e.g., a terminating NUL) within that length.
 
77
As a convenience for cases where an entire NUL-terminated string is
 
78
to be converted,
 
79
a
 
80
<varname role='parameter'>srclen</varname>
 
81
value of
 
82
<literal>0</literal>
 
83
is taken to mean
 
84
<emphasis remap='B'>strlen(src)</emphasis>.</para>
 
85
 
 
86
<para>The
 
87
<varname role='parameter'>base</varname>
 
88
parameter of
 
89
<function>atoul</function>
 
90
can be
 
91
<literal>8</literal>,
 
92
<literal>10</literal>,
 
93
or
 
94
<literal>16</literal>,
 
95
in which case the number supplied is assumed to be of that form
 
96
(and in the case of
 
97
<literal>16</literal>,
 
98
to lack any
 
99
<emphasis remap='B'>0x</emphasis>
 
100
prefix).
 
101
It can also be
 
102
<literal>0</literal>,
 
103
in which case the number is examined for a leading zero
 
104
or a leading
 
105
<emphasis remap='B'>0x</emphasis>
 
106
to determine its base,
 
107
or
 
108
<literal>13</literal>
 
109
(halfway between 10 and 16),
 
110
which has the same effect as
 
111
<literal>0</literal>
 
112
except that a non-hexadecimal
 
113
number is considered decimal regardless of any leading zero.</para>
 
114
 
 
115
<para>The
 
116
<varname role='parameter'>dstlen</varname>
 
117
parameter of
 
118
<function>ultoa</function>
 
119
specifies the size of the
 
120
<varname role='parameter'>dst</varname>
 
121
parameter;
 
122
under no circumstances are more than
 
123
<varname role='parameter'>dstlen</varname>
 
124
bytes written to
 
125
<varname role='parameter'>dst</varname>.
 
126
A result which will not fit is truncated.
 
127
<emphasis remap='I'>Dstlen</emphasis>
 
128
can be zero, in which case
 
129
<varname role='parameter'>dst</varname>
 
130
need not be valid and no result is written,
 
131
but the return value is unaffected;
 
132
in all other cases, the (possibly truncated) result is NUL-terminated.</para>
 
133
 
 
134
<para>The
 
135
<varname role='parameter'>base</varname>
 
136
parameter of
 
137
<function>ultoa</function>
 
138
must be
 
139
<literal>8</literal>,
 
140
<literal>10</literal>,
 
141
or
 
142
<literal>16</literal>.</para>
 
143
 
 
144
<para><emphasis remap='I'>Atoul</emphasis>
 
145
returns NULL for success and
 
146
a pointer to a string-literal error message for failure;
 
147
see DIAGNOSTICS.
 
148
<emphasis remap='I'>Ultoa</emphasis>
 
149
returns the size of buffer which would 
 
150
be needed to
 
151
accommodate the full conversion result, including terminating NUL;
 
152
it is the caller's responsibility to check this against the size of
 
153
the provided buffer to determine whether truncation has occurred.</para>
 
154
</refsect1>
 
155
 
 
156
<refsect1 id='see_also'><title>SEE ALSO</title>
 
157
<para><citerefentry><refentrytitle>atol</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>strtoul</refentrytitle><manvolnum>3</manvolnum></citerefentry></para>
 
158
</refsect1>
 
159
 
 
160
<refsect1 id='diagnostics'><title>DIAGNOSTICS</title>
 
161
<para>Fatal errors in
 
162
<function>atoul</function>
 
163
are:
 
164
empty input;
 
165
unknown
 
166
<varname role='parameter'>base</varname>;
 
167
non-digit character found;
 
168
number too large for an
 
169
<emphasis remap='B'>unsigned long</emphasis>.</para>
 
170
</refsect1>
 
171
 
 
172
<refsect1 id='history'><title>HISTORY</title>
 
173
<para>Written for the FreeS/WAN project by Henry Spencer.</para>
 
174
</refsect1>
 
175
 
 
176
<refsect1 id='bugs'><title>BUGS</title>
 
177
<para>There is no provision for reporting an invalid
 
178
<varname role='parameter'>base</varname>
 
179
parameter given to
 
180
<function>ultoa</function>.</para>
 
181
 
 
182
<para>The restriction of error reports to literal strings
 
183
(so that callers don't need to worry about freeing them or copying them)
 
184
does limit the precision of error reporting.</para>
 
185
 
 
186
<para>The error-reporting convention lends itself to slightly obscure code,
 
187
because many readers will not think of NULL as signifying success.
 
188
A good way to make it clearer is to write something like:</para>
 
189
 
 
190
<!-- .RS -->
 
191
<literallayout remap='.nf'>
 
192
<emphasis remap='B'>const char *error;</emphasis>
 
193
 
 
194
<emphasis remap='B'>error = atoul( /* ... */ );</emphasis>
 
195
<emphasis remap='B'>if (error != NULL) {</emphasis>
 
196
<emphasis remap='B'>        /* something went wrong */</emphasis>
 
197
</literallayout> <!-- .fi -->
 
198
</refsect1>
 
199
</refentry>
 
200