From b83c3e056e7d707780794f89ed45e12db21e6baa Mon Sep 17 00:00:00 2001 From: Salvador Fandino Date: Thu, 15 Oct 2015 17:36:03 +0200 Subject: [PATCH] libssh2_session_set_last_error: Add function MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Net::SSH2, the Perl wrapping module for libssh2 implements several features* on top of libssh2 that can fail and so need some mechanism to report the error condition to the user. Until now, besides the error state maintained internally by libssh2, another error state was maintained at the Perl level for every session object and then additional logic was used to merge both error states. That is a maintenance nighmare, and actually there is no way to do it correctly and consistently. In order to allow the high level language to add new features to the library but still rely in its error reporting features the new function libssh2_session_set_last_error (that just exposses _libssh2_error_flags) is introduced. *) For instance, connecting to a remote SSH service giving the hostname and port. Signed-off-by: Salvador Fandino Signed-off-by: Salvador Fandiño --- docs/CMakeLists.txt | 1 + docs/Makefile.am | 1 + docs/libssh2_session_last_errno.3 | 1 + docs/libssh2_session_last_error.3 | 1 + docs/libssh2_session_set_last_error.3 | 33 +++++++++++++++++++++++++++ include/libssh2.h | 3 +++ src/session.c | 19 ++++++++++++++- 7 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 docs/libssh2_session_set_last_error.3 diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index fd6fcf2c..3e9d165e 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -139,6 +139,7 @@ set(MAN_PAGES libssh2_session_init_ex.3 libssh2_session_last_errno.3 libssh2_session_last_error.3 + libssh2_session_set_last_error.3 libssh2_session_method_pref.3 libssh2_session_methods.3 libssh2_session_set_blocking.3 diff --git a/docs/Makefile.am b/docs/Makefile.am index fa8188f4..02c67e27 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -110,6 +110,7 @@ dist_man_MANS = \ libssh2_session_init_ex.3 \ libssh2_session_last_errno.3 \ libssh2_session_last_error.3 \ + libssh2_session_set_last_error.3 \ libssh2_session_method_pref.3 \ libssh2_session_methods.3 \ libssh2_session_set_blocking.3 \ diff --git a/docs/libssh2_session_last_errno.3 b/docs/libssh2_session_last_errno.3 index fb395ef1..f9172cbc 100644 --- a/docs/libssh2_session_last_errno.3 +++ b/docs/libssh2_session_last_errno.3 @@ -18,3 +18,4 @@ Numeric error code corresponding to the the Error Code constants. .SH SEE ALSO .BR libssh2_session_last_error(3) +.BR libssh2_session_set_last_error(3) diff --git a/docs/libssh2_session_last_error.3 b/docs/libssh2_session_last_error.3 index 91663a04..2a64dbb7 100644 --- a/docs/libssh2_session_last_error.3 +++ b/docs/libssh2_session_last_error.3 @@ -29,3 +29,4 @@ Numeric error code corresponding to the the Error Code constants. .SH SEE ALSO .BR libssh2_session_last_errno(3) +.BR libssh2_session_set_last_error(3) diff --git a/docs/libssh2_session_set_last_error.3 b/docs/libssh2_session_set_last_error.3 new file mode 100644 index 00000000..fca6d1df --- /dev/null +++ b/docs/libssh2_session_set_last_error.3 @@ -0,0 +1,33 @@ +.TH libssh2_session_set_last_error 3 "26 Oct 2015" "libssh2 1.6.1" "libssh2 manual" +.SH NAME +libssh2_session_set_last_error - sets the internal error state +.SH SYNOPSIS +#include + +int +libssh2_session_set_last_error(LIBSSH2_SESSION *session, int errcode, const char *errmsg) + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIerrcode\fP - One of the error codes as defined in the public +libssh2 header file. + +\fIerrmsg\fP - If not NULL, a copy of the given string is stored +inside the session object as the error message. + +This function is provided for high level language wrappers +(i.e. Python or Perl) and other libraries that may extend libssh2 with +additional features while still relying on its error reporting +mechanism. + +.SH RETURN VALUE +Numeric error code corresponding to the the Error Code constants. + +.SH AVAILABILITY +Added in 1.6.1 + +.SH SEE ALSO +.BR libssh2_session_last_error(3) +.BR libssh2_session_last_errno(3) diff --git a/include/libssh2.h b/include/libssh2.h index 8b4695a8..f3d976cb 100644 --- a/include/libssh2.h +++ b/include/libssh2.h @@ -567,6 +567,9 @@ LIBSSH2_API int libssh2_session_last_error(LIBSSH2_SESSION *session, char **errmsg, int *errmsg_len, int want_buf); LIBSSH2_API int libssh2_session_last_errno(LIBSSH2_SESSION *session); +LIBSSH2_API int libssh2_session_set_last_error(LIBSSH2_SESSION* session, + int errcode, + const char* errmsg); LIBSSH2_API int libssh2_session_block_directions(LIBSSH2_SESSION *session); LIBSSH2_API int libssh2_session_flag(LIBSSH2_SESSION *session, int flag, diff --git a/src/session.c b/src/session.c index cc77a7a7..06e61dd1 100644 --- a/src/session.c +++ b/src/session.c @@ -1290,7 +1290,24 @@ libssh2_session_last_errno(LIBSSH2_SESSION * session) return session->err_code; } -/* libssh2_session_flag +/* libssh2_session_set_last_error + * + * Sets the internal error code for the session. + * + * This function is available specifically to be used by high level + * language wrappers (i.e. Python or Perl) that may extend the library + * features while still relying on its error reporting mechanism. + */ +LIBSSH2_API int +libssh2_session_set_last_error(LIBSSH2_SESSION* session, + int errcode, + const char* errmsg) +{ + return _libssh2_error_flags(session, errcode, errmsg, + LIBSSH2_ERR_FLAG_DUP); +} + +/* Libssh2_session_flag * * Set/Get session flags *