xref: /curl/docs/libcurl/mksymbolsmanpage.pl (revision 8c1d9378) 
1#!/usr/bin/env perl
2# ***************************************************************************
3# *                                  _   _ ____  _
4# *  Project                     ___| | | |  _ \| |
5# *                             / __| | | | |_) | |
6# *                            | (__| |_| |  _ <| |___
7# *                             \___|\___/|_| \_\_____|
8# *
9# * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
10# *
11# * This software is licensed as described in the file COPYING, which
12# * you should have received as part of this distribution. The terms
13# * are also available at https://curl.se/docs/copyright.html.
14# *
15# * You may opt to use, copy, modify, merge, publish, distribute and/or sell
16# * copies of the Software, and permit persons to whom the Software is
17# * furnished to do so, under the terms of the COPYING file.
18# *
19# * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
20# * KIND, either express or implied.
21# *
22# * SPDX-License-Identifier: curl
23# *
24# ***************************************************************************
25
26use POSIX qw(strftime);
27my @ts;
28if (defined($ENV{SOURCE_DATE_EPOCH})) {
29    @ts = localtime($ENV{SOURCE_DATE_EPOCH});
30} else {
31    @ts = localtime;
32}
33my $date = strftime "%b %e, %Y", @ts;
34my $year = strftime "%Y", @ts;
35
36print <<HEADER
37---
38c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
39SPDX-License-Identifier: curl
40Title: libcurl-symbols
41Section: 3
42Source: libcurl
43Protocol:
44  - All
45See-also:
46  - libcurl (3)
47  - libcurl-easy (3)
48  - libcurl-multi (3)
49  - libcurl-security (3)
50  - libcurl-thread (3)
51Added-in: n/a
52---
53# libcurl symbols
54
55This man page details version information for public symbols provided in the
56libcurl header files. This lists the first version in which the symbol was
57introduced and for some symbols two additional information pieces:
58
59The first version in which the symbol is marked "deprecated" - meaning that
60since that version no new code should be written to use the symbol as it is
61marked for getting removed in a future.
62
63The last version that featured the specific symbol. Using the symbol in source
64code makes it no longer compile error-free after that specified version.
65
66This man page is automatically generated from the symbols-in-versions file.
67HEADER
68    ;
69
70sub nameref {
71    my ($n)=@_;
72    if($n =~ /^CURLOPT_/) {
73        if($n eq "CURLOPT_RTSPHEADER") {
74            $n = "CURLOPT_HTTPHEADER";
75        }
76        elsif($n eq "CURLOPT_WRITEHEADER") {
77            $n = "CURLOPT_HEADERDATA";
78        }
79        elsif($n eq "CURLOPT_WRITEINFO") {
80            ; # now obsolete
81        }
82        else {
83            return "$n(3)";
84        }
85    }
86    elsif($n =~ /^CURLMOPT_/) {
87        return "$n(3)";
88    }
89    elsif($n =~ /^CURLINFO_/) {
90        my %infotypes = (
91            'CURLINFO_TEXT' => 1,
92            'CURLINFO_HEADER_IN' => 1,
93            'CURLINFO_HEADER_OUT' => 1,
94            'CURLINFO_DATA_IN' => 1,
95            'CURLINFO_DATA_OUT' => 1,
96            'CURLINFO_SSL_DATA_IN' => 1,
97            'CURLINFO_SSL_DATA_OUT' => 1,
98            );
99        if($infotypes{$n}) {
100            return "CURLOPT_DEBUGFUNCTION(3)";
101        }
102    }
103    elsif($n =~ /^CURLALTSVC_/) {
104        return "CURLOPT_ALTSVC_CTRL(3)";
105    }
106    elsif($n =~ /^CURLAUTH_/) {
107        return "CURLOPT_HTTPAUTH(3)";
108    }
109    elsif($n =~ /^CURLFORM_/) {
110        return "curl_formadd(3)";
111    }
112    elsif($n =~ /^CURLKH/) {
113        return "CURLOPT_SSH_KEYFUNCTION(3)";
114    }
115    elsif($n =~ /^CURLE_/) {
116        return "libcurl-errors(3)";
117    }
118    elsif($n =~ /^CURLM_/) {
119        return "libcurl-errors(3)";
120    }
121    elsif($n =~ /^CURLUE_/) {
122        return "libcurl-errors(3)";
123    }
124    elsif($n =~ /^CURLHE_/) {
125        return "libcurl-errors(3)";
126    }
127    elsif($n =~ /^CURLSHE_/) {
128        return "libcurl-errors(3)";
129    }
130    elsif($n =~ /^CURLPROTO_/) {
131        return "CURLINFO_PROTOCOL(3)";
132    }
133    elsif($n =~ /^CURLPX_/) {
134        return "CURLINFO_PROXY_ERROR(3)";
135    }
136    elsif($n =~ /^CURLPROXY_/) {
137        return "CURLOPT_PROXYTYPE(3)";
138    }
139    elsif($n =~ /^CURLSSLBACKEND_/) {
140        return "curl_global_sslset(3)";
141    }
142    elsif($n =~ /^CURLSSLOPT_/) {
143        return "CURLOPT_SSL_OPTIONS(3)";
144    }
145    elsif($n =~ /^CURLSSLSET_/) {
146        return "curl_global_sslset(3)";
147    }
148    elsif($n =~ /^CURLUPART_/) {
149        return "curl_url_get(3)";
150    }
151    elsif($n =~ /^CURLU_/) {
152        return "curl_url_get(3)";
153    }
154    elsif($n =~ /^CURLVERSION_/) {
155        return "curl_version_info(3)";
156    }
157    elsif($n =~ /^CURLSHOPT_/) {
158        if($n eq "CURLSHOPT_NONE") {
159            $n = "curl_share_setopt";
160        }
161        return "$n(3)";
162    }
163    elsif($n =~ /^CURLWS_/) {
164        return "curl_ws_send(3)";
165    }
166    elsif($n =~ /^CURL_FORMADD_/) {
167        return "curl_formadd(3)";
168    }
169    elsif($n =~ /^CURL_HTTPPOST_/) {
170        return "curl_formadd(3)";
171    }
172    elsif($n =~ /^CURL_GLOBAL_/) {
173        return "curl_global_init(3)";
174    }
175    elsif($n =~ /^CURL_HTTP_VERSION_/) {
176        return "CURLOPT_HTTP_VERSION(3)";
177    }
178    elsif($n =~ /^CURL_LOCK_/) {
179        return "CURLSHOPT_SHARE(3)";
180    }
181    elsif($n =~ /^CURL_SSLVERSION_/) {
182        return "CURLOPT_SSLVERSION(3)";
183    }
184    elsif($n =~ /^CURL_VERSION_/) {
185        return "curl_version_info(3)";
186    }
187    elsif($n =~ /^CURL_RTSPREQ_/) {
188        return "CURLOPT_RTSP_REQUEST(3)";
189    }
190    elsif($n =~ /^CURLH_/) {
191        return "curl_easy_header(3)";
192    }
193    elsif($n =~ /^CURL_TRAILERFUNC_/) {
194        return "CURLOPT_TRAILERFUNCTION(3)";
195    }
196    elsif($n =~ /^CURLOT_/) {
197        return "curl_easy_option_next(3)";
198    }
199    elsif($n =~ /^CURLFINFOFLAG_/) {
200        return "CURLOPT_CHUNK_BGN_FUNCTION(3)";
201    }
202    elsif($n =~ /^CURLFILETYPE_/) {
203        return "CURLOPT_CHUNK_BGN_FUNCTION(3)";
204    }
205    elsif($n =~ /^CURL_CHUNK_BGN_FUNC_/) {
206        return "CURLOPT_CHUNK_BGN_FUNCTION(3)";
207    }
208    elsif($n =~ /^CURL_CHUNK_END_FUNC_/) {
209        return "CURLOPT_CHUNK_END_FUNCTION(3)";
210    }
211    elsif($n =~ /^CURLSSH_AUTH_/) {
212        return "CURLOPT_SSH_AUTH_TYPES(3)";
213    }
214    elsif($n =~ /^CURL_POLL_/) {
215        return "CURLMOPT_SOCKETFUNCTION(3)";
216    }
217    elsif($n =~ /^CURLMSG_/) {
218        return "curl_multi_info_read(3)";
219    }
220    elsif($n =~ /^CURLFTPAUTH_/) {
221        return "CURLOPT_FTPSSLAUTH(3)";
222    }
223    elsif($n =~ /^CURLFTPMETHOD_/) {
224        return "CURLOPT_FTP_FILEMETHOD(3)";
225    }
226    elsif($n =~ /^CURLFTPSSL_/) {
227        return "CURLOPT_USE_SSL(3)";
228    }
229    elsif($n =~ /^CURLFTP_CREATE_/) {
230        return "CURLOPT_FTP_CREATE_MISSING_DIRS(3)";
231    }
232    elsif($n =~ /^CURLGSSAPI_DELEGATION_/) {
233        return "CURLOPT_GSSAPI_DELEGATION(3)";
234    }
235    elsif($n =~ /^CURLHEADER_/) {
236        return "CURLOPT_HEADEROPT(3)";
237    }
238    elsif($n =~ /^CURLHSTS_/) {
239        return "CURLOPT_HSTS_CTRL(3)";
240    }
241    elsif($n =~ /^CURLIOCMD_/) {
242        return "CURLOPT_IOCTLFUNCTION(3)";
243    }
244    elsif($n =~ /^CURLIOE_/) {
245        return "CURLOPT_IOCTLFUNCTION(3)";
246    }
247    elsif($n =~ /^CURLMIMEOPT_/) {
248        return "CURLOPT_MIME_OPTIONS(3)";
249    }
250    elsif($n =~ /^CURLPAUSE_/) {
251        return "curl_easy_pause(3)";
252    }
253    elsif($n =~ /^CURLPIPE_/) {
254        return "CURLMOPT_PIPELINING(3)";
255    }
256    elsif($n =~ /^CURLSOCKTYPE_/) {
257        return "CURLOPT_SOCKOPTFUNCTION(3)";
258    }
259    elsif($n =~ /^CURLSTS_/) {
260        return "CURLOPT_HSTSREADFUNCTION(3)";
261    }
262    elsif($n =~ /^CURLUSESSL_/) {
263        return "CURLOPT_USE_SSL(3)";
264    }
265    elsif($n =~ /^CURL_CSELECT_/) {
266        return "curl_multi_socket_action(3)";
267    }
268    elsif($n =~ /^CURL_FNMATCHFUNC_/) {
269        return "CURLOPT_FNMATCH_FUNCTION(3)";
270    }
271    elsif($n =~ /^CURL_HET_/) {
272        return "CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)";
273    }
274    elsif($n =~ /^CURL_IPRESOLVE_/) {
275        return "CURLOPT_IPRESOLVE(3)";
276    }
277    elsif($n =~ /^CURL_SEEKFUNC_/) {
278        return "CURLOPT_SEEKFUNCTION(3)";
279    }
280    elsif($n =~ /^CURL_TIMECOND_/) {
281        return "CURLOPT_TIMECONDITION(3)";
282    }
283    elsif($n =~ /^CURL_REDIR_POST_/) {
284        return "CURLOPT_POSTREDIR(3)";
285    }
286}
287
288while(<STDIN>) {
289    if($_ =~ /^(CURL[A-Z0-9_.]*) *(.*)/i) {
290        my ($symbol, $rest)=($1,$2);
291        my ($intro, $dep, $rem);
292        if($rest =~ s/^([0-9.]*) *//) {
293           $intro = $1;
294        }
295        if($rest =~ s/^([0-9.]*) *//) {
296           $dep = $1;
297        }
298        if($rest =~ s/^- *([0-9.]*)//) {
299           $rem = $1;
300        }
301        print "\n## $symbol\nIntroduced in $intro.";
302        if($dep) {
303            print " Deprecated since $dep.";
304        }
305        if($rem) {
306            print " Last used in $rem.";
307        }
308        my $see = $rem || $dep ? "" : nameref($symbol);
309        if($see) {
310            print " See $see.";
311        }
312        print "\n";
313    }
314}
315