Require ATS plugins to be compiled with C++17

doc/admin-guide/files/records.yaml.en.rst

@@ -4173,7 +4173,7 @@ Client-Related Configuration
    Can be useful if using a crypto engine that communicates off chip.  The
    thread will be rescheduled for other work until the crypto engine operation
    completes. A test crypto engine that inserts a 5 second delay on private key
-   operations can be found at :ts:git:`contrib/openssl/async_engine.c`.
+   operations can be found at :ts:git:`contrib/openssl/async_engine.cc`.
 
 .. ts:cv:: CONFIG proxy.config.ssl.engine.conf_file STRING NULL
 

doc/developer-guide/api/functions/TSClientProtocolStack.en.rst

@@ -61,15 +61,15 @@ protocol :arg:`tag` being present in the stack.
 Each protocol is represented by tag which is a null terminated string. A particular tag will always
 be returned as the same character pointer and so protocols can be reliably checked with pointer
 comparisons. :func:`TSNormalizedProtocolTag` will return this character pointer for a specific
-:arg:`tag`. A return value of :const:`NULL` indicates the provided :arg:`tag` is not registered as
+:arg:`tag`. A return value of :const:`nullptr` indicates the provided :arg:`tag` is not registered as
 a known protocol tag. :func:`TSRegisterProtocolTag` registers the :arg:`tag` and then returns its
 normalized value. This is useful for plugins that provide custom protocols for user agents.
 
 The protocols are ordered from higher level protocols to the lower level ones on which the higher
 operate. For instance a stack might look like "http/1.1,tls/1.2,tcp,ipv4". For
 :func:`TSHttpTxnClientProtocolStackGet`, :func:`TSHttpSsnClientProtocolStackGet`, and :func:`TSHttpTxnServerProtocolStackGet` these values
 are placed in the array :arg:`result`. :arg:`count` is the maximum number of elements of
-:arg:`result` that may be modified by the function call. If :arg:`actual` is not :const:`NULL` then
+:arg:`result` that may be modified by the function call. If :arg:`actual` is not :const:`nullptr` then
 the actual number of elements in the protocol stack will be returned. If this is equal or less than
 :arg:`count` then all elements were returned. If it is larger then some layers were omitted from
 :arg:`result`. If the full stack is required :arg:`actual` can be used to resize :arg:`result` to
@@ -80,7 +80,7 @@ than 10 which therefore should suffice. These functions return :const:`TS_SUCCES
 
 The :func:`TSHttpTxnClientProtocolStackContains`, :func:`TSHttpSsnClientProtocolStackContains`, and :func:`TSHttpTxnServerProtocolStackContains`
 functions are provided for the convenience when only the presence of a protocol is of interest, not
-its location or the presence of other protocols. These functions return :const:`NULL` if the protocol
+its location or the presence of other protocols. These functions return :const:`nullptr` if the protocol
 :arg:`tag` is not present, and a pointer to the normalized tag if it is present. The strings are
 matched with an anchor prefix search, as with debug tags. For instance if :arg:`tag` is "tls" then it
 will match "tls/1.2" or "tls/1.3". This makes checking for TLS or IP more convenient. If more precision

doc/developer-guide/api/functions/TSHttpConnectWithPluginId.en.rst

@@ -61,7 +61,7 @@ stack via the loopback interface.
    the connection. It is accessible via the log field :ref:`pitag
    <pitag>`. This is intended as a class or type identifier that
    is consistent across all connections for this plugin. In effect,
-   the name of the plugin. This can be :literal:`NULL`.
+   the name of the plugin. This can be :literal:`nullptr`.
 
 :arg:`id`
    This is a numeric identifier that is passed through to the HTTP

doc/developer-guide/api/functions/TSHttpHookAdd.en.rst

@@ -141,7 +141,7 @@ transaction hooks::
     TSPluginInit (int argc, const char *argv[])
     {
         TSCont contp;
-        contp = TSContCreate(handler, NULL);
+        contp = TSContCreate(handler, nullptr);
         TSHttpHookAdd(TS_HTTP_SSN_START_HOOK, contp);
     }
 

doc/developer-guide/api/functions/TSHttpParserCreate.en.rst

@@ -68,7 +68,7 @@ It should be called after :data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`.
 may be used again.
 
 :func:`TSHttpParserDestroy` destroys the TSHttpParser object pointed
