Engine and TA files management

Overview

Functions for convinient work with the files on the engine and TA. More…

// global functions

char* tapi_file_make_name(te_string* dest);
char* tapi_file_make_custom_pathname(te_string* dest, const char* dirname, const char* suffix);
char* tapi_file_make_pathname(te_string* dest);
char* tapi_file_join_pathname(te_string* dest, const char* dirname, const char* path, const char* suffix);
char* tapi_file_resolve_ta_pathname(te_string* dest, const char* ta, tapi_cfg_base_ta_dir base_dir, const char* relname);
char* tapi_file_generate_name(void);
char* tapi_file_generate_pathname(void);
char* tapi_file_create_pattern(size_t len, char c);
char* tapi_file_create(size_t len, char* buf, bool random);
te_errno tapi_file_create_ta(const char* ta, const char* filename, const char* fmt, ...);
te_errno te_errno tapi_file_create_ta_r(const char* ta, const char* lfile, const char* rfile, const char* fmt, ...);
te_errno te_errno te_errno tapi_file_read_ta(const char* ta, const char* filename, char** pbuf);
te_errno tapi_file_append_ta(const char* ta, const char* filename, const char* fmt, ...);
te_errno te_errno tapi_file_copy_ta(const char* ta_src, const char* src, const char* ta_dst, const char* dst);
te_errno tapi_file_expand_kvpairs(const char* ta, const char* template, const char* posargs[TE_EXPAND_MAX_POS_ARGS], const te_kvpair_h* kvpairs, const char* filename_fmt, ...);
te_errno tapi_file_ta_unlink_fmt(const char* ta, const char* path_fmt, ...);

Detailed Documentation

Functions for convinient work with the files on the engine and TA.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Global Functions

char* tapi_file_make_name(te_string* dest)

Generate a unique basename for a file.

If dest is NULL, a fresh string is allocated and returned.

The name is appended to the string contents. That way it is easier to construct derived pathnames and similar stuff.

Parameters:

dest	The string to hold the name or NULL.

Returns:

the pointer to the contents of dest or a heap-allocated buffer

char* tapi_file_make_custom_pathname(te_string* dest, const char* dirname, const char* suffix)

Generate a unique pathname for a file on the Engine side.

If dest is NULL, a fresh string is allocated and returned.

The name is appended to the string contents.

Parameters:

dest	The string to hold the name or NULL.
dirname	Directory component (may be NULL, in which case a relative name is generated)
suffix	A custom suffix to add to a generated pathname (may be NULL).

Returns:

the pointer to the contents of dest or a heap-allocated buffer

char* tapi_file_make_pathname(te_string* dest)

Generate a unique pathname for a file on the Engine side.

If dest is NULL, a fresh string is allocated and returned.

The name is appended to the string contents.

TE_TMP env variable must be set.

Parameters:

dest	The string to hold the name or NULL.

Returns:

the pointer to the contents of dest or a heap-allocated buffer

char* tapi_file_join_pathname(te_string* dest, const char* dirname, const char* path, const char* suffix)

Construct a pathname from parts.

If path is not NULL, uses te_file_join_filename() to construct a complete filename. Otherwise, it behaves like tapi_file_make_custom_pathname(), generating a unique filename under dirname.

If path is not NULL, it may be either a relative or an absolute pathname. In the latter case dirname is ignored.

If dest is NULL, a fresh string is allocated and returned.

The name is appended to the string contents.

Parameters:

dest	The string to hold the name or NULL.
dirname	Directory name (may be NULL)
path	Pathname (absolute, relative or NULL)
suffix	A suffix to append to a pathname (may be NULL).

Returns:

the pointer to the contents of dest or a heap-allocated buffer

char* tapi_file_resolve_ta_pathname(te_string* dest, const char* ta, tapi_cfg_base_ta_dir base_dir, const char* relname)

Resolve a pathname relative to one of the agent directories.

te_file_join_filename() is used for resolving, so pathname components need not exist and symlinks are not resolved.

