Add a .pragma directive for configuration files

[openssl.git] / doc / man5 / config.pod

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 7245132aa1c09e0f43f447d45301f1fdf5e0fe45..4b8465594af2b288edea3c4479c101e4a40fa992 100644 (file)
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -50,6 +50,9 @@ not support the B<.include> syntax. They would bail out with error
 if the B<=> character is not present but with it they just ignore
 the include.
 
+Pragmas can be specified with the B<.pragma> directive.
+See L</PRAGMAS> for mor information.
+
 Each section in a configuration file consists of a number of name and
 value pairs of the form B<name=value>
 
@@ -78,6 +81,40 @@ the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
 All expansion and escape rules as described above that apply to B<value>
 also apply to the path of the B<.include> directive.
 
+=head1 PRAGMAS
+
+Pragmas can be used to change the behavior of the configuration file
+parser, among others.  Currently supported pragmas are:
+
+=over 4
+
+=item B<.pragma> B<dollarid>:I<value>
+
+I<value> can be one of:
+
+=over 4
+
+=item  B<"on"> or B<"true">
+
+this signifies that dollar signs are considered an identity character
+from this point on and that variable expansion requires the use of
+braces or parentheses.  In other words, C<foo$bar> will be considered
+a name instead of C<foo> followed by the expansion of the variable
+C<bar>.
+This is suitable for platforms where the dollar sign is commonly used
+as part of names.
+
+=item B<"off"> or B<"false">
+
+Turns this pragma off, i.e. C<foo$bar> will be interpreted as C<foo>
+followed by the expansion of the variable C<bar>.
+
+=back
+
+By default, this pragma is turned off.
+
+=back
+
 =head1 OPENSSL LIBRARY CONFIGURATION
 
 Applications can automatically configure certain
@@ -507,9 +544,20 @@ Files are loaded in a single pass. This means that an variable expansion
 will only work if the variables referenced are defined earlier in the
 file.
 
+=head1 HISTORY
+
+An undocumented API, NCONF_WIN32(), used a slightly different set
+of parsing rules there were intended to be tailored to
+the Microsoft Windows platform.
+Specifically, the backslash character was not an escape character and
+could be used in pathnames, only the double-quote character was recognized,
+and comments began with a semi-colon.
+This function was deprecated in OpenSSL 3.0; applications with
+configuration files using that syntax will have to be modified.
+
 =head1 SEE ALSO
 
-L<x509(1)>, L<req(1)>, L<ca(1)>, L<fips_config(5)>
+L<openssl-x509(1)>, L<openssl-req(1)>, L<openssl-ca(1)>, L<fips_config(5)>
 
 =head1 COPYRIGHT