-to by :arg:`parser`. The :arg:`parser` pointer must not be NULL.
+to by :arg:`parser`. The :arg:`parser` pointer must not be nullptr.
 
 Return Values
 =============

doc/developer-guide/api/functions/TSHttpTxnOutgoingAddrGet.en.rst

@@ -54,5 +54,5 @@ what was passing :arg:`addr` if :ts:cv:`session sharing <proxy.config.http.serve
 Conversely :func:`TSHttpTxnOutgoingAddrGet` retrieves the local address and must be called in the
 :macro:`TS_HTTP_SEND_REQUEST_HDR_HOOK` or later, after the outbound connection has been established. It returns a
 pointer to a :code:`sockaddr` which contains the local IP address and port. If there is no valid
-outbound connection, :arg:`addr` will be :code:`NULL`. The returned pointer is a transient pointer
+outbound connection, :arg:`addr` will be :code:`nullptr`. The returned pointer is a transient pointer
 and must not be referenced after the callback in which :func:`TSHttpTxnOutgoingAddrGet` was called.

doc/developer-guide/api/functions/TSHttpTxnPostBufferReaderGet.en.rst

@@ -55,7 +55,7 @@ handler makes use of :c:func:`TSHttpTxnPostBufferReaderGet`.
 
        int64_t consumed      = 0;
        TSIOBufferBlock block = TSIOBufferReaderStart(post_buffer_reader);
-       while (block != NULL) {
+       while (block != nullptr) {
          int64_t data_len        = 0;
          const char *block_bytes = TSIOBufferBlockReadStart(block, post_buffer_reader, &data_len);
          memcpy(body_bytes + consumed, block_bytes, data_len);
@@ -74,5 +74,5 @@ handler makes use of :c:func:`TSHttpTxnPostBufferReaderGet`.
      return 0;
    }
 
-:ts:git:`example/plugins/c-api/request_buffer/request_buffer.c` is a simple
+:ts:git:`example/plugins/c-api/request_buffer/request_buffer.cc` is a simple
 yet complete plugin that accesses HTTP request bodies.

doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst

@@ -61,7 +61,7 @@ Types
       and not :func:`TSPluginInit`.
 
       Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_INITIALIZED` and
-      ``NULL`` data.
+      ``nullptr`` data.
 
    .. cpp:enumerator:: TS_LIFECYCLE_PORTS_READY_HOOK
 
@@ -71,14 +71,14 @@ Types
       is called will be accepted by |TS|, making this a convenient place to signal
       external processes of that.
 
-      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_READY` and ``NULL``
+      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_PORTS_READY` and ``nullptr``
       data.
 
    .. cpp:enumerator:: TS_LIFECYCLE_CACHE_READY_HOOK
 
       Called after |TS| cache initialization has finished.
 
-      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_CACHE_READY` and ``NULL``
+      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_CACHE_READY` and ``nullptr``
       data.
 
    .. cpp:enumerator:: TS_LIFECYCLE_MSG_HOOK
@@ -103,7 +103,7 @@ Types
 
       Called after |TS| task threads have been started.
 
-      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_TASK_THREADS_READY` and ``NULL``
+      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_TASK_THREADS_READY` and ``nullptr``
       data.
 
    .. cpp:enumerator:: TS_LIFECYCLE_SSL_SECRET_HOOK
@@ -118,7 +118,7 @@ Types
 
       Called after |TS| receiving a shutdown signal, such as SIGTERM.
 
-      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_SHUTDOWN` and ``NULL`` data.
+      Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_SHUTDOWN` and ``nullptr`` data.
 
 .. c:struct:: TSPluginMsg
 
@@ -177,7 +177,7 @@ directly.
    void
    TSPluginInit (int argc, const char * argv[])
    {
-      TSLifecycleHookAdd(TS_LIFECYCLE_PORTS_INITIALIZED_HOOK, TSContCreate(local_ssl_init, NULL));
+      TSLifecycleHookAdd(TS_LIFECYCLE_PORTS_INITIALIZED_HOOK, TSContCreate(local_ssl_init, nullptr));
    }
 
 History

doc/developer-guide/api/functions/TSPluginInit.en.rst

@@ -36,7 +36,8 @@ Synopsis
 Description
 ===========
 
