/******************************************************************************
* Copyright (c) 2000-2019 Ericsson Telecom AB
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html
******************************************************************************/
///////////////////////////////////////////////////////////////////////////////
//
// File: TCCFileIO_Functions.ttcn
// Description: TCC Useful Functions: FileIO Functions
// Rev: R36B
// Prodnr: CNL 113 472
//
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
// Module: TCCFileIO_Functions
//
// Purpose:
// This module supports file I/O handling
//
// Module Parameters:
// -
//
// Module depends on:
// -
//
///////////////////////////////////////////////////////////////////////////////
module TCCFileIO_Functions {
/* Function: f_FIO_open_rdonly
A wrapper function for f_FIO_open. It opens the file with the given name
for reading only.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_rdonly (in charstring pl_name) return integer;
/* Function: f_FIO_open_append_wronly
A wrapper function for f_FIO_open. It opens the file with the given name
for writing only. If the file already exists it is opened in appending
mode.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_append_wronly (in charstring pl_name)
return integer;
/* Function: f_FIO_open_append_rdwr
A wrapper function for f_FIO_open. It opens the file with the given name
for reading and writing. If the file already exists it is opened in
appending mode.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_append_rdwr (in charstring pl_name)
return integer;
/* Function: f_FIO_open_trunc_wronly
A wrapper function for f_FIO_open. It opens the file with the given name
for writing only. If the file was not empty it is truncated.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_trunc_wronly (in charstring pl_name)
return integer;
/* Function: f_FIO_open_trunc_rdwr
A wrapper function for f_FIO_open. It opens the file with the given name
for reading and writing. If the file was not empty it is truncated.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_trunc_rdwr (in charstring pl_name)
return integer;
/* Function: f_FIO_open_append_wronly_excl
A wrapper function for f_FIO_open. It opens the file with the given name
for writing only in exclusive mode. If the file already exists it is
opened in appending mode.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_append_wronly_excl (in charstring pl_name)
return integer;
/* Function: f_FIO_open_append_rdwr_excl
A wrapper function for f_FIO_open. It opens the file with the given name
for reading and writing in exclusive mode. If the file already exists it
is opened in appending mode.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_append_rdwr_excl (in charstring pl_name)
return integer;
/* Function: f_FIO_open_trunc_wronly_excl
A wrapper function for f_FIO_open. It opens the file with the given name
for writing only in exclusive mode. If the file was not empty it is
truncated.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_trunc_wronly_excl (in charstring pl_name)
return integer;
/* Function: f_FIO_open_trunc_rdwr_excl
A wrapper function for f_FIO_open. It opens the file with the given name
for reading and writing in exclusive mode. If the file was not empty it is
truncated.
Parameters:
NAME - The name of the file.
Returns:
A valid file descriptor or -1 on error. */
external function f_FIO_open_trunc_rdwr_excl (in charstring pl_name)
return integer;
/* Function: f_FIO_close
Closes a file associated with the given file descriptor.
Parameters:
FD - The file descriptor to close.
Returns:
What the POSIX function close returns. */
external function f_FIO_close (in integer pl_fd) return integer;
/* Function: f_FIO_seek_home
Moves the file pointer to the beginning of the file.
Parameters:
FD - A file descriptor.
Returns:
What the POSIX function lseek returns. */
external function f_FIO_seek_home (in integer pl_fd) return integer;
/* Function: f_FIO_seek_end
Moves the file pointer to the end of the file.
Parameters:
FD - A file descriptor.
Returns:
What the POSIX function lseek returns. */
external function f_FIO_seek_end (in integer pl_fd) return integer;
/* Function: f_FIO_seek_forward
Moves the file pointer forward with a given number of bytes from the
current position.
Parameters:
FD - A file descriptor.
BYTES - The number of bytes.
Returns:
What the POSIX function lseek returns. */
external function f_FIO_seek_forward (in integer pl_fd,
in integer pl_bytes) return integer;
/* Function: f_FIO_seek_backward
Moves the file pointer backward with a given number of bytes from the
current position.
Parameters:
FD - A file descriptor.
BYTES - The number of bytes.
Returns:
What the POSIX function lseek returns. */
external function f_FIO_seek_backward (in integer pl_fd,
in integer pl_bytes) return integer;
/* Function: f_FIO_write_data
A wrapper function for f_FIO_write. It writes binary data.
Parameters:
FD - A file descriptor.
DATA - The data to write to the file.
Returns:
Number of bytes written or -1 on error. */
external function f_FIO_write_data (in integer pl_fd,
in octetstring pl_data) return integer;
/* Function: f_FIO_write_text
A wrapper function for f_FIO_write. It writes textual data.
Parameters:
FD - A file descriptor.
TEXT - The text to write to the file.
Returns:
Number of bytes written or -1 on error. */
external function f_FIO_write_text (in integer pl_fd,
in charstring pl_text) return integer;
/* Function: f_FIO_write_data_flush
A wrapper function for f_FIO_write. It writes binary data and calls
f_FIO_flush.
Parameters:
FD - A file descriptor.
DATA - The data to write to the file.
Returns:
Number of bytes written or -1 on error. */
external function f_FIO_write_data_flush (in integer pl_fd,
in octetstring pl_data) return integer;
/* Function: f_FIO_write_text_flush
A wrapper function for f_FIO_write. It writes textual data and calls
f_FIO_flush.
Parameters:
FD - A file descriptor.
TEXT - The text to write to the file.
Returns:
Number of bytes written or -1 on error. */
external function f_FIO_write_text_flush (in integer pl_fd,
in charstring pl_text) return integer;
/* Function: f_FIO_flush
Transfers ("flushes") all modified in-core data of the file referred to by
the file descriptor to the disk device.
Parameters:
FD - A file descriptor.
Returns:
What the POSIX function fsync returns. */
external function f_FIO_flush (in integer pl_fd) return integer;
/* Function: f_FIO_read_data
A wrapper function for f_FIO_read. It reads binary data.
Parameters:
FD - A file descriptor.
DATA - The buffer for storing the data.
BYTES - The number of bytes to read.
Returns:
Number of bytes read or -1 on error. */
external function f_FIO_read_data (in integer pl_fd, inout octetstring pl_data,
in integer pl_bytes) return integer;
/* Function: f_FIO_read_text
A wrapper function for f_FIO_read. It reads textual data.
Parameters:
FD - A file descriptor.
TEXT - The buffer for storing the text.
BYTES - The number of bytes to read.
Returns:
Number of bytes read or -1 on error. */
external function f_FIO_read_text (in integer pl_fd, inout charstring pl_text,
in integer pl_bytes) return integer;
/* Function: f_FIO_read_text_until
A wrapper function for f_FIO_read_until. It reads textual data.
Parameters:
FD - A file descriptor.
TEXT - The buffer for storing the text.
SEPARATOR - The separator pattern.
Returns:
Number of bytes read or -1 on error. */
external function f_FIO_read_text_until (in integer pl_fd,
inout charstring pl_text, in charstring pl_separator) return integer;
/* Function: f_FIO_read_data_until
A wrapper function for f_FIO_read_until. It reads binary data.
Parameters:
FD - A file descriptor.
TEXT - The buffer for storing the data.
SEPARATOR - The separator pattern.
Returns:
Number of bytes read or -1 on error. */
external function f_FIO_read_data_until (in integer pl_fd,
inout octetstring pl_data, in octetstring pl_separator) return integer;
/* Function: f_FIO_read_data_TLV
A wrapper function for f_FIO_read. It reads a full ASN.1 TLV
structure in binary data format.
Parameters:
FD - A file descriptor.
TEXT - The buffer for storing the data.
SEPARATOR - The separator pattern.
Returns:
Number of bytes read or -1 on error. */
external function f_FIO_read_data_TLV (in integer pl_fd,
inout octetstring pl_data) return integer;
/* Function: f_FIO_get_error_string
Returns the actual error message.
Returns:
The actual error message as a string. */
external function f_FIO_get_error_string () return charstring;
/* Function: f_FIO_get_error_code
Returns the actual error code.
Returns:
The actual error code. */
external function f_FIO_get_error_code () return integer;
/* Function: f_FIO_set_filedescriptor_previousline
Returns:
If there was no problem, then the return value will be 1.
*/
external function f_FIO_set_filedescriptor_previousline (in integer pl_fd) return integer;
/* Function: f_FIO_chdir
A wrapper function for f_FIO_chdir. It changes the current directory.
Parameters:
NAME - The name of the new directory.
Returns:
Boolean value for successful or unsuccessful directory change */
external function f_FIO_chdir (in charstring pl_name) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_mkdir
//
// Purpose:
// Create a new directory
//
// Parameters:
// p_dir_name - *in* *charstring* - name of the directory to create
//
// Return Value:
// boolean - indicate the successful or unsuccessful directory creation
//
// Errors:
// In the case of unsuccessful operation the cause of the error can be
// queried by the f_FIO_get_error_code, f_FIO_get_error_string functions
//
// Detailed description:
// The path to the directory must exist, so the existence of the path
// should be checked, and the missing directories should be created
// recursively.
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_mkdir (in charstring p_dir_name) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_remove
//
// Purpose:
// Removes folder or a directory
//
// Parameters:
// pl_file_name - *in* *charstring* - name of the folder/directory to remove
//
// Return Value:
// boolean - indicate the successful or unsuccessful target removal
//
// Errors:
// In the case of unsuccessful operation the cause of the error can be
// queried by the f_FIO_get_error_code, f_FIO_get_error_string functions
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_remove (in charstring pl_file_name) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_rmdir
//
// Purpose:
// Removes a directory
//
// Parameters:
// p_dir_name - *in* *charstring* - name of the directory to remove
//
// Return Value:
// boolean - indicate the successful or unsuccessful directory creation
//
// Errors:
// In the case of unsuccessful operation the cause of the error can be
// queried by the f_FIO_get_error_code, f_FIO_get_error_string functions
//
// Detailed description:
// The directories must be empty, so the child directories should be
// cleaned and deleted recursively.
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_rmdir (in charstring p_dir_name) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_fileOrDirExists
//
// Purpose:
// Checks the existence of files and directories.
//
// Parameters:
// p_name - *in* *charstring* - name of the file or directory to check
//
// Return Value:
// boolean - indicate the exictense of the file or diectory
//
// Errors:
// -
//
// Detailed description:
// -
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_fileOrDirExists (in charstring p_name) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_rename
//
// Purpose:
// Renames a file.
//
// Parameters:
// pl__old__name - *in* *charstring* - file/directory that needs to be renamed
// pl__new__name - *in* *charstring* - new name of the file/directory
//
// Return Value:
// boolean - indicate that the rename procedure was successful or not
//
// Errors:
// In the case of unsuccessful operation the cause of the error can be
// queried by the f_FIO_get_error_code, f_FIO_get_error_string functions
//
// Detailed description:
// Permissions needed to rename the file/directory.
// The file or directory, that would be renamed, should exist, otherwise it
// returns false. The rename procedure fails in case of the target path is
// not exist.
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_rename(in charstring p_old_name, in charstring p_new_name) return boolean;
type record FIO_permissions{
boolean set_uid optional, // Set user ID on execution.
boolean set_gid optional, // Set group ID on execution.
boolean sticky_bit optional, // Save text image after execution.
boolean owner_read optional, // Read by owner.
boolean owner_write optional, // Write by owner.
boolean owner_execute optional, // Execute by owner.
boolean group_read optional, // Read by group.
boolean group_write optional, // Write by group.
boolean group_execute optional, // Execute by group.
boolean other_read optional, // Read by others.
boolean other_write optional, // Write by others.
boolean other_execute optional // Execute by others.
}
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_stat
//
// Purpose:
// Query the permissions of the file or directory.
//
// Parameters:
// p_name - *in* *charstring* - name of the file or directory to check
// p_permissions - *out* *FIO_permissions* - the permissions of the object
//
// Return Value:
// boolean - indicate sucessfull execution
//
// Errors:
// -
//
// Detailed description:
// -
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_stat (in charstring p_name,
out FIO_permissions p_permissions) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_chmod
//
// Purpose:
// Change the permissions of the file or directory.
//
// Parameters:
// p_name - *in* *charstring* - name of the file or directory to check
// p_permissions - *in* *FIO_permissions* - the permissions of the object
//
// Return Value:
// boolean - indicate sucessfull execution
//
// Errors:
// -
//
// Detailed description:
// Change the permissions of the file or directory according to the
// p_permissions. If the value of the field is:
// - true: set the permission
// - false: clear the permission
// - omit: doesn't change the permission
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_chmod (in charstring p_name,
in FIO_permissions p_permissions) return boolean;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_fileSize
//
// Purpose:
// Query the size of the file.
//
// Parameters:
// p_name - *in* *charstring* - name of the file to check
//
// Return Value:
// integer - the size of the file in bytes, or -1 on error
//
// Errors:
// -
//
// Detailed description:
// -
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_fileSize (in charstring p_name) return integer;
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_fileList
//
// Purpose:
// Query the contents of a directory.
//
// Parameters:
// p_name - *in* *charstring* - name of the directory to check
// p_files - *inout* *FileList* - the contents of the directory
//
// Return Value:
// boolean - indicate sucessfull execution
//
// Errors:
// -
//
// Detailed description:
// -
//
///////////////////////////////////////////////////////////////////////////////
type record of charstring FileList;
external function f_FIO_fileList (in charstring p_name,
inout FileList p_files) return boolean;
type enumerated FIO_FileType {
BlockDevice,
CharacterDevice,
Directory,
FIFO_Pipe,
Symlink,
RegularFile,
Socket,
Unknown,
NotExists,
ErrorReadingFile
};
type record FIO_FileInfo {
FIO_FileType fileType, //The type of the file
integer nodeNumber optional, //inode number
integer mode optional, //protection
integer linkCount optional, //number of hard links
integer ownership optional, //user ID of owner
integer groupId optional, //group ID of owner
integer blockSize optional, //blocksize for file system I/O
integer fileSize optional, //total size, in bytes
integer blocksAllocated optional, //number of 512B blocks allocated
integer lastStatusChange, //time of last access
integer lastFileAccess, //time of last modification
integer lastFileModification //time of last status change
}
///////////////////////////////////////////////////////////////////////////////
// Function: f_FIO_getFileType
//
// Purpose:
// Returns the file type of the given file
//
// Parameters:
// p_name - *in* *charstring* - name of the file or directory to check
//
// Return Value:
// - FIO_FileInfo: Contains the file type, and information about it.
//
// Errors:
// - If the file is not found, FIO_FileInfo.fileType will be NotExists
// - If the file can not be accessed, FIO_FileInfo.fileType will be ErrorReadingFile
// - If the file type is unknown, FIO_FileInfo.fileType will be Unknown
//
// Detailed description:
// Returns information about a given file
//
///////////////////////////////////////////////////////////////////////////////
external function f_FIO_getFileInfo (in charstring p_name) return FIO_FileInfo;
}