B.1.1 Declaring file and directory structures ¶

In many file system operations we need a description of a file or directory, both to select its attributes and to report meaningful errors to the user of a script. The following API allows us to store such informations into a Bash symbolic array, so that we can use the resulting compound value as single parameter to function calls; See Arrays. In this documentation such arrays will be often referred to as “data structures”.

We can declare a file structure as follows:

mbfl_declare_assoc_array_varref(LOGFILE)

mbflutils_file_init_file_struct mbfl_datavar(LOGFILE) \
  '/var/log/software.log' 'root' 'root' '0640' 'log file for software'

another example:

function caller () {
  mbfl_declare_assoc_array_varref(LOGFILE)

  callee mbfl_datavar(LOGFILE)
  ...
}

function callee () {
  mbfl_mandatory_nameref_parameter(LOGFILE, 1, log file data structure)

  mbflutils_file_init_file_struct mbfl_datavar(LOGFILE) \
    '/var/log/software.log' 'root' 'root' '0640' 'log file for software'
}

Function: mbflutils_file_init_file_struct ARRYNAME PATHNAME DESCRIPTION ¶

Function: mbflutils_file_init_directory_struct ARRYNAME PATHNAME DESCRIPTION ¶

Function: mbflutils_file_init_file_struct ARRYNAME PATHNAME DESCRIPTION OWNER GROUP MODE ¶

Function: mbflutils_file_init_directory_struct ARRYNAME PATHNAME DESCRIPTION OWNER GROUP MODE ¶

Initialise a symbolic array variable as representing the file system pathname and attributes of a file or directory; such array variable is to be used later to install the file or directory, or change its attributes as specified.

The arguments are:

ARRYNAME

The name of the array variable, which should have been previously declared.

PATHNAME

Mandatory parameter. A string representing the file system pathname of the file or directory; it is stored in the symbolic array with key PATHNAME.

DESCRIPTION

Mandatory parameter. A string representing the description of the file or directory; it is stored in the symbolic array with key DESCRIPTION. This description is used in verbose and error messages by printing it with the Bash built–in printf(), using the format specification ‘%b’, so some backslash sequences are expanded; See Bash Builtin Commands.

OWNER

Optional parameter, defaults to the empty string. A string representing the owner of the file or directory; it is stored in the symbolic array with key OWNER.

GROUP

Optional parameter, defaults to the empty string. A string representing the group of the file or directory; it is stored in the symbolic array with key GROUP.

MODE

Optional parameter, defaults to the empty string. A string representing the octal or symbolic mode of the file or directory; it is stored in the symbolic array with key MODE.