-:func:`TSPluginInit` must be defined by all plugins. Traffic Server
+:func:`TSPluginInit` must be defined by all plugins. It should be at global
+scope (not in any namespace). Traffic Server
 calls this initialization routine when it loads the plugin and sets
 :arg:`argc` and :arg:`argv` appropriately based on the values in
 :file:`plugin.config`.

doc/developer-guide/api/functions/TSSslClientContext.en.rst

@@ -46,7 +46,7 @@ of lookup keys (2 for each context).
 :func:`TSSslClientContextFindByName` can be used to retrieve the client context pointed by the lookup
 key pairs. User should call :func:`TSSslClientContextsNamesGet` first to determine which lookup keys are
 present before querying for the context. :arg:`ca_paths` should be the first key and :arg:`ck_paths`
-should be the second. This function returns NULL if the client context mapping are changed and no valid
+should be the second. This function returns nullptr if the client context mapping are changed and no valid
 context exists for the key pair. The caller is responsible for releasing the context returned by this
 function with :func:`TSSslContextDestroy`.
 

doc/developer-guide/api/functions/TSSslSession.en.rst

@@ -49,7 +49,7 @@ The functions also work with the :type:`TSSslSession` object which can be cast t
 These functions perform the appropriate locking on the session cache to avoid errors.
 
 The :func:`TSSslSessionGet` and :func:`TSSslSessionGetBuffer` functions retrieve the :type:`TSSslSession` object that is identified by the
-:type:`TSSslSessionID` object.  If there is no matching session object, :func:`TSSslSessionGet` returns NULL and :func:`TSSslSessionGetBuffer`
+:type:`TSSslSessionID` object.  If there is no matching session object, :func:`TSSslSessionGet` returns nullptr and :func:`TSSslSessionGetBuffer`
 returns 0.
 
 :func:`TSSslSessionGetBuffer` returns the session information serialized in a buffer that can be shared between processes.

doc/developer-guide/api/functions/TSUrlHostGet.en.rst

@@ -76,7 +76,7 @@ Return Values
 =============
 
 All APIs except :func:`TSUrlPortGet` and :func:`TSUrlRawPortGet` return a string, which is
-not guaranteed to be NULL terminated. You must therefore always use the :arg:`length` value
+not guaranteed to be null-terminated. You must therefore always use the :arg:`length` value
 to determine the actual length of the returned string.
 
 :func:`TSUrlPortGet` simply returns the port number as an integer, possibly

doc/developer-guide/api/functions/TSUrlHostSet.en.rst

@@ -55,7 +55,7 @@ information.
 and :func:`TSUrlHttpFragmentSet` each set the specified portion of the URL
 located at offset within the marshal buffer :arg:`bufp` to the string
 value. If :arg:`length` is :literal:`-1` then these functions assume that value
-is NULL-terminated. Otherwise, the length of the :arg:`string` value is taken
+is null-terminated. Otherwise, the length of the :arg:`string` value is taken
 to be the value of :arg:`length`. These functions copy the string to within
 :arg:`bufp`, so it can be subsequently modified or deleted.
 

doc/developer-guide/api/functions/TSUrlPercentEncode.en.rst

@@ -48,7 +48,7 @@ information.
 storing the new string in the :arg:`dst` buffer. The :arg:`length` parameter
 will be set to the new (encoded) string length, or :literal:`0` if the encoding
 failed.  :func:`TSStringPercentEncode` is similar but operates on a string. If
-the optional :arg:`map` parameter is provided (not :literal:`NULL`) , it should
+the optional :arg:`map` parameter is provided (not :literal:`nullptr`) , it should
 be a map of characters to encode.
 
 :func:`TSStringPercentDecode` perform percent-decoding of the string in the :arg:`str` buffer,

doc/developer-guide/api/functions/TSUrlStringGet.en.rst

@@ -49,7 +49,7 @@ information.
 the marshal buffer :arg:`bufp`.  (However :arg:`bufp` is actually superfluous and may be null.)
 :func:`TSUrlStringGet` stores the length of the allocated string in the parameter :arg:`length`.
 This is the same length that :func:`TSUrlLengthGet` returns. The returned string is allocated by a
-call to :func:`TSmalloc` and must be freed by a call to :func:`TSfree`. If length is :literal:`NULL`
+call to :func:`TSmalloc` and must be freed by a call to :func:`TSfree`. If length is :literal:`nullptr`
 then no attempt is made to de-reference it. The returned string is not guaranteed to have a null
 terminator - :arg:`length` must be used to correctly display the string.
 

