version: add a feature names array to curl_version_info_data #9583

monnerat · 2022-09-24T11:06:00Z

New field feature_names contains a pointer to a null-terminated sorted array of feature names. Bitmask field features is deprecated.

This will allow us to support more than 32 features.

Whether the strcasecmp4sort() procedure should be moved to strcase.c is questionable.

lib/version.c

bagder · 2022-09-27T12:47:02Z

docs/libcurl/curl_version_info.3

+
+\fIfeature_names\fP is a pointer to an array of string pointers, containing the
+names of the features that libcurl supports. The array is terminated by a NULL
+entry.


This mentions that features is deprecated, but the man page still only documents the bits in that bitmask. It says nothing about the potential names in feature_names that users of this function probably are very interested in. The list above should probably list both?

Yes, I can do it. Note this means the man page will still have to be updated when a new feature is introduced.

That was always the case. How is a user supposed to know what the feature means if it isn't documented?

As features is deprecated, do you expect me to remove the bit definitions in the doc ?

I think it is way too early for that. The documentation also needs to work as a resource for people reading existing code, and there will be code using these flags for the foreseeable future and then the documentation needs to describe them.

I think it is way too early for that.

Then the doc should be ready now !

bagder · 2022-09-28T07:13:47Z

docs/libcurl/curl_version_info.3

+libcurl was built with support for Unix domain sockets.
+.IP zstd
+supports HTTP zstd content encoding using zstd library.
+.RE


This is much better, but now you've duplicated the documentation for each feature, and they're not duplicated identically. I suggest we instead list each feature with both name and bitmask define name, and have one explanation for it.

Can I drop descriptions of CURL_VERSION_CONV and CURL_VERSION_KERBEROS4? They're obsolete and have no associated name. Reason: I want to label descriptions by names and these are not named! Or do I associate a dummy name that can never occur :-( ?

each feature with both name and bitmask define name, and have one explanation for it.

Done.
(I wish man had a built-in .TABLE macro!)

