Page 6 of 23
check_block
Replaces or prepends/appends a data block in a file
The block is composed of entire lines and is surrounded by special comment
lines when inserted in the target file. These comment lines identify the
data block and allow the function to be called several times on the same
target file with different data blocks. The block identifier is the
base name of the source path.
If the given block is not present in the target file, it is appended or
prepended, depending on the flag argument. If the block is already
present in the file (was inserted by a previous run of this function),
its content is compared with the new data, and replaced if different.
In this case, it is replaced at the exact location where the previous block
lied.
If the target file exists, it is saved before being overwritten.
If the target path directory does not exist, it is created.
Arguments
$1 | If this arg starts with the '-' char, the data is to be read from
stdin and the string after the '-' is the block identifier.
If it does not start with '-', it is the path to the source file
(containing the data to insert). |
$2 | Target path |
$3 | Optional. Target file mode.
Default=644 |
$4 | Optional. Flag. Set to 'prepend' to add data at the beginning of
the file. Default mode: Append.
Used only if data block is not already present in the file.
Can be set to '' (empty string) to mean 'default mode'. |
$5 | Optional. Comment character.
This argument, if set, must contain only one character.
This character will be used as first char when building
the 'identifier' lines surrounding the data block.
Default: '#'. |
Returns
Always 0
Displays
Info msg
check_copy
Copy a file or the content of function's standard input to a target file
The copy takes place only if the source and target files are different.
If the target file is already existing, it is saved before being overwritten.
If the target path directory does not exist, it is created.
Arguments
$1 | Source path. Special value: '-' means that data to copy is read from
stdin, allowing to produce dynamic content without a temp file. |
$2 | Target path |
$3 | Optional. File creation mode. Default=644 |
Returns
Always 0
Displays
Info msg
check_line
Checks if a given line is contained in a file
Takes a pattern and a string as arguments. The first line matching the
pattern is compared with the string. If they are different, the string
argument replaces the line in the file. If they are the same, the file
is left unchanged.
If the pattern is not found, the string arg is appended to the file.
If the file does not exist, it is created.
Arguments
$1 | File path |
$2 | Pattern to search |
$3 | Line string |
Returns
Always 0
Displays
Info msg
check_link
Creates or modifies a symbolic link
The target is saved before being modified.
If the target path directory does not exist, it is created.
Arguments
$1 | Link target |
$2 | Link path |
Returns
Always 0
Displays
Info msg
chmod
Change the mode of a set of files/dirs
Arguments
$1 | mode as accepted by chmod |
$2+ | List of paths |
Returns
chmod status code
Displays
Nothing
chown
Change the owner of a set of files/dirs
Arguments
$1 | owner[:group] |
$2+ | List of paths |
Returns
chown status code
Displays
Nothing
comment_out
Comment lines in a file
The lines containing the (grep) pattern given in argument will be commented
out by prefixing them with the comment string.
If the pattern is not contained in the file, the file is left unchanged.
Arguments
$1 | File path |
$2 | Pattern to search (grep regex syntax) |
$3 | Optional. Comment prefix string. Default='#' |
$4 | Number of lines to comment (''=all). Default: '' |
Returns
Always 0
Displays
Info msg
contains_block
Checks if a file contains a block inserted by check_block
Arguments
$1 | The block identifier or source path |
$2 | File path |
Returns
0 if the block is in the file, !=0 if not.
Displays
Nothing
create_dir
Creates a directory
If the given path argument corresponds to an already existing
file (any type except directory or symbolic link to a directory), the
program aborts with a fatal error. If you want to avoid
this (if you want to create the directory, even if something else is
already existing in this path), call delete first.
If the path given as arg contains a symbolic link pointing to an existing
directory, it is left as-is.
Arguments
$1 | Path |
$2 | Optional. Directory owner[:group]. Default: root |
$3 | Optional. Directory mode in a format accepted by chmod. Default: 755 |
Returns
Always 0
Displays
Info msg
delete
Recursively deletes a file or a directory
Returns without error if arg is a non-existent path
Arguments
Returns
Always 0
Displays
Info msg
file_checksum
Compute the checksum of a file
Computed checksum depends on the OS and software available. It is prefixed
with a string giving the format, followed by a ':' and the chacksum in
readable form.
Possible format strings, in preference order: SHA1, MD5, CKS, SUM.
Generate a fatal error if none of these mechanisms is found.
Arguments
Returns
0 if file exists, 1 if not
Displays
Checksum, nothing if file does not exist.
file_group
Return group of a file (numeric)
Arguments
Returns
0 if file exists, 1 if not
Displays
File group in numeric form (nothing if file does not exist)
file_is_link
Portable way to check if a file is a symbolic link
Note: Don't use 'test -h' (not portable)
Arguments
Returns
0 if file exists and is a symbolic link, 1 if not
Displays
Nothing
file_mode
Return mode of a file in octal
Arguments
Returns
0 if file exists, 1 if not
Displays
File mode (nothing if file does not exist)
file_mtime
Return last modification time of a file (Unix format)
Arguments
Returns
0 if file exists, 1 if not
Displays
File last modification time in Unix format (Seconds since Epoch),
nothing if file does not exist.
file_owner
Return owner of a file (numeric)
Arguments
Returns
0 if file exists, 1 if not
Displays
File owner in numeric form (nothing if file does not exist)
file_readlink
Get the link target of a symbolic link
Arguments
Returns
0 if file exists and is a symbolic link, 1 if not
Displays
Link target if file exists and is a symbolic link, nothing otherwise
file_realpath
Canonicalize a file path
The input path must correspond to an existing item (file or dir, any type)
Every directories leading to the source item must be readable by the current
user.
This function preserves the current directory.
Arguments
Returns
0 if canonical path could be determined, 1 if not
Displays
Canonical path, nothing if path does not exist or access denied
file_size
Return size of a file (in bytes)
Arguments
Returns
0 if file exists, 1 if not
Displays
File size (in bytes), nothing if file does not exist.
file_type
Get the type of a file
Arguments
Returns
0 if file exists, 1 if not
Displays
- Nothing if file does not exist,
- R: Regular file,
- L: Symbolic link,
- D: Directory,
- C: Character device
- B: Block device
- P: Named pipe (fifo)
find_executable
Find an executable file
Arguments
$1 | Executable name |
$2 | Optional. List of directories to search (separated by ':' chars).
If not set, use PATH |
Returns
0 if executable was found, 1 if not
Displays
Absolute path if found, nothing if not found
rename_to_old
Renames a file to '<dir>/old.<filename>
### This function is deprecated. Please use save instead.
Arguments
Returns
Always 0
Displays
Info msg
sort_file
Sort a file in-place
Arguments
$1 | Path |
$2-* | Optional. Sort options |
Returns
Sort return code
Displays
Info msg
uncomment
Uncomment lines in a file
The commented lines containing the (grep) pattern given in argument
will be uncommented by removing the comment string.
If the pattern is not contained in the file, the file is left unchanged.
Arguments
$1 | File path |
$2 | Pattern to search (grep regex syntax) |
$3 | Optional. Comment prefix string. Default='#' |
$4 | Number of lines to uncomment (''=all). Default: '' |
Returns
Always 0
Displays
Info msg