doc/developer-guide/api/functions/TSUserArgs.en.rst

@@ -79,19 +79,19 @@ independently.
 
 To look up the owner of a reserved index use :func:`TSUserArgIndexNameLookup`, with the appropriate type.
 If :arg:`name` is found as an owner, the function returns :code:`TS_SUCCESS` and :arg:`arg_index` is
-updated with the index reserved under that name. If :arg:`description` is not :code:`NULL` then
+updated with the index reserved under that name. If :arg:`description` is not :code:`nullptr` then
 the character pointer to which it points will be updated to point at the description for that
 reserved index. This enables communication between plugins where plugin "A" reserves an index under
 a well known name and plugin "B" locates the index by looking it up under that name.
 
 The owner of a reserved index can be found with :func:`TSUserArgIndexLookup`. If
 :arg:`arg_index` is reserved then the function returns :code:`TS_SUCCESS` and the pointers referred
 to by :arg:`name` and :arg:`description` are updated. :arg:`name` must point at a valid character
-pointer but :arg:`description` can be :code:`NULL` in which case it is ignored.
+pointer but :arg:`description` can be :code:`nullptr` in which case it is ignored.
 
 Manipulating the array is simple. :func:`TSUserArgSet` sets the array slot at :arg:`arg_idx`, for the
 particular type based on the provide data pointer. The values can be retrieved with the value from
-:func:`TSUserArgGet`. Values that have not been set are :code:`NULL`. Note that both the setter and the getter are
+:func:`TSUserArgGet`. Values that have not been set are :code:`nullptr`. Note that both the setter and the getter are
 context sensitive, based on the type (or value) of the data pointer:
 
    ============== =======================================================================

doc/developer-guide/api/functions/TSUuidCreate.en.rst

@@ -92,7 +92,7 @@ Finally, :func:`TSClientRequestUuidGet` can be used to extract
 the client request uuid from a transaction. The output buffer must be of
 sufficient length, minimum of ``TS_CRUUID_STRING_LEN`` + 1 bytes. This
 produces the same string as the log tag %<cruuid> generates, and it will
-be NULL terminated.
+be null terminated.
 
 Return Values
 =============
@@ -102,7 +102,7 @@ the UUID object. Several of the functions returns a normal Traffic Server
 return status code, :type:`TSReturnCode`. You should verify the success of
 those APIs, of course.
 
-The :func:`TSUuidStringGet` function will return ``NULL`` if the :type:`TSUuid`
+The :func:`TSUuidStringGet` function will return ``nullptr`` if the :type:`TSUuid`
 object is not properly initialized. Likewise, :func:`TSUuidVersionGet` would
 then return ``TS_UUID_UNDEFINED``.
 

doc/developer-guide/api/functions/TSVConnFdCreate.en.rst

@@ -43,7 +43,7 @@ Return Values
 =============
 
 On success, the returned :type:`TSVConn` object owns the socket and the
-caller must not close it. If :func:`TSVConnFdCreate` fails, :literal:`NULL`
+caller must not close it. If :func:`TSVConnFdCreate` fails, :literal:`nullptr`
 is returned, the socket is unchanged and the caller must close it.
 
 Examples

doc/developer-guide/api/functions/TSfgets.en.rst

@@ -38,5 +38,5 @@ Reads a line from the file pointed to by :arg:`filep` into the buffer
 
 Lines are terminated by a line feed character, ' '.  The line placed
 in the buffer includes the line feed character and is terminated with
-a ``NULL``.  If the line is longer than length bytes then only the first
+a ``nullptr``.  If the line is longer than length bytes then only the first
 length-minus-1 bytes are placed in :arg:`buf`.

doc/developer-guide/api/functions/TSmalloc.en.rst

@@ -32,6 +32,7 @@ Synopsis
     #include <ts/ts.h>
 
 .. function:: void * TSmalloc(size_t size)
+.. cpp:function:: template <typename T> T * malloc(size_t count = 1)
 .. function:: void * TSrealloc(void * ptr , size_t size)
 .. function:: char * TSstrdup(const char * str)
 .. function:: char * TSstrndup(const char * str, size_t size)
