libssh  0.6.3
Functions
The SSH helper functions.

Different helper functions used in the SSH Library. More...

Functions

char * ssh_basename (const char *path)
 basename - parse filename component. More...
 
int ssh_check_hostname_syntax (const char *hostname)
 Checks syntax of a domain name. More...
 
int ssh_check_username_syntax (const char *username)
 Checks syntax of a username. More...
 
char * ssh_dirname (const char *path)
 Parse directory component. More...
 
int ssh_getpass (const char *prompt, char *buf, size_t len, int echo, int verify)
 Get a password from the console. More...
 
int ssh_mkdir (const char *pathname, mode_t mode)
 Attempts to create a directory with the given pathname. More...
 
char * ssh_path_expand_tilde (const char *d)
 Expand a directory starting with a tilde '~'. More...
 
int ssh_timeout_update (struct ssh_timestamp *ts, int timeout)
 updates a timeout value so it reflects the remaining time More...
 
const char * ssh_version (int req_version)
 Check if libssh is the required version or get the version string. More...
 

Detailed Description

Different helper functions used in the SSH Library.

Function Documentation

char* ssh_basename ( const char *  path)

basename - parse filename component.

basename breaks a null-terminated pathname string into a filename component. ssh_basename() returns the component following the final '/'. Trailing '/' characters are not counted as part of the pathname.

Parameters
[in]pathThe path to parse.
Returns
The filename of path or NULL if we can't allocate memory. If path is a the string "/", basename returns the string "/". If path is NULL or an empty string, "." is returned.

Referenced by ssh_scp_push_directory(), and ssh_scp_push_file64().

int ssh_check_hostname_syntax ( const char *  hostname)

Checks syntax of a domain name.

The check is made based on the RFC1035 section 2.3.1 Allowed characters are: hyphen, period, digits (0-9) and letters (a-zA-Z)

The label should be no longer than 63 characters The label should start with a letter and end with a letter or number The label in this implementation can start with a number to allow virtual URLs to pass. Note that this will make IPv4 addresses to pass this check too.

Parameters
hostnameThe domain name to be checked, has to be null terminated
Returns
SSH_OK if the hostname passes syntax check SSH_ERROR otherwise or if hostname is NULL or empty string
int ssh_check_username_syntax ( const char *  username)

Checks syntax of a username.

This check disallows metacharacters in the username

Parameters
usernameThe username to be checked, has to be null terminated
Returns
SSH_OK if the username passes syntax check SSH_ERROR otherwise or if username is NULL or empty string

Referenced by ssh_options_set().

char* ssh_dirname ( const char *  path)

Parse directory component.

dirname breaks a null-terminated pathname string into a directory component. In the usual case, ssh_dirname() returns the string up to, but not including, the final '/'. Trailing '/' characters are not counted as part of the pathname. The caller must free the memory.

Parameters
[in]pathThe path to parse.
Returns
The dirname of path or NULL if we can't allocate memory. If path does not contain a slash, c_dirname() returns the string ".". If path is the string "/", it returns the string "/". If path is NULL or an empty string, "." is returned.

Referenced by ssh_write_knownhost().

int ssh_getpass ( const char *  prompt,
char *  buf,
size_t  len,
int  echo,
int  verify 
)

Get a password from the console.

You should make sure that the buffer is an empty string!

You can also use this function to ask for a username. Then you can fill the buffer with the username and it is shows to the users. If the users just presses enter the buffer will be untouched.

1 char username[128];
2 
3 snprintf(username, sizeof(username), "john");
4 
5 ssh_getpass("Username:", username, sizeof(username), 1, 0);

The prompt will look like this:

Username: [john]

If you press enter then john is used as the username, or you can type it in to change it.

Parameters
[in]promptThe prompt to show to ask for the password.
[out]bufThe buffer the password should be stored. It NEEDS to be empty or filled out.
[in]lenThe length of the buffer.
[in]echoShould we echo what you type.
[in]verifyShould we ask for the password twice.
Returns
0 on success, -1 on error.
int ssh_mkdir ( const char *  pathname,
mode_t  mode 
)

Attempts to create a directory with the given pathname.

This is the portable version of mkdir, mode is ignored on Windows systems.

Parameters
[in]pathnameThe path name to create the directory.
[in]modeThe permissions to use.
Returns
0 on success, < 0 on error with errno set.

Referenced by ssh_write_knownhost().

char* ssh_path_expand_tilde ( const char *  d)

Expand a directory starting with a tilde '~'.

Parameters
[in]dThe directory to expand.
Returns
The expanded directory, NULL on error.

Referenced by ssh_options_set().

int ssh_timeout_update ( struct ssh_timestamp *  ts,
int  timeout 
)

updates a timeout value so it reflects the remaining time

Parameters
[in]tspointer to an existing timestamp
[in]timeouttimeout in milliseconds. Negative values mean infinite timeout
Returns
remaining time in milliseconds, 0 if elapsed, -1 if never.

References SSH_LOG_WARNING.

Referenced by ssh_channel_select(), ssh_select(), and ssh_set_fd_except().

const char* ssh_version ( int  req_version)

Check if libssh is the required version or get the version string.

Parameters
[in]req_versionThe version required.
Returns
If the version of libssh is newer than the version required it will return a version string. NULL if the version is older.

Example:

1 if (ssh_version(SSH_VERSION_INT(0,2,1)) == NULL) {
2  fprintf(stderr, "libssh version is too old!\n");
3  exit(1);
4 }
5 
6 if (debug) {
7  printf("libssh %s\n", ssh_version(0));
8 }