output-file: rename and document registration function

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

Ticket: #7227

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: );

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));

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 */

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)) {

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,

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) {