Update comments in `wiretap/file_access.c`

1 files changed, 128 insertions, 90 deletions

diff --git a/wiretap/file_access.c b/wiretap/file_access.c
index 795a1ba77e..827aa78f92 100644
--- a/wiretap/file_access.c
+++ b/wiretap/file_access.c
@@ -133,6 +133,9 @@ add_extensions(GSList *extensions, const gchar *extension,
  * *not* be placed here; if there's nothing to put in the last field
  * of the structure, don't put an entry here, not even one with an
  * empty string for the extensions list.
+ *
+ * All added file types, regardless of extension or lack thereof,
+ * must also be added open_info_base[] below.
  */
 static const struct file_extension_info file_type_extensions_base[] = {
 	{ "Wireshark/tcpdump/... - pcap", TRUE, "pcap;cap;dmp" },
@@ -244,10 +247,11 @@ add_extensions_for_file_extensions_type(int extension_type, GSList *extensions,
 }
 
 /* Return a list of file extensions that are used by the specified file
-   extension type.
-
-   All strings in the list are allocated with g_malloc() and must be freed
-   with g_free(). */
+ * extension type.
+ *
+ * All strings in the list are allocated with g_malloc() and must be freed
+ * with g_free().
+ */
 GSList *
 wtap_get_file_extension_type_extensions(guint extension_type)
 {
@@ -276,21 +280,22 @@ wtap_get_file_extension_type_extensions(guint extension_type)
 }
 
 /* Return a list of all extensions that are used by all capture file
-   types, including compressed extensions, e.g. not just "pcap" but
-   also "pcap.gz" if we can read gzipped files.
-
-   "Capture files" means "include file types that correspond to
-   collections of network packets, but not file types that
-   store data that just happens to be transported over protocols
-   such as HTTP but that aren't collections of network packets",
-   so that it could be used for "All Capture Files" without picking
-   up JPEG files or files such as that - those aren't capture files,
-   and we *do* have them listed in the long list of individual file
-   types, so omitting them from "All Capture Files" is the right
-   thing to do.
-
-   All strings in the list are allocated with g_malloc() and must be freed
-   with g_free(). */
+ * types, including compressed extensions, e.g. not just "pcap" but
+ * also "pcap.gz" if we can read gzipped files.
+ *
+ * "Capture files" means "include file types that correspond to
+ * collections of network packets, but not file types that
+ * store data that just happens to be transported over protocols
+ * such as HTTP but that aren't collections of network packets",
+ * so that it could be used for "All Capture Files" without picking
+ * up JPEG files or files such as that - those aren't capture files,
+ * and we *do* have them listed in the long list of individual file
+ * types, so omitting them from "All Capture Files" is the right
+ * thing to do.
+ *
+ * All strings in the list are allocated with g_malloc() and must be freed
+ * with g_free().
+ */
 GSList *
 wtap_get_all_capture_file_extensions_list(void)
 {
@@ -327,24 +332,26 @@ wtap_get_all_capture_file_extensions_list(void)
 }
 
 /*
- * The open_file_* routines should return:
+ * The open_file_* routines must return:
  *
- *	-1 on an I/O error;
+ *	WTAP_OPEN_ERROR on an I/O error;
  *
- *	1 if the file they're reading is one of the types it handles;
+ *	WTAP_OPEN_MINE if the file they're reading is one of the types
+ *	    it handles;
  *
- *	0 if the file they're reading isn't the type they're checking for.
+ *	WTAP_OPEN_NOT_MINE if the file they're reading isn't the type
+ *	    they're checking for.
  *
- * If the routine handles this type of file, it should set the "file_type"
+ * If the routine handles this type of file, it must set the "file_type"
  * field in the "struct wtap" to the type of the file.
  *
- * Note that the routine does not have to free the private data pointer on
+ * Note that the routine does *not* have to free the private data pointer on
  * error. The caller takes care of that by calling wtap_close on error.
  * (See https://gitlab.com/wireshark/wireshark/-/issues/8518)
  *
- * However, the caller does have to free the private data pointer when
- * returning 0, since the next file type will be called and will likely
- * just overwrite the pointer.
+ * However, the caller *does* have to free the private data pointer when
+ * returning WTAP_OPEN_NOT_MINE, since the next file type will be called
+ * and will likely just overwrite the pointer.
  *
  * The names are used in file open dialogs to select, for files that
  * don't have magic numbers and that could potentially be files of
@@ -549,7 +556,7 @@ wtap_register_open_info(struct open_info *oi, const gboolean first_routine)
 	set_heuristic_routine();
 }
 
-/* De-registers a file reader by removign it from the GArray based on its name.
+/* De-registers a file reader by removing it from the GArray based on its name.
  * This function must NOT be called during wtap_open_offline(), since it changes the array.
  * Note: this function will error if it doesn't find the given name; if you want to handle
  * that condition more gracefully, call wtap_has_open_info() first.
@@ -632,9 +639,10 @@ wtap_uses_lua_filehandler(const wtap* wth)
 #endif
 
 /* returns the 'type' number to use for wtap_open_offline based on the
-   passed-in name (the name in the open_info struct). It returns WTAP_TYPE_AUTO
-   on failure, which is the number 0. The 'type' number is the entry's index+1,
-   because that's what wtap_open_offline() expects it to be. */
+ * passed-in name (the name in the open_info struct). It returns WTAP_TYPE_AUTO
+ * on failure, which is the number 0. The 'type' number is the entry's index+1,
+ * because that's what wtap_open_offline() expects it to be.
+ */
 unsigned int
 open_info_name_to_type(const char *name)
 {
@@ -779,12 +787,13 @@ heuristic_uses_extension(unsigned int i, const char *extension)
 }
 
 /* Opens a file and prepares a wtap struct.
-   If "do_random" is TRUE, it opens the file twice; the second open
-   allows the application to do random-access I/O without moving
-   the seek offset for sequential I/O, which is used by Wireshark
-   so that it can do sequential I/O to a capture file that's being
-   written to as new packets arrive independently of random I/O done
-   to display protocol trees for packets when they're selected. */
+ * If "do_random" is TRUE, it opens the file twice; the second open
+ * allows the application to do random-access I/O without moving
+ * the seek offset for sequential I/O, which is used by Wireshark
+ * so that it can do sequential I/O to a capture file that's being
+ * written to as new packets arrive independently of random I/O done
+ * to display protocol trees for packets when they're selected.
+ */
 wtap *
 wtap_open_offline(const char *filename, unsigned int type, int *err, char **err_info,
 		  gboolean do_random)
@@ -976,12 +985,13 @@ wtap_open_offline(const char *filename, unsigned int type, int *err, char **err_
 	/* Try all file types that support magic numbers */
 	for (i = 0; i < heuristic_open_routine_idx; i++) {
 		/* Seek back to the beginning of the file; the open routine
-		   for the previous file type may have left the file
-		   position somewhere other than the beginning, and the
-		   open routine for this file type will probably want
-		   to start reading at the beginning.
-
-		   Initialize the data offset while we're at it. */
+		 * for the previous file type may have left the file
+		 * position somewhere other than the beginning, and the
+		 * open routine for this file type will probably want
+		 * to start reading at the beginning.
+		 *
+		 * Initialize the data offset while we're at it.
+		 */
 		if (file_seek(wth->fh, 0, SEEK_SET, err) == -1) {
 			/* Error - give up */
 			wtap_close(wth);
@@ -1569,7 +1579,7 @@ wtap_dump_can_write_format(int ft, const GArray *file_encaps,
 	return TRUE;
 }
 
-/**
+/*
  * Return TRUE if we can write a file with the given GArray of
  * encapsulation types and the given bitmask of comment types.
  */
@@ -1619,7 +1629,7 @@ compare_file_type_subtypes_by_description(gconstpointer a, gconstpointer b)
 	              wtap_file_type_subtype_description(file_type_subtype_b));
 }
 
-/**
+/*
  * Get a GArray of file type/subtype values for file types/subtypes
  * that can be used to save a file of a given type/subtype with a given
  * GArray of encapsulation types and the given bitmask of comment types.
@@ -1733,7 +1743,7 @@ wtap_get_savable_file_types_subtypes_for_file(int file_type_subtype,
 	return savable_file_types_subtypes;
 }
 
-/**
+/*
  * Get a GArray of all writable file type/subtype values.
  */
 GArray *
@@ -1797,7 +1807,9 @@ wtap_get_writable_file_types_subtypes(ft_sort_order sort_order)
 	return writable_file_types_subtypes;
 }
 
-/* String describing the file type/subtype. */
+/*
+ * String describing the file type/subtype.
+ */
 const char *
 wtap_file_type_subtype_description(int file_type_subtype)
 {
@@ -1808,7 +1820,9 @@ wtap_file_type_subtype_description(int file_type_subtype)
 		return file_type_subtype_table[file_type_subtype].description;
 }
 
-/* Name to use in, say, a command-line flag specifying the type/subtype. */
+/*
+ * Name to use in, say, a command-line flag specifying the type/subtype.
+ */
 const char *
 wtap_file_type_subtype_name(int file_type_subtype)
 {
@@ -1830,7 +1844,9 @@ wtap_register_compatibility_file_subtype_name(const char *old_name,
 	    g_strdup(new_name));
 }
 
-/* Translate a name to a capture file type/subtype. */
+/*
+ * Translate a name to a capture file type/subtype.
+ */
 int
 wtap_name_to_file_type_subtype(const char *name)
 {
@@ -1902,6 +1918,9 @@ wtap_pcapng_file_type_subtype(void)
 	return pcapng_file_type_subtype;
 }
 
+/*
+ * Determine if a file type/subtype can write a block of the given type.
+ */
 block_support_t
 wtap_file_type_subtype_supports_block(int file_type_subtype,
     wtap_block_type_t type)
@@ -1933,6 +1952,10 @@ wtap_file_type_subtype_supports_block(int file_type_subtype,
 	return BLOCK_NOT_SUPPORTED;
 }
 
+/*
+ * Determine if a file type/subtype, when writing a block of the given type,
+ * can support adding the given option to the block.
+ */
 option_support_t
 wtap_file_type_subtype_supports_option(int file_type_subtype,
     wtap_block_type_t type, guint option)
@@ -2053,13 +2076,14 @@ add_extensions_for_file_type_subtype(int file_type_subtype, GSList *extensions,
 }
 
 /* Return a list of file extensions that are used by the specified file type.
-
-   If include_compressed is TRUE, the list will include compressed
-   extensions, e.g. not just "pcap" but also "pcap.gz" if we can read
-   gzipped files.
-
-   All strings in the list are allocated with g_malloc() and must be freed
-   with g_free(). */
+ *
+ * If include_compressed is TRUE, the list will include compressed
+ * extensions, e.g. not just "pcap" but also "pcap.gz" if we can read
+ * gzipped files.
+ *
+ * All strings in the list are allocated with g_malloc() and must be freed
+ * with g_free().
+ */
 GSList *
 wtap_get_file_extensions_list(int file_type_subtype, gboolean include_compressed)
 {
@@ -2098,16 +2122,17 @@ wtap_get_file_extensions_list(int file_type_subtype, gboolean include_compressed
 }
 
 /* Return a list of all extensions that are used by all file types that
-   we can read, including compressed extensions, e.g. not just "pcap" but
-   also "pcap.gz" if we can read gzipped files.
-
-   "File type" means "include file types that correspond to collections
-   of network packets, as well as file types that store data that just
-   happens to be transported over protocols such as HTTP but that aren't
-   collections of network packets, and plain text files".
-
-   All strings in the list are allocated with g_malloc() and must be freed
-   with g_free(). */
+ * we can read, including compressed extensions, e.g. not just "pcap" but
+ * also "pcap.gz" if we can read gzipped files.
+ *
+ * "File type" means "include file types that correspond to collections
+ * of network packets, as well as file types that store data that just
+ * happens to be transported over protocols such as HTTP but that aren't
+ * collections of network packets, and plain text files".
+ *
+ * All strings in the list are allocated with g_malloc() and must be freed
+ * with g_free().
+ */
 GSList *
 wtap_get_all_file_extensions_list(void)
 {
@@ -2147,8 +2172,10 @@ wtap_free_extensions_list(GSList *extensions)
 	g_slist_free(extensions);
 }
 
-/* Return the default file extension to use with the specified file type;
-   that's just the extension, without any ".". */
+/*
+ * Return the default file extension to use with the specified file type;
+ * that's just the extension, without any ".".
+ */
 const char *
 wtap_default_file_extension(int file_type_subtype)
 {
@@ -2159,6 +2186,9 @@ wtap_default_file_extension(int file_type_subtype)
 		return file_type_subtype_table[file_type_subtype].default_file_extension;
 }
 
+/*
+ * Return whether we know how to write the specified file type.
+ */
 gboolean
 wtap_dump_can_open(int file_type_subtype)
 {
@@ -2170,6 +2200,10 @@ wtap_dump_can_open(int file_type_subtype)
 	return TRUE;
 }
 
+/*
+ * Return whether we know how to write a compressed file of the specified
+ * file type.
+ */
 #ifdef HAVE_ZLIB
 gboolean
 wtap_dump_can_compress(int file_type_subtype)
@@ -2215,7 +2249,8 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t
 	 * This will fail if file_type_subtype isn't a valid
 	 * file type/subtype value, so, if it doesn't fail,
 	 * we know file_type_subtype is within the bounds of
-	 * the table of file types/subtypes. */
+	 * the table of file types/subtypes.
+	 */
 	if (!wtap_dump_can_open(file_type_subtype)) {
 		/* Invalid type, or type we don't know how to write. */
 		*err = WTAP_ERR_UNWRITABLE_FILE_TYPE;
@@ -2223,7 +2258,8 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t
 	}
 
 	/* OK, we know how to write that file type/subtype; can we write
-	   the specified encapsulation type in that file type/subtype? */
+	 * the specified encapsulation type in that file type/subtype?
+	 */
 	*err = (*file_type_subtype_table[file_type_subtype].can_write_encap)(params->encap);
 	/* if the err said to check wslua's can_write_encap, try that */
 	if (*err == WTAP_ERR_CHECK_WSLUA
@@ -2239,16 +2275,17 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t
 	}
 
 	/* Check whether we can open a capture file with that file type
-	   and that encapsulation, and, if the compression type isn't
-	   "uncompressed", whether we can write a *compressed* file
-	   of that file type. */
-	/* If we're doing compression, can this file type/subtype be
+	 * and that encapsulation, and, if the compression type isn't
+	 * "uncompressed", whether we can write a *compressed* file
+	 * of that file type.
+	 * If we're doing compression, can this file type/subtype be
 	   written in compressed form?
-
-	   (The particular type doesn't matter - if the file can't
-	   be written 100% sequentially, we can't compress it,
-	   because we can't go back and overwrite something we've
-	   already written. */
+	 *
+	 * (The particular type doesn't matter - if the file can't
+	 * be written 100% sequentially, we can't compress it,
+	 * because we can't go back and overwrite something we've
+	 * already written.
+	 */
 	if (compression_type != WTAP_UNCOMPRESSED &&
 	    !wtap_dump_can_compress(file_type_subtype)) {
 		*err = WTAP_ERR_COMPRESSION_NOT_SUPPORTED;
@@ -2294,16 +2331,17 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t
 	} else if (params->encap != WTAP_ENCAP_NONE) {
 		int snaplen;
 
-		// Generate a fake IDB if we don't have one, unless the
-		// file encapsulation is none. (WTAP_ENCAP_NONE either
-		// means that there are no interfaces, or they will be
-		// provided later when reading the file in single-pass mode.)
-		//
-		// XXX File types should provide their own IDBs (possibly
-		// fake ones generated by wtap_add_generated_idb()), in
-		// order to support being used as inputs for mergecap where
-		// pcapng is the output. This doesn't work for files with
-		// WTAP_ENCAP_PER_PACKET.
+		/* Generate a fake IDB if we don't have one, unless the
+		 * file encapsulation is none. (WTAP_ENCAP_NONE either
+		 * means that there are no interfaces, or they will be
+		 * provided later when reading the file in single-pass mode.)
+		 *
+		 * XXX File types should provide their own IDBs (possibly
+		 * fake ones generated by wtap_add_generated_idb()), in
+		 * order to support being used as inputs for mergecap where
+		 * pcapng is the output. This doesn't work for files with
+		 * WTAP_ENCAP_PER_PACKET.
+		 */
 		descr = wtap_block_create(WTAP_BLOCK_IF_ID_AND_INFO);
 		descr_mand = (wtapng_if_descr_mandatory_t*)wtap_block_get_mandatory_data(descr);
 		descr_mand->wtap_encap = params->encap;