Oops! It seems the new documentation format causes test 1177 to fail :-(

bagder

If libcurl returns more/other features in its name list than the list in tool_libinfo.c knows about, I assume they will still get output fine?

bagder · 2022-11-08T12:50:48Z

docs/libcurl/curl_version_info.3

@@ -106,6 +110,9 @@ typedef struct {
  /* when 'age' is CURLVERSION_TENTH or higher (>= 7.77.0), the members
     below exist */
  const char *gsasl_version; /* human readable string. */
+  /* when 'age' is CURLVERSION_ELEVENTH or higher (>= 7.86.0), the members


7.87.0 now!!

Time past soooo fast !

bagder · 2022-11-08T12:52:18Z

docs/libcurl/symbols-in-versions

@@ -1097,6 +1097,7 @@ CURLUSESSL_CONTROL              7.17.0
 CURLUSESSL_NONE                 7.17.0
 CURLUSESSL_TRY                  7.17.0
 CURLVERSION_EIGHTH              7.72.0
+CURLVERSION_ELEVENTH            7.86.0


bagder · 2022-11-08T12:54:39Z

src/tool_libinfo.c

+  {"Kerberos",       NULL,                CURL_VERSION_KERBEROS5},
+  {"Largefile",      NULL,                CURL_VERSION_LARGEFILE},
+  {"libz",           &feature_libz,       CURL_VERSION_LIBZ},
+  {"MIME",           NULL,                0},


This is not an actual feature is it?

No it isn't. This is a leftover from local tests. Does not harm, but useless. Removed now.

monnerat · 2022-11-09T00:13:06Z

All your remarks taken into account now. Thanks for pointing on them.

If libcurl returns more/other features in its name list than the list in tool_libinfo.c knows about, I assume they will still get output fine?

Yes. the feature list is taken directly from the name array:

curl/src/tool_help.c

Lines 177 to 182 in f8b8dc4

    
           if(feature_names[0]) { 
        
             printf("Features:"); 
        
             for(builtin = feature_names; *builtin; ++builtin) 
        
               printf(" %s", *builtin); 
        
             puts(""); /* newline */ 
        
           }

In case an old library does not provide the feature array, the later is built by the tool from the flags:

curl/src/tool_libinfo.c

Lines 160 to 170 in f8b8dc4

    
           if(curlinfo->age >= CURLVERSION_ELEVENTH && curlinfo->feature_names) 
        
             feature_names = curlinfo->feature_names; 
        
           else { 
        
             const struct feature_name_presentp *p; 
        
             const char **cpp = fnames; 
        
             for(p = maybe_feature; p->feature_name; p++) 
        
               if(curlinfo->features & p->feature_bitmask) 
        
                 *cpp++ = p->feature_name; 
        
             *cpp = NULL; 
        
           }

Field feature_names contains a null-terminated sorted array of feature names. Bitmask field features is deprecated. Documentation is updated. Test 1177 and tests/version-scan.pl updated to match new documentation format and extended to check feature names too.

If the run-time libcurl is too old to support feature names, the name array is created locally from the bit masks. This is the only sequence left that uses feature bit masks.

Closes #9583

If the run-time libcurl is too old to support feature names, the name array is created locally from the bit masks. This is the only sequence left that uses feature bit masks. Closes #9583

bagder · 2022-11-14T08:19:54Z

Thanks!

monnerat marked this pull request as draft September 24, 2022 16:33

bagder reviewed Sep 24, 2022

View reviewed changes

lib/version.c Show resolved Hide resolved

monnerat force-pushed the feature-strings branch 5 times, most recently from 3adef61 to 34073e8 Compare September 25, 2022 17:51

jay mentioned this pull request Sep 25, 2022

vtls: use a thread lock for multissl init #9589

Closed

monnerat force-pushed the feature-strings branch from 34073e8 to 3881d12 Compare September 25, 2022 23:09

monnerat marked this pull request as ready for review September 26, 2022 10:59

monnerat force-pushed the feature-strings branch 3 times, most recently from 4eaf738 to f9dfa20 Compare September 27, 2022 10:34

bagder reviewed Sep 27, 2022

View reviewed changes

monnerat force-pushed the feature-strings branch from f9dfa20 to 3065804 Compare September 27, 2022 14:24

bagder reviewed Sep 28, 2022

View reviewed changes

monnerat force-pushed the feature-strings branch 4 times, most recently from d777418 to f3ce058 Compare September 29, 2022 11:33

jay added the libcurl API label Oct 2, 2022

monnerat force-pushed the feature-strings branch from f3ce058 to 7c2de16 Compare October 5, 2022 17:24

monnerat force-pushed the feature-strings branch from 7c2de16 to 07d5d8e Compare October 19, 2022 10:59

bagder added the feature-window A merge of this requires an open feature window label Oct 21, 2022

monnerat force-pushed the feature-strings branch 2 times, most recently from 5ec6880 to 5d08759 Compare October 29, 2022 16:50

bagder reviewed Nov 8, 2022

View reviewed changes

monnerat force-pushed the feature-strings branch from 5d08759 to f8b8dc4 Compare November 8, 2022 23:52

monnerat force-pushed the feature-strings branch from f8b8dc4 to ef124a8 Compare November 10, 2022 17:32

monnerat added 3 commits November 11, 2022 16:11

docs: curl_version_info is not thread-safe before libcurl initialization

99db4c5

tool: use feature names instead of bit mask, when possible

ae33f69

If the run-time libcurl is too old to support feature names, the name array is created locally from the bit masks. This is the only sequence left that uses feature bit masks.

monnerat force-pushed the feature-strings branch from ef124a8 to ae33f69 Compare November 11, 2022 15:23

bagder removed the feature-window A merge of this requires an open feature window label Nov 14, 2022

bagder closed this in e780aae Nov 14, 2022

bagder pushed a commit that referenced this pull request Nov 14, 2022

docs: curl_version_info is not thread-safe before libcurl initialization

e1e4825

Closes #9583

monnerat deleted the feature-strings branch November 14, 2022 12:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

version: add a feature names array to curl_version_info_data #9583

version: add a feature names array to curl_version_info_data #9583

monnerat commented Sep 24, 2022

bagder Sep 27, 2022 •

edited

monnerat Sep 27, 2022

bagder Sep 27, 2022

monnerat Sep 27, 2022

bagder Sep 27, 2022 •

edited

monnerat Sep 27, 2022

bagder Sep 28, 2022

monnerat Sep 28, 2022

monnerat Sep 28, 2022

monnerat Sep 28, 2022

bagder left a comment

bagder Nov 8, 2022

monnerat Nov 8, 2022

bagder Nov 8, 2022

monnerat Nov 8, 2022

bagder Nov 8, 2022

monnerat Nov 8, 2022 •

edited

monnerat commented Nov 9, 2022

bagder commented Nov 14, 2022

version: add a feature names array to curl_version_info_data #9583

version: add a feature names array to curl_version_info_data #9583

Conversation

monnerat commented Sep 24, 2022

bagder Sep 27, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bagder Sep 27, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bagder left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

monnerat Nov 8, 2022 • edited

Choose a reason for hiding this comment

monnerat commented Nov 9, 2022

bagder commented Nov 14, 2022

bagder Sep 27, 2022 •

edited

bagder Sep 27, 2022 •

edited

monnerat Nov 8, 2022 •

edited