If dest is NULL, a fresh string is allocated and returned.

The name is appended to the string contents.

Parameters:

dest	The string to hold the name or NULL.
ta	Agent name.
base_dir	Agent base directory.
relname	Relative filename.

Returns:

the pointer to the contents of dest or a heap-allocated buffer

See also:

tapi_cfg_base_get_ta_dir()

char* tapi_file_generate_name(void)

Generate unique basename for file.

Deprecated The function returns a pointer to a static buffer, so it is inherently unreliable. Use tapi_file_make_name() instead.

Returns:

generated name

char* tapi_file_generate_pathname(void)

Generate unique pathname for file on the engine.

Deprecated The function returns a pointer to a static buffer, so it is inherently unreliable. Use tapi_file_make_pathname() instead.

Returns:

generated name

char* tapi_file_create_pattern(size_t len, char c)

Create file in the TE temporary directory.

Parameters:

len	file length
c	file content pattern

Returns:

name (memory is allocated) of the file or NULL in the case of failure

char* tapi_file_create(size_t len, char* buf, bool random)

Create file in the TE temporary directory with the specified content.

Parameters:

len	file length
buf	buffer with the file content
random	if true, fill buffer with random data

Returns:

name (memory is allocated) of the file or NULL in the case of failure

te_errno tapi_file_create_ta(const char* ta, const char* filename, const char* fmt, ...)

Create file in the specified directory on the TA.

Parameters:

ta	Test Agent name
filename	pathname of the file
fmt	format string for the file content

Returns:

Status code

te_errno te_errno tapi_file_create_ta_r(const char* ta, const char* lfile, const char* rfile, const char* fmt, ...)

Create local file, copy it to TA, remove local file. The function does the same thing as tapi_file_create_ta(), but it creates local file with specified name instead of using automatically generated name.

Parameters:

ta	Test Agent name
lfile	pathname of the local file
rfile	pathname of the file on TA
fmt	format string for the file content

Returns:

Status code

te_errno te_errno te_errno tapi_file_read_ta(const char* ta, const char* filename, char** pbuf)

Read file content from the TA.

Parameters:

ta	Test Agent name
filename	pathname of the file
pbuf	location for buffer allocated by the routine

Returns:

Status code

te_errno tapi_file_append_ta(const char* ta, const char* filename, const char* fmt, ...)

Like tapi_file_create_ta(), but it appends data to the file.

If the file does not exist, it is created.

Parameters:

ta	Test Agent name
filename	pathname of the file
fmt	format string for the file content

Returns:

Status code

te_errno te_errno tapi_file_copy_ta(const char* ta_src, const char* src, const char* ta_dst, const char* dst)

Copy file from the one TA to other or between the Engine and an agent.

Todo Currently the function does not support copying files on the Engine locally, so both ta_src and ta_dst cannot be NULL at the same time.

Parameters:

ta_src	source Test Agent (NULL if the source is the Engine)
src	source file name
ta_dst	destination Test Agent (NULL if the source is the Engine)
dst	destination file name

Returns:

Status code

te_errno tapi_file_expand_kvpairs(const char* ta, const char* template, const char* posargs[TE_EXPAND_MAX_POS_ARGS], const te_kvpair_h* kvpairs, const char* filename_fmt, ...)

Generate a file by expanding references in template.

The expansion is done with te_string_expand_kvpairs() using posargs for positional argument references and kvpairs for named variable references.

If ta is not NULL, the file is copied to a given agent; otherwise it is created locally on the Engine host.

Parameters:

ta	Test Agent name (may be NULL, then Engine is assumed)
template	file content template
posargs	array of positional arguments (may be NULL)
kvpairs	kvpairs of named variables
filename_fmt	format string of a generated pathname
…	arguments

Returns:

status code

te_errno tapi_file_ta_unlink_fmt(const char* ta, const char* path_fmt, ...)

Unlink file on the TA.

Parameters:

ta	Test Agent name
path_fmt	Format string to make path to be deleted

Returns:

Status code.