@@ -48,7 +49,7 @@ For example, :func:`TSrealloc` behaves like the C library routine :code:`realloc
 There are two reasons to use the routines provided by Traffic Server. The
 first is portability. The Traffic Server API routines behave the same on
 all of Traffic Servers supported platforms. For example, :code:`realloc` does
-not accept an argument of ``NULL`` on some platforms. The second reason is
+not accept an argument of ``nullptr`` on some platforms. The second reason is
 that the Traffic Server routines actually track the memory allocations by
 file and line number. This tracking is very efficient, is always turned
 on, and is useful for tracking down memory leaks.
@@ -58,6 +59,12 @@ heap. Traffic Server uses :func:`TSmalloc` internally for memory allocations.
 Always use :func:`TSfree` to release memory allocated by :func:`TSmalloc`; do not use
 :code:`free`.
 
+**malloc()**, which is in the :code:`tsapi` namespace, returns a pointer, of type :code:`T *`,
+to allocated memory with enough bytes to hold an array of :code:`count` (default value
+of :code;`1`) instances of :code:`T`.  No constructor of :code:`T` is called for the
+array elements.  This function in turn calls :func:`TSmalloc`, so the memory it allocates
+should be released by calling :func:`TSfree`.
+
 :func:`TSstrdup` returns a pointer to a new string that is a duplicate of the
 string pointed to by str. The memory for the new string is allocated using
 :func:`TSmalloc` and should be freed by a call to :func:`TSfree`.
@@ -77,7 +84,11 @@ will append at most :arg:`size` - :code:`strlen(dst)` - 1 bytes, NUL-terminating
 result.
 
 :func:`TSfree` releases the memory allocated by :func:`TSmalloc` or :func:`TSrealloc`. If
-ptr is ``NULL``, :func:`TSfree` does no operation.
+ptr is ``nullptr``, :func:`TSfree` does no operation.
+
+Use of these functions should be avoided in new code.  For dynamic memory allocation,
+prefer in general to use C++ Standard Library containers and smart pointers.  Use of C++
+:code:`new` and :code:`delete` operators is the next best option.
 
 See also
 ========

doc/developer-guide/cache-architecture/data-structures.en.rst

@@ -112,7 +112,7 @@ Data Structures
 
    This class is a wrapper for :class:`HTTPCacheAlt`. It provides the
    external API for accessing data in the wrapped class. It contains only a
-   pointer (possibly ``NULL``) to an instance of the wrapped class.
+   pointer (possibly ``nullptr``) to an instance of the wrapped class.
 
 .. class:: CacheHTTPInfo
 

doc/developer-guide/config-vars.en.rst

@@ -43,9 +43,9 @@
 
 .. _overridable_txn_vars.cc: https://github.com/apache/trafficserver/blob/master/src/shared/overridable_txn_vars.cc
 
-.. |ts_lua_http_config.c| replace:: ``ts_lua_http_config.c``
+.. |ts_lua_http_config.cc| replace:: ``ts_lua_http_config.cc``
 
-.. _ts_lua_http_config.c: https://github.com/apache/trafficserver/blob/master/plugins/experimental/ts_lua/ts_lua_http_config.c
+.. _ts_lua_http_config.cc: https://github.com/apache/trafficserver/blob/master/plugins/experimental/ts_lua/ts_lua_http_config.cc
 
 .. |TSHttpOverridableConfig.en.rst| replace:: ``TSHttpOverridableConfig.en.rst``
 
@@ -153,7 +153,7 @@ check:``RecCheckT``
 pattern:``char const*``
    This provides a regular expressions (PCRE format) for validating the value,
    beyond the basic type validation performed by ``RecCheckT``. This can be
-   ``NULL`` if there is no regular expression to use.
+   ``nullptr`` if there is no regular expression to use.
 
 access:``RecAccessT``
    Access control. The valid values are:
@@ -320,7 +320,7 @@ required for generic access:
 #. Update the testing logic in |InkAPITest.cc|_ by adding the string name of the
    configuration variable to the ``SDK_Overridable_Configs`` array.
 
-#. Update the Lua plugin enumeration ``TSLuaOverridableConfigKey`` in |ts_lua_http_config.c|_.
+#. Update the Lua plugin enumeration ``TSLuaOverridableConfigKey`` in |ts_lua_http_config.cc|_.
 
 #. Update the documentation of :ref:`ts-overridable-config` in |TSHttpOverridableConfig.en.rst|_.