output-file: rename and document registration function

Rename OutputRegisterFileLogger to SCOutputRegisterFileLogger, add
function documentation and include in userguide.

Ticket: #7227

diff --git a/doc/userguide/devguide/extending/output/index.rst b/doc/userguide/devguide/extending/output/index.rst
index e5b22192ef07e7abfa70b76f8cf91fe83ac60f00..de766a796809c2791b80bd209355a8dd33b6daa2 100644 (file)
--- a/doc/userguide/devguide/extending/output/index.rst
+++ b/doc/userguide/devguide/extending/output/index.rst
@@ -77,3 +77,14 @@ Stream loggers can be registered with the
    :language: c
    :start-at: /** \brief Register a streaming logger
    :end-at: );
+
+File Logging
+~~~~~~~~~~~~
+
+File loggers can be registered with the ``SCOutputRegisterFileLogger``
+function:
+
+.. literalinclude:: ../../../../../src/output-file.h
+   :language: c
+   :start-at: /** \brief Register a file logger
+   :end-at: );

diff --git a/src/output-file.c b/src/output-file.c
index 6d29298fea0b8ea32f9b3ef4de3433e78d3bbe58..e468f14d25c098ee64ab2b7d477884735a3943f9 100644 (file)
--- a/src/output-file.c
+++ b/src/output-file.c
@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2022 Open Information Security Foundation
+/* Copyright (C) 2007-2024 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -42,7 +42,7 @@ bool g_file_logger_enabled = false;
  * it's perfectly valid that have multiple instances of the same
  * log module (e.g. http.log) with different output ctx'. */
 typedef struct OutputFileLogger_ {
-    FileLogger LogFunc;
+    SCFileLogger LogFunc;
     void *initdata;
     struct OutputFileLogger_ *next;
     const char *name;
@@ -53,7 +53,7 @@ typedef struct OutputFileLogger_ {
 
 static OutputFileLogger *list = NULL;
 
-int OutputRegisterFileLogger(LoggerId id, const char *name, FileLogger LogFunc, void *initdata,
+int SCOutputRegisterFileLogger(LoggerId id, const char *name, SCFileLogger LogFunc, void *initdata,
         ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit)
 {
     OutputFileLogger *op = SCCalloc(1, sizeof(*op));

diff --git a/src/output-file.h b/src/output-file.h
index d859efc7c3a5a2ee99d97a8f7f5baff3955207fe..9ea66891a5875181191d7de1e0c5477de9e9e66a 100644 (file)
--- a/src/output-file.h
+++ b/src/output-file.h
@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2022 Open Information Security Foundation
+/* Copyright (C) 2007-2024 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -45,14 +45,35 @@ void OutputFileLogFfc(ThreadVars *tv, OutputFileLoggerThreadData *op_thread_data
         const bool file_close, const bool file_trunc, uint8_t dir);
 
 /** file logger function pointer type */
-typedef int (*FileLogger)(ThreadVars *, void *thread_data, const Packet *, const File *, void *tx,
+typedef int (*SCFileLogger)(ThreadVars *, void *thread_data, const Packet *, const File *, void *tx,
         const uint64_t tx_id, uint8_t direction);
 
-int OutputRegisterFileLogger(LoggerId id, const char *name, FileLogger LogFunc, void *initdata,
+/** \brief Register a file logger.
+ *
+ * \param logger_id An ID used to distinguish this logger from others
+ *     while profiling.
+ *
+ * \param name An informational name for this logger. Used only for
+ *     debugging.
+ *
+ * \param LogFunc A function that will be called to log each file to be logged.
+ *
+ * \param initdata Initialization data that will pass to the
+ *     ThreadInitFunc.
+ *
+ * \param ThreadInitFunc Thread initialization function.
+ *
+ * \param ThreadDeinitFunc Thread de-initialization function.
+ *
+ * \retval 0 on success, -1 on failure.
+ */
+int SCOutputRegisterFileLogger(LoggerId id, const char *name, SCFileLogger LogFunc, void *initdata,
         ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit);
 
+/** Internal function: private API. */
 void OutputFileLoggerRegister(void);
 
+/** Internal function: private API. */
 void OutputFileShutdown(void);
 
 #endif /* SURICATA_OUTPUT_FILE_H */

diff --git a/src/output.c b/src/output.c
index 46e7f808a830545d1768d4f6c94674868de6ae5b..9469bfada93a4215a2daa9d35cab60df19c8c5b5 100644 (file)
--- a/src/output.c
+++ b/src/output.c
@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2021 Open Information Security Foundation
+/* Copyright (C) 2007-2024 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -391,7 +391,7 @@ void OutputRegisterTxSubModule(LoggerId id, const char *parent_name, const char
  * \retval Returns 0 on success, -1 on failure.
  */
 void OutputRegisterFileSubModule(LoggerId id, const char *parent_name, const char *name,
-        const char *conf_name, OutputInitSubFunc InitFunc, FileLogger FileLogFunc,
+        const char *conf_name, OutputInitSubFunc InitFunc, SCFileLogger FileLogFunc,
         ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit)
 {
     if (unlikely(FileLogFunc == NULL)) {

diff --git a/src/output.h b/src/output.h
index abbd907a1e47f2ecf6ca92c79370e008bc0bb41e..f9e8a6f51d48920dd0ef9a98b11c645915a99dc6 100644 (file)
--- a/src/output.h
+++ b/src/output.h
@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2022 Open Information Security Foundation
+/* Copyright (C) 2007-2024 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -68,7 +68,7 @@ typedef struct OutputModule_ {
     PacketLogCondition PacketConditionFunc;
     TxLogger TxLogFunc;
     TxLoggerCondition TxLogCondition;
-    FileLogger FileLogFunc;
+    SCFileLogger FileLogFunc;
     FiledataLogger FiledataLogFunc;
     FlowLogger FlowLogFunc;
     SCStreamingLogger StreamingLogFunc;
@@ -116,7 +116,7 @@ void OutputRegisterTxSubModuleWithProgress(LoggerId id, const char *parent_name,
         ThreadDeinitFunc ThreadDeinit);
 
 void OutputRegisterFileSubModule(LoggerId id, const char *parent_name, const char *name,
-        const char *conf_name, OutputInitSubFunc InitFunc, FileLogger FileLogFunc,
+        const char *conf_name, OutputInitSubFunc InitFunc, SCFileLogger FileLogFunc,
         ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit);
 
 void OutputRegisterFiledataModule(LoggerId id, const char *name, const char *conf_name,

diff --git a/src/runmodes.c b/src/runmodes.c
index eb4cfa879e89b38a5ba02842c9915b095c3ccc54..e9fb64a153686745874e0f03d3d9e0e25bd8c1d7 100644 (file)
--- a/src/runmodes.c
+++ b/src/runmodes.c
@@ -635,7 +635,7 @@ static void SetupOutput(
         filedata_logger_count++;
     } else if (module->FileLogFunc) {
         SCLogDebug("%s is a file logger", module->name);
-        OutputRegisterFileLogger(module->logger_id, module->name, module->FileLogFunc, output_ctx,
+        SCOutputRegisterFileLogger(module->logger_id, module->name, module->FileLogFunc, output_ctx,
                 module->ThreadInit, module->ThreadDeinit);
         file_logger_count++;
     } else if (module->StreamingLogFunc) {