xref: /curl/docs/libcurl/mksymbolsmanpage.pl (revision e3fe0200) 
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)
51---
52# libcurl symbols
53
54This man page details version information for public symbols provided in the
55libcurl header files. This lists the first version in which the symbol was
56introduced and for some symbols two additional information pieces:
57
58The first version in which the symbol is marked "deprecated" - meaning that
59since that version no new code should be written to use the symbol as it is
60marked for getting removed in a future.
61
62The last version that featured the specific symbol. Using the symbol in source
63code will make it no longer compile error-free after that specified version.
64
65This man page is automatically generated from the symbols-in-versions file.
66HEADER
67    ;
68
69sub nameref {
70    my ($n)=@_;
71    if($n =~ /^CURLOPT_/) {
72        if($n eq "CURLOPT_RTSPHEADER") {
73            $n = "CURLOPT_HTTPHEADER";
74        }
75        elsif($n eq "CURLOPT_WRITEHEADER") {
76            $n = "CURLOPT_HEADERDATA";
77        }
78        elsif($n eq "CURLOPT_WRITEINFO") {
79            ; # now obsolete
80        }
81        else {
82            return "$n(3)";
83        }
84    }
85    elsif($n =~ /^CURLMOPT_/) {
86        return "$n(3)";
87    }
88    elsif($n =~ /^CURLINFO_/) {
89        my %infotypes = (
90            'CURLINFO_TEXT' => 1,
91            'CURLINFO_HEADER_IN' => 1,
92            'CURLINFO_HEADER_OUT' => 1,
93            'CURLINFO_DATA_IN' => 1,
94            'CURLINFO_DATA_OUT' => 1,
95            'CURLINFO_SSL_DATA_IN' => 1,
96            'CURLINFO_SSL_DATA_OUT' => 1,
97            );
98        if($infotypes{$n}) {
99            return "CURLOPT_DEBUGFUNCTION(3)";
100        }
101    }
102    elsif($n =~ /^CURLALTSVC_/) {
103        return "CURLOPT_ALTSVC_CTRL(3)";
104    }
105    elsif($n =~ /^CURLAUTH_/) {
106        return "CURLOPT_HTTPAUTH(3)";
107    }
108    elsif($n =~ /^CURLFORM_/) {
109        return "curl_formadd(3)";
110    }
111    elsif($n =~ /^CURLKH/) {
112        return "CURLOPT_SSH_KEYFUNCTION(3)";
113    }
114    elsif($n =~ /^CURLE_/) {
115        return "libcurl-errors(3)";
116    }
117    elsif($n =~ /^CURLM_/) {
118        return "libcurl-errors(3)";
119    }
120    elsif($n =~ /^CURLUE_/) {
121        return "libcurl-errors(3)";
122    }
123    elsif($n =~ /^CURLHE_/) {
124        return "libcurl-errors(3)";
125    }
126    elsif($n =~ /^CURLSHE_/) {
127        return "libcurl-errors(3)";
128    }
129    elsif($n =~ /^CURLPROTO_/) {
130        return "CURLINFO_PROTOCOL(3)";
131    }
132    elsif($n =~ /^CURLPX_/) {
133        return "CURLINFO_PROXY_ERROR(3)";
134    }
135    elsif($n =~ /^CURLPROXY_/) {
136        return "CURLOPT_PROXYTYPE(3)";
137    }
138    elsif($n =~ /^CURLSSLBACKEND_/) {
139        return "curl_global_sslset(3)";
140    }
141    elsif($n =~ /^CURLSSLOPT_/) {
142        return "CURLOPT_SSL_OPTIONS(3)";
143    }
144    elsif($n =~ /^CURLSSLSET_/) {
145        return "curl_global_sslset(3)";
146    }
147    elsif($n =~ /^CURLUPART_/) {
148        return "curl_url_get(3)";
149    }
150    elsif($n =~ /^CURLU_/) {
151        return "curl_url_get(3)";
152    }
153    elsif($n =~ /^CURLVERSION_/) {
154        return "curl_version_info(3)";
155    }
156    elsif($n =~ /^CURLSHOPT_/) {
157        if($n eq "CURLSHOPT_NONE") {
158            $n = "curl_share_setopt";
159        }
160        return "$n(3)";
161    }
162    elsif($n =~ /^CURLWS_/) {
163        return "curl_ws_send(3)";
164    }
165    elsif($n =~ /^CURL_FORMADD_/) {
166        return "curl_formadd(3)";
167    }
168    elsif($n =~ /^CURL_HTTPPOST_/) {
169        return "curl_formadd(3)";
170    }
171    elsif($n =~ /^CURL_GLOBAL_/) {
172        return "curl_global_init(3)";
173    }
174    elsif($n =~ /^CURL_HTTP_VERSION_/) {
175        return "CURLOPT_HTTP_VERSION(3)";
176    }
177    elsif($n =~ /^CURL_LOCK_/) {
178        return "CURLSHOPT_SHARE(3)";
179    }
180    elsif($n =~ /^CURL_SSLVERSION_/) {
181        return "CURLOPT_SSLVERSION(3)";
182    }
183    elsif($n =~ /^CURL_VERSION_/) {
184        return "curl_version_info(3)";
185    }
186    elsif($n =~ /^CURL_RTSPREQ_/) {
187        return "CURLOPT_RTSP_REQUEST(3)";
188    }
189    elsif($n =~ /^CURLH_/) {
190        return "curl_easy_header(3)";
191    }
192    elsif($n =~ /^CURL_TRAILERFUNC_/) {
193        return "CURLOPT_TRAILERFUNCTION(3)";
194    }
195    elsif($n =~ /^CURLOT_/) {
196        return "curl_easy_option_next(3)";
197    }
198    elsif($n =~ /^CURLFINFOFLAG_/) {
199        return "CURLOPT_CHUNK_BGN_FUNCTION(3)";
200    }
201    elsif($n =~ /^CURLFILETYPE_/) {
202        return "CURLOPT_CHUNK_BGN_FUNCTION(3)";
203    }
204    elsif($n =~ /^CURL_CHUNK_BGN_FUNC_/) {
205        return "CURLOPT_CHUNK_BGN_FUNCTION(3)";
206    }
207    elsif($n =~ /^CURL_CHUNK_END_FUNC_/) {
208        return "CURLOPT_CHUNK_END_FUNCTION(3)";
209    }
210    elsif($n =~ /^CURLSSH_AUTH_/) {
211        return "CURLOPT_SSH_AUTH_TYPES(3)";
212    }
213    elsif($n =~ /^CURL_POLL_/) {
214        return "CURLMOPT_SOCKETFUNCTION(3)";
215    }
216    elsif($n =~ /^CURLMSG_/) {
217        return "curl_multi_info_read(3)";
218    }
219    elsif($n =~ /^CURLFTPAUTH_/) {
220        return "CURLOPT_FTPSSLAUTH(3)";
221    }
222    elsif($n =~ /^CURLFTPMETHOD_/) {
223        return "CURLOPT_FTP_FILEMETHOD(3)";
224    }
225    elsif($n =~ /^CURLFTPSSL_/) {
226        return "CURLOPT_USE_SSL(3)";
227    }
228    elsif($n =~ /^CURLFTP_CREATE_/) {
229        return "CURLOPT_FTP_CREATE_MISSING_DIRS(3)";
230    }
231    elsif($n =~ /^CURLGSSAPI_DELEGATION_/) {
232        return "CURLOPT_GSSAPI_DELEGATION(3)";
233    }
234    elsif($n =~ /^CURLHEADER_/) {
235        return "CURLOPT_HEADEROPT(3)";
236    }
237    elsif($n =~ /^CURLHSTS_/) {
238        return "CURLOPT_HSTS_CTRL(3)";
239    }
240    elsif($n =~ /^CURLIOCMD_/) {
241        return "CURLOPT_IOCTLFUNCTION(3)";
242    }
243    elsif($n =~ /^CURLIOE_/) {
244        return "CURLOPT_IOCTLFUNCTION(3)";
245    }
246    elsif($n =~ /^CURLMIMEOPT_/) {
247        return "CURLOPT_MIME_OPTIONS(3)";
248    }
249    elsif($n =~ /^CURLPAUSE_/) {
250        return "curl_easy_pause(3)";
251    }
252    elsif($n =~ /^CURLPIPE_/) {
253        return "CURLMOPT_PIPELINING(3)";
254    }
255    elsif($n =~ /^CURLSOCKTYPE_/) {
256        return "CURLOPT_SOCKOPTFUNCTION(3)";
257    }
258    elsif($n =~ /^CURLSTS_/) {
259        return "CURLOPT_HSTSREADFUNCTION(3)";
260    }
261    elsif($n =~ /^CURLUSESSL_/) {
262        return "CURLOPT_USE_SSL(3)";
263    }
264    elsif($n =~ /^CURL_CSELECT_/) {
265        return "curl_multi_socket_action(3)";
266    }
267    elsif($n =~ /^CURL_FNMATCHFUNC_/) {
268        return "CURLOPT_FNMATCH_FUNCTION(3)";
269    }
270    elsif($n =~ /^CURL_HET_/) {
271        return "CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)";
272    }
273    elsif($n =~ /^CURL_IPRESOLVE_/) {
274        return "CURLOPT_IPRESOLVE(3)";
275    }
276    elsif($n =~ /^CURL_SEEKFUNC_/) {
277        return "CURLOPT_SEEKFUNCTION(3)";
278    }
279    elsif($n =~ /^CURL_TIMECOND_/) {
280        return "CURLOPT_TIMECONDITION(3)";
281    }
282    elsif($n =~ /^CURL_REDIR_POST_/) {
283        return "CURLOPT_POSTREDIR(3)";
284    }
285}
286
287while(<STDIN>) {
288    if($_ =~ /^(CURL[A-Z0-9_.]*) *(.*)/i) {
289        my ($symbol, $rest)=($1,$2);
290        my ($intro, $dep, $rem);
291        if($rest =~ s/^([0-9.]*) *//) {
292           $intro = $1;
293        }
294        if($rest =~ s/^([0-9.]*) *//) {
295           $dep = $1;
296        }
297        if($rest =~ s/^- *([0-9.]*)//) {
298           $rem = $1;
299        }
300        print "\n## $symbol\nIntroduced in $intro.";
301        if($dep) {
302            print " Deprecated since $dep.";
303        }
304        if($rem) {
305            print " Last used in $rem.";
306        }
307        my $see = $rem || $dep ? "" : nameref($symbol);
308        if($see) {
309            print " See $see.";
310        }
311        print "\n";
312    }
313}
314