Utility Functions

• Dir

• Non-method functions

Dir

A directory object that iterates over its files and subdirectories (non-recursive)

• function	description
  Dir.open(pathname [,extension])	Creates a directory object; opens a directory, returning an iterator over the files/subdirectories within the directory
  dir:__call()	Gets the next file within the directory
  dir:close()	Closes the directory

Dir.open(pathname [,extension])

• Description

  • Creates a directory object; opens a directory, returning an iterator over the directory's files and subdirectories (non-recursive)

  Parameters

  • pathname : string

    • The pathname of the directory

    extension (optional) : string

    • If given, only file with this extension will be returned

  Returns

  • userdata : the directory object

  Example

  •    1 for filename in Dir.open('/path/to/dir') do 
       2   print(filename)
       3 end
    

dir:__call()

• Description

  • Gets the next file/subdirectory within the directory

  Returns

  • string : a filename of the next file/subdirectory within the directory; returns nil if all files iterated

  Example

  •    1 -- open a directory and print the name of the first file/subdir
       2 local dir = Dir.open('/path/to/dir')
       3 local first = dir()
       4 print( tostring(file) )
    

dir:close()

• Description

  • Closes the directory. Called automatically on garbage collection of dir.

Non Method Functions

• function	description
  get_version()	Gets the version of Wireshark
  format_date(timestamp)	Formats an absolute timestamp into a human-readable date
  format_time(timestamp)	Formats a relative timestamp into a human-readable form
  report_failure(text)	Reports a failure to the user, shown in a message box with an error icon
  critical(text)	Writes a log message with critical severity to the Lua console and stdout
  warn(text)	Writes a log message with warning severity to the Lua console and stdout
  message(text)	Writes a log message with normal severity to the Lua console and stdout
  info(text)	Writes a log message with informational severity to the Lua console and stdout
  debug(text)	Writes a log message with debug severity to the Lua console and stdout
  loadfile(filename)	Loads a Lua file and compiles it into a Lua chunk
  dofile(filename)	Opens the named file and executes its contents as a Lua chunk
  persconffile_path([filename])	Gets the personal configuration directory
  datafile_path([filename])	Gets the global configuration directory
  register_stat_cmd_arg(argument, action)	Registers a tshark statistics function, called with the -z option

get_version()

• Description

  • Gets the version of Wireshark

  Returns

  • string : the version number (e.g., "1.6.0")

format_date(timestamp)

• Description

  • Formats an absolute timestamp into a human-readable date

  Parameters

  • timestamp : string

    • A timestamp value to convert.

  Returns

  • string : The formatted date

format_time(timestamp)

• Description

  • Formats a relative timestamp into a human-readable form

  Parameters

  • timestamp : string

    • A timestamp value to convert

  Returns

  • string : The formatted time

report_failure(text)

• Description

  • Reports a failure to the user, shown in a message box with an error icon

  Parameters

  • text : string

    • the text to display in the message box

critical(text)

• Description

  • Writes a log message with critical severity to the Lua console and stdout

  Parameters

  • text : string

    • the text message to be logged

warn(text)

• Description

  • Writes a log message with warning severity to the Lua console and stdout

  Parameters

  • text : string

    • the text message to be logged

message(text)

• Description

  • Writes a log message with normal severity to the Lua console and stdout

  Parameters

  • text : string

    • the text message to be logged

info(text)

• Description

  • Writes a log message with informational severity to the Lua console and stdout

  Parameters

  • text : string

    • the text message to be logged

debug(text)

• Description

  • Writes a log message with debug severity to the Lua console and stdout

    See Bug 5976. This function hides Lua's debug table.

  Parameters

  • text : string

    • the text message to be logged

loadfile(filename)

• Description

  • Loads a Lua file and compiles it into a Lua chunk (similar to the standard loadfile but searches additional directories)

  Parameters

  • filename : string

    • Name of the file to be loaded. If the file does not exist in the current directory, the user and system directories are searched.

  Returns

  • function : The compiled chunk as a function; otherwise returns nil plus the error message.

  Errors

  • File not found or file contains invalid Lua

  Example

  •    1 local f = loadfile('/path/to/file')
       2  
       3 -- assume the file's Lua returns something
       4 local result = f()
       5 print (result)
    

dofile(filename)

• Description

  • Opens the named file and executes its contents as a Lua chunk (similar to the standard dofile but searches additional directories)

  Parameter

  • filename : string

    • Name of the file to be run. If the file does not exist in the current directory, the user and system directories are searched.

  Returns

  • all values returned by the Lua chunk

  Errors

  • File not found or file contains invalid Lua

persconffile_path([filename])

• Description

  • Gets the personal configuration directory

  Parameters

  • filename (optional) : string

    • A filename (or directory name) that is appended to the path with the appropriate path separator

  Returns

  • string : The full pathname for a file in the personal configuration directory

  Example

  •    1 local path = persconffile_path('plugins')
       2 
       3 -- on Mac OS X, prints: /Users/tony/.wireshark/plugins
       4 print(path)
    

datafile_path([filename])

• Description

  • Gets the global configuration directory

  Parameters

  • filename (optional)

    • A filename (or directory name) that is appended to the path with the appropriate path separator

  Returns

  • string : The full pathname for a file in Wireshark's global configuration directory

  Example

  •    1 local path = datafile_path('init.lua')
       2 
       3 -- on Mac OS X, prints: /Applications/Wireshark.app/Contents/Resources/share/wireshark/init.lua
       4 print(path)
    

register_stat_cmd_arg(argument, action)

• Description

  • Registers a tshark statistics function, called with the -z option

  Parameters

  • argument : string

    • name of option argument

    action : function

    • function to be called when the command is invoked