diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bdc9df78..b4876ee6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -553,8 +553,8 @@ jobs: make install cd .. # Verify install - diff -u <(find docs -name '*.3' -printf '%f\n' | grep -v template | sort) <(find "$HOME"/temp/share/man/man3 -name '*.3' -printf '%f\n' | sort) - diff -u <(find include -name '*.h' -printf '%f\n' | sort) <(find "$HOME"/temp/include -name '*.h' -printf '%f\n' | sort) + diff -u <(find libssh2-99.98.97/docs -name '*.3' -printf '%f\n' | sort) <(find "$HOME"/temp/share/man/man3 -name '*.3' -printf '%f\n' | sort) + diff -u <(find libssh2-99.98.97/include -name '*.h' -printf '%f\n' | sort) <(find "$HOME"/temp/include -name '*.h' -printf '%f\n' | sort) rm -rf libssh2-99.98.97 build_linux_cross_mingw64: diff --git a/CMakeLists.txt b/CMakeLists.txt index 808cbd5d..a8169eaf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -547,7 +547,18 @@ if(LINT) endif() endif() -add_subdirectory(docs) +option(LIBSSH2_BUILD_DOCS "Build man pages" ON) +set(_build_docs FALSE) +if(LIBSSH2_BUILD_DOCS) + find_package(Perl) + if(PERL_FOUND) + set(_build_docs TRUE) + add_subdirectory(docs) + else() + message(WARNING "Perl not found. Will not build manuals.") + endif() +endif() +add_feature_info("Docs" _build_docs "build docs") feature_summary(WHAT ALL) diff --git a/REUSE.toml b/REUSE.toml index df9e5238..aad68990 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -28,7 +28,6 @@ path = [ "docs/INSTALL_CMAKE.md", "docs/SECURITY.md", "docs/TODO", - "docs/template.3", "os400/README400", "tests/key_*", "tests/openssh_server/.gitattributes", diff --git a/configure.ac b/configure.ac index 21ae4413..12df5d45 100644 --- a/configure.ac +++ b/configure.ac @@ -92,7 +92,41 @@ esac dnl check for how to do large files AC_SYS_LARGEFILE -# Crypto backends +dnl Perl +AC_PATH_PROG(PERL, perl,, $PATH:/usr/local/bin/perl:/usr/bin/:/usr/local/bin) +AC_SUBST(PERL) +AM_CONDITIONAL(PERL, test -n "$PERL") + +dnl ********************************************************************** +dnl Check whether to build documentation +dnl ********************************************************************** + +AC_MSG_CHECKING([whether to build documentation]) +AC_ARG_ENABLE(docs, +AS_HELP_STRING([--enable-docs],[Enable documentation (default)]) +AS_HELP_STRING([--disable-docs],[Disable documentation]), +[ case "$enableval" in + no) + AC_MSG_RESULT(no) + BUILD_DOCS=0 + ;; + *) + AC_MSG_RESULT(yes) + BUILD_DOCS=1 + ;; + esac ], + AC_MSG_RESULT(yes) + BUILD_DOCS=1 +) +if test -z "$PERL" -a "x$BUILD_DOCS" != "x0"; then + AC_MSG_WARN([perl was not found. Will not build documentation.]) + BUILD_DOCS=0 +fi + +dnl set variable for use in automakefile(s) +AM_CONDITIONAL(BUILD_DOCS, test x"$BUILD_DOCS" = x1) + +dnl Crypto backends found_crypto=none found_crypto_str="" diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index e158c6c7..0f2afcae 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -1,46 +1,52 @@ -# Copyright (C) Alexander Lamaison # Copyright (C) Viktor Szakats -# -# Redistribution and use in source and binary forms, -# with or without modification, are permitted provided -# that the following conditions are met: -# -# Redistributions of source code must retain the above -# copyright notice, this list of conditions and the -# following disclaimer. -# -# Redistributions in binary form must reproduce the above -# copyright notice, this list of conditions and the following -# disclaimer in the documentation and/or other materials -# provided with the distribution. -# -# Neither the name of the copyright holder nor the names -# of any other contributors may be used to endorse or -# promote products derived from this software without -# specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND -# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, -# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES -# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR -# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, -# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY -# OF SUCH DAMAGE. -# # SPDX-License-Identifier: BSD-3-Clause -libssh2_transform_makefile_inc("Makefile.am" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.am.cmake") -# Get dist_man_MANS variable -include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.am.cmake") +# Get man_MANS variable +libssh2_transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") +include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") +# Generate man pages +function(libssh2_add_manual_pages _listname) + # Maximum number of files per command to stay within shell/OS limits + if(CMAKE_HOST_UNIX) + set(_files_per_batch 10000) + else() # e.g. Windows with cmd.exe and other obsolete/unidentified shells + set(_files_per_batch 200) + endif() + set(_file_count 0) + set(_rofffiles "") + set(_mdfiles "") + set(_eol "_EOL_") + foreach(_file IN LISTS ${_listname} _eol) + math(EXPR _file_count "${_file_count} + 1") + if(_file_count GREATER_EQUAL _files_per_batch OR _file STREQUAL "_EOL_") + add_custom_command(OUTPUT ${_rofffiles} + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/cd2nroff" -k -d "${CMAKE_CURRENT_BINARY_DIR}" ${_mdfiles} + DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/cd2nroff" ${_mdfiles} + VERBATIM + ) + set(_file_count 0) + set(_rofffiles "") + set(_mdfiles "") + endif() + + list(APPEND _rofffiles "${CMAKE_CURRENT_BINARY_DIR}/${_file}") + string(REPLACE ".3" ".md" _mdfile "${_file}") + list(APPEND _mdfiles "${_mdfile}") + endforeach() + unset(_rofffiles) + unset(_mdfiles) +endfunction() + +libssh2_add_manual_pages(man_MANS) +add_custom_target(libssh2-man ALL DEPENDS ${man_MANS}) if(NOT LIBSSH2_DISABLE_INSTALL) + set(_src "") + foreach(_file IN LISTS man_MANS) + list(APPEND _src "${CMAKE_CURRENT_BINARY_DIR}/${_file}") + endforeach() include(GNUInstallDirs) - install(FILES ${dist_man_MANS} DESTINATION "${CMAKE_INSTALL_MANDIR}/man3") + install(FILES ${_src} DESTINATION "${CMAKE_INSTALL_MANDIR}/man3") + unset(_src) endif() diff --git a/docs/Makefile.am b/docs/Makefile.am index a21eb3b6..b80fc84c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,193 +1,21 @@ # Copyright (C) The libssh2 project and its contributors. # SPDX-License-Identifier: BSD-3-Clause -EXTRA_DIST = template.3 AUTHORS BINDINGS.md HACKING.md HACKING-CRYPTO \ - INSTALL_AUTOTOOLS INSTALL_CMAKE.md SECURITY.md TODO CMakeLists.txt +AUTOMAKE_OPTIONS = foreign no-dependencies -dist_man_MANS = \ - libssh2_agent_connect.3 \ - libssh2_agent_disconnect.3 \ - libssh2_agent_free.3 \ - libssh2_agent_get_identity.3 \ - libssh2_agent_get_identity_path.3 \ - libssh2_agent_init.3 \ - libssh2_agent_list_identities.3 \ - libssh2_agent_set_identity_path.3 \ - libssh2_agent_sign.3 \ - libssh2_agent_userauth.3 \ - libssh2_banner_set.3 \ - libssh2_base64_decode.3 \ - libssh2_channel_close.3 \ - libssh2_channel_direct_streamlocal_ex.3 \ - libssh2_channel_direct_tcpip.3 \ - libssh2_channel_direct_tcpip_ex.3 \ - libssh2_channel_eof.3 \ - libssh2_channel_exec.3 \ - libssh2_channel_flush.3 \ - libssh2_channel_flush_ex.3 \ - libssh2_channel_flush_stderr.3 \ - libssh2_channel_forward_accept.3 \ - libssh2_channel_forward_cancel.3 \ - libssh2_channel_forward_listen.3 \ - libssh2_channel_forward_listen_ex.3 \ - libssh2_channel_free.3 \ - libssh2_channel_get_exit_signal.3 \ - libssh2_channel_get_exit_status.3 \ - libssh2_channel_handle_extended_data.3 \ - libssh2_channel_handle_extended_data2.3 \ - libssh2_channel_ignore_extended_data.3 \ - libssh2_channel_open_ex.3 \ - libssh2_channel_open_session.3 \ - libssh2_channel_process_startup.3 \ - libssh2_channel_read.3 \ - libssh2_channel_read_ex.3 \ - libssh2_channel_read_stderr.3 \ - libssh2_channel_receive_window_adjust.3 \ - libssh2_channel_receive_window_adjust2.3 \ - libssh2_channel_request_auth_agent.3 \ - libssh2_channel_request_pty.3 \ - libssh2_channel_request_pty_ex.3 \ - libssh2_channel_request_pty_size.3 \ - libssh2_channel_request_pty_size_ex.3 \ - libssh2_channel_send_eof.3 \ - libssh2_channel_set_blocking.3 \ - libssh2_channel_setenv.3 \ - libssh2_channel_setenv_ex.3 \ - libssh2_channel_shell.3 \ - libssh2_channel_signal_ex.3 \ - libssh2_channel_subsystem.3 \ - libssh2_channel_wait_closed.3 \ - libssh2_channel_wait_eof.3 \ - libssh2_channel_window_read.3 \ - libssh2_channel_window_read_ex.3 \ - libssh2_channel_window_write.3 \ - libssh2_channel_window_write_ex.3 \ - libssh2_channel_write.3 \ - libssh2_channel_write_ex.3 \ - libssh2_channel_write_stderr.3 \ - libssh2_channel_x11_req.3 \ - libssh2_channel_x11_req_ex.3 \ - libssh2_crypto_engine.3 \ - libssh2_exit.3 \ - libssh2_free.3 \ - libssh2_hostkey_hash.3 \ - libssh2_init.3 \ - libssh2_keepalive_config.3 \ - libssh2_keepalive_send.3 \ - libssh2_knownhost_add.3 \ - libssh2_knownhost_addc.3 \ - libssh2_knownhost_check.3 \ - libssh2_knownhost_checkp.3 \ - libssh2_knownhost_del.3 \ - libssh2_knownhost_free.3 \ - libssh2_knownhost_get.3 \ - libssh2_knownhost_init.3 \ - libssh2_knownhost_readfile.3 \ - libssh2_knownhost_readline.3 \ - libssh2_knownhost_writefile.3 \ - libssh2_knownhost_writeline.3 \ - libssh2_poll.3 \ - libssh2_poll_channel_read.3 \ - libssh2_publickey_add.3 \ - libssh2_publickey_add_ex.3 \ - libssh2_publickey_init.3 \ - libssh2_publickey_list_fetch.3 \ - libssh2_publickey_list_free.3 \ - libssh2_publickey_remove.3 \ - libssh2_publickey_remove_ex.3 \ - libssh2_publickey_shutdown.3 \ - libssh2_scp_recv.3 \ - libssh2_scp_recv2.3 \ - libssh2_scp_send.3 \ - libssh2_scp_send64.3 \ - libssh2_scp_send_ex.3 \ - libssh2_session_abstract.3 \ - libssh2_session_banner_get.3 \ - libssh2_session_banner_set.3 \ - libssh2_session_block_directions.3 \ - libssh2_session_callback_set.3 \ - libssh2_session_callback_set2.3 \ - libssh2_session_disconnect.3 \ - libssh2_session_disconnect_ex.3 \ - libssh2_session_flag.3 \ - libssh2_session_free.3 \ - libssh2_session_get_blocking.3 \ - libssh2_session_get_read_timeout.3 \ - libssh2_session_get_timeout.3 \ - libssh2_session_handshake.3 \ - libssh2_session_hostkey.3 \ - libssh2_session_init.3 \ - libssh2_session_init_ex.3 \ - libssh2_session_last_errno.3 \ - libssh2_session_last_error.3 \ - libssh2_session_method_pref.3 \ - libssh2_session_methods.3 \ - libssh2_session_set_blocking.3 \ - libssh2_session_set_last_error.3 \ - libssh2_session_set_read_timeout.3 \ - libssh2_session_set_timeout.3 \ - libssh2_session_startup.3 \ - libssh2_session_supported_algs.3 \ - libssh2_sftp_close.3 \ - libssh2_sftp_close_handle.3 \ - libssh2_sftp_closedir.3 \ - libssh2_sftp_fsetstat.3 \ - libssh2_sftp_fstat.3 \ - libssh2_sftp_fstat_ex.3 \ - libssh2_sftp_fstatvfs.3 \ - libssh2_sftp_fsync.3 \ - libssh2_sftp_get_channel.3 \ - libssh2_sftp_init.3 \ - libssh2_sftp_last_error.3 \ - libssh2_sftp_lstat.3 \ - libssh2_sftp_mkdir.3 \ - libssh2_sftp_mkdir_ex.3 \ - libssh2_sftp_open.3 \ - libssh2_sftp_open_ex.3 \ - libssh2_sftp_open_ex_r.3 \ - libssh2_sftp_open_r.3 \ - libssh2_sftp_opendir.3 \ - libssh2_sftp_posix_rename.3 \ - libssh2_sftp_posix_rename_ex.3 \ - libssh2_sftp_read.3 \ - libssh2_sftp_readdir.3 \ - libssh2_sftp_readdir_ex.3 \ - libssh2_sftp_readlink.3 \ - libssh2_sftp_realpath.3 \ - libssh2_sftp_rename.3 \ - libssh2_sftp_rename_ex.3 \ - libssh2_sftp_rewind.3 \ - libssh2_sftp_rmdir.3 \ - libssh2_sftp_rmdir_ex.3 \ - libssh2_sftp_seek.3 \ - libssh2_sftp_seek64.3 \ - libssh2_sftp_setstat.3 \ - libssh2_sftp_shutdown.3 \ - libssh2_sftp_stat.3 \ - libssh2_sftp_stat_ex.3 \ - libssh2_sftp_statvfs.3 \ - libssh2_sftp_symlink.3 \ - libssh2_sftp_symlink_ex.3 \ - libssh2_sftp_tell.3 \ - libssh2_sftp_tell64.3 \ - libssh2_sftp_unlink.3 \ - libssh2_sftp_unlink_ex.3 \ - libssh2_sftp_write.3 \ - libssh2_sign_sk.3 \ - libssh2_trace.3 \ - libssh2_trace_sethandler.3 \ - libssh2_userauth_authenticated.3 \ - libssh2_userauth_banner.3 \ - libssh2_userauth_hostbased_fromfile.3 \ - libssh2_userauth_hostbased_fromfile_ex.3 \ - libssh2_userauth_keyboard_interactive.3 \ - libssh2_userauth_keyboard_interactive_ex.3 \ - libssh2_userauth_list.3 \ - libssh2_userauth_password.3 \ - libssh2_userauth_password_ex.3 \ - libssh2_userauth_publickey.3 \ - libssh2_userauth_publickey_fromfile.3 \ - libssh2_userauth_publickey_fromfile_ex.3 \ - libssh2_userauth_publickey_frommemory.3 \ - libssh2_userauth_publickey_sk.3 \ - libssh2_version.3 +if BUILD_DOCS +# Get man_MANS variable +include Makefile.inc + +MANPAGES = $(man_MANS:.3=.md) +CLEANFILES = $(man_MANS) +SUFFIXES = .3 .md + +.md.3: + $(srcdir)/cd2nroff $< >$@ + +endif + +EXTRA_DIST = $(MANPAGES) template.md cd2nroff AUTHORS BINDINGS.md HACKING.md \ + HACKING-CRYPTO INSTALL_AUTOTOOLS INSTALL_CMAKE.md SECURITY.md TODO \ + CMakeLists.txt diff --git a/docs/Makefile.inc b/docs/Makefile.inc new file mode 100644 index 00000000..0b5a7f1c --- /dev/null +++ b/docs/Makefile.inc @@ -0,0 +1,192 @@ +# Copyright (C) The libssh2 project and its contributors. +# SPDX-License-Identifier: BSD-3-Clause + +# Shared between CMakeLists.txt and Makefile.am + +man_MANS = \ + libssh2_agent_connect.3 \ + libssh2_agent_disconnect.3 \ + libssh2_agent_free.3 \ + libssh2_agent_get_identity.3 \ + libssh2_agent_get_identity_path.3 \ + libssh2_agent_init.3 \ + libssh2_agent_list_identities.3 \ + libssh2_agent_set_identity_path.3 \ + libssh2_agent_sign.3 \ + libssh2_agent_userauth.3 \ + libssh2_banner_set.3 \ + libssh2_base64_decode.3 \ + libssh2_channel_close.3 \ + libssh2_channel_direct_streamlocal_ex.3 \ + libssh2_channel_direct_tcpip.3 \ + libssh2_channel_direct_tcpip_ex.3 \ + libssh2_channel_eof.3 \ + libssh2_channel_exec.3 \ + libssh2_channel_flush.3 \ + libssh2_channel_flush_ex.3 \ + libssh2_channel_flush_stderr.3 \ + libssh2_channel_forward_accept.3 \ + libssh2_channel_forward_cancel.3 \ + libssh2_channel_forward_listen.3 \ + libssh2_channel_forward_listen_ex.3 \ + libssh2_channel_free.3 \ + libssh2_channel_get_exit_signal.3 \ + libssh2_channel_get_exit_status.3 \ + libssh2_channel_handle_extended_data.3 \ + libssh2_channel_handle_extended_data2.3 \ + libssh2_channel_ignore_extended_data.3 \ + libssh2_channel_open_ex.3 \ + libssh2_channel_open_session.3 \ + libssh2_channel_process_startup.3 \ + libssh2_channel_read.3 \ + libssh2_channel_read_ex.3 \ + libssh2_channel_read_stderr.3 \ + libssh2_channel_receive_window_adjust.3 \ + libssh2_channel_receive_window_adjust2.3 \ + libssh2_channel_request_auth_agent.3 \ + libssh2_channel_request_pty.3 \ + libssh2_channel_request_pty_ex.3 \ + libssh2_channel_request_pty_size.3 \ + libssh2_channel_request_pty_size_ex.3 \ + libssh2_channel_send_eof.3 \ + libssh2_channel_set_blocking.3 \ + libssh2_channel_setenv.3 \ + libssh2_channel_setenv_ex.3 \ + libssh2_channel_shell.3 \ + libssh2_channel_signal_ex.3 \ + libssh2_channel_subsystem.3 \ + libssh2_channel_wait_closed.3 \ + libssh2_channel_wait_eof.3 \ + libssh2_channel_window_read.3 \ + libssh2_channel_window_read_ex.3 \ + libssh2_channel_window_write.3 \ + libssh2_channel_window_write_ex.3 \ + libssh2_channel_write.3 \ + libssh2_channel_write_ex.3 \ + libssh2_channel_write_stderr.3 \ + libssh2_channel_x11_req.3 \ + libssh2_channel_x11_req_ex.3 \ + libssh2_crypto_engine.3 \ + libssh2_exit.3 \ + libssh2_free.3 \ + libssh2_hostkey_hash.3 \ + libssh2_init.3 \ + libssh2_keepalive_config.3 \ + libssh2_keepalive_send.3 \ + libssh2_knownhost_add.3 \ + libssh2_knownhost_addc.3 \ + libssh2_knownhost_check.3 \ + libssh2_knownhost_checkp.3 \ + libssh2_knownhost_del.3 \ + libssh2_knownhost_free.3 \ + libssh2_knownhost_get.3 \ + libssh2_knownhost_init.3 \ + libssh2_knownhost_readfile.3 \ + libssh2_knownhost_readline.3 \ + libssh2_knownhost_writefile.3 \ + libssh2_knownhost_writeline.3 \ + libssh2_poll.3 \ + libssh2_poll_channel_read.3 \ + libssh2_publickey_add.3 \ + libssh2_publickey_add_ex.3 \ + libssh2_publickey_init.3 \ + libssh2_publickey_list_fetch.3 \ + libssh2_publickey_list_free.3 \ + libssh2_publickey_remove.3 \ + libssh2_publickey_remove_ex.3 \ + libssh2_publickey_shutdown.3 \ + libssh2_scp_recv.3 \ + libssh2_scp_recv2.3 \ + libssh2_scp_send.3 \ + libssh2_scp_send64.3 \ + libssh2_scp_send_ex.3 \ + libssh2_session_abstract.3 \ + libssh2_session_banner_get.3 \ + libssh2_session_banner_set.3 \ + libssh2_session_block_directions.3 \ + libssh2_session_callback_set.3 \ + libssh2_session_callback_set2.3 \ + libssh2_session_disconnect.3 \ + libssh2_session_disconnect_ex.3 \ + libssh2_session_flag.3 \ + libssh2_session_free.3 \ + libssh2_session_get_blocking.3 \ + libssh2_session_get_read_timeout.3 \ + libssh2_session_get_timeout.3 \ + libssh2_session_handshake.3 \ + libssh2_session_hostkey.3 \ + libssh2_session_init.3 \ + libssh2_session_init_ex.3 \ + libssh2_session_last_errno.3 \ + libssh2_session_last_error.3 \ + libssh2_session_method_pref.3 \ + libssh2_session_methods.3 \ + libssh2_session_set_blocking.3 \ + libssh2_session_set_last_error.3 \ + libssh2_session_set_read_timeout.3 \ + libssh2_session_set_timeout.3 \ + libssh2_session_startup.3 \ + libssh2_session_supported_algs.3 \ + libssh2_sftp_close.3 \ + libssh2_sftp_close_handle.3 \ + libssh2_sftp_closedir.3 \ + libssh2_sftp_fsetstat.3 \ + libssh2_sftp_fstat.3 \ + libssh2_sftp_fstat_ex.3 \ + libssh2_sftp_fstatvfs.3 \ + libssh2_sftp_fsync.3 \ + libssh2_sftp_get_channel.3 \ + libssh2_sftp_init.3 \ + libssh2_sftp_last_error.3 \ + libssh2_sftp_lstat.3 \ + libssh2_sftp_mkdir.3 \ + libssh2_sftp_mkdir_ex.3 \ + libssh2_sftp_open.3 \ + libssh2_sftp_open_ex.3 \ + libssh2_sftp_open_ex_r.3 \ + libssh2_sftp_open_r.3 \ + libssh2_sftp_opendir.3 \ + libssh2_sftp_posix_rename.3 \ + libssh2_sftp_posix_rename_ex.3 \ + libssh2_sftp_read.3 \ + libssh2_sftp_readdir.3 \ + libssh2_sftp_readdir_ex.3 \ + libssh2_sftp_readlink.3 \ + libssh2_sftp_realpath.3 \ + libssh2_sftp_rename.3 \ + libssh2_sftp_rename_ex.3 \ + libssh2_sftp_rewind.3 \ + libssh2_sftp_rmdir.3 \ + libssh2_sftp_rmdir_ex.3 \ + libssh2_sftp_seek.3 \ + libssh2_sftp_seek64.3 \ + libssh2_sftp_setstat.3 \ + libssh2_sftp_shutdown.3 \ + libssh2_sftp_stat.3 \ + libssh2_sftp_stat_ex.3 \ + libssh2_sftp_statvfs.3 \ + libssh2_sftp_symlink.3 \ + libssh2_sftp_symlink_ex.3 \ + libssh2_sftp_tell.3 \ + libssh2_sftp_tell64.3 \ + libssh2_sftp_unlink.3 \ + libssh2_sftp_unlink_ex.3 \ + libssh2_sftp_write.3 \ + libssh2_sign_sk.3 \ + libssh2_trace.3 \ + libssh2_trace_sethandler.3 \ + libssh2_userauth_authenticated.3 \ + libssh2_userauth_banner.3 \ + libssh2_userauth_hostbased_fromfile.3 \ + libssh2_userauth_hostbased_fromfile_ex.3 \ + libssh2_userauth_keyboard_interactive.3 \ + libssh2_userauth_keyboard_interactive_ex.3 \ + libssh2_userauth_list.3 \ + libssh2_userauth_password.3 \ + libssh2_userauth_password_ex.3 \ + libssh2_userauth_publickey.3 \ + libssh2_userauth_publickey_fromfile.3 \ + libssh2_userauth_publickey_fromfile_ex.3 \ + libssh2_userauth_publickey_frommemory.3 \ + libssh2_userauth_publickey_sk.3 \ + libssh2_version.3 diff --git a/docs/cd2nroff b/docs/cd2nroff new file mode 100755 index 00000000..c3283a06 --- /dev/null +++ b/docs/cd2nroff @@ -0,0 +1,525 @@ +#!/usr/bin/env perl +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) Daniel Stenberg, , et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at https://curl.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +# SPDX-License-Identifier: curl +# +########################################################################### + +=begin comment + +Converts a curldown file to nroff (manpage). + +=end comment +=cut + +use strict; +use warnings; + +my $cd2nroff = "0.1"; # to keep check +my $dir; +my $extension; +my $keepfilename; + +while(@ARGV) { + if($ARGV[0] eq "-d") { + shift @ARGV; + $dir = shift @ARGV; + } + elsif($ARGV[0] eq "-e") { + shift @ARGV; + $extension = shift @ARGV; + } + elsif($ARGV[0] eq "-k") { + shift @ARGV; + $keepfilename = 1; + } + elsif($ARGV[0] eq "-h") { + print < Write the output to the file name from the meta-data in the + specified directory, instead of writing to stdout +-e If -d is used, this option can provide an added "extension", arbitrary + text really, to append to the file name. +-h This help text, +-v Show version then exit +HELP + ; + exit 0; + } + elsif($ARGV[0] eq "-v") { + print "cd2nroff version $cd2nroff\n"; + exit 0; + } + else { + last; + } +} + +use POSIX qw(strftime); +my @ts; +if(defined($ENV{SOURCE_DATE_EPOCH})) { + @ts = gmtime($ENV{SOURCE_DATE_EPOCH}); +} else { + @ts = localtime; +} +my $date = strftime "%Y-%m-%d", @ts; + +sub outseealso { + my (@sa) = @_; + my $comma = 0; + my @o; + push @o, ".SH SEE ALSO\n"; + for my $s (sort @sa) { + push @o, sprintf "%s.BR $s", $comma ? ",\n": ""; + $comma = 1; + } + push @o, "\n"; + return @o; +} + +sub outprotocols { + my (@p) = @_; + my $comma = 0; + my @o; + push @o, ".SH PROTOCOLS\n"; + + if($p[0] eq "TLS") { + push @o, "This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc."; + } + else { + my @s = sort @p; + push @o, "This functionality affects "; + for my $e (sort @s) { + push @o, sprintf "%s%s", + $comma ? (($e eq $s[-1]) ? " and " : ", "): "", + lc($e); + $comma = 1; + } + if($#s == 0) { + if($s[0] eq "All") { + push @o, " supported protocols"; + } + else { + push @o, " only"; + } + } + } + push @o, "\n"; + return @o; +} + +sub outtls { + my (@t) = @_; + my $comma = 0; + my @o; + if($t[0] eq "All") { + push @o, "\nAll TLS backends support this option."; + } + elsif($t[0] eq "none") { + push @o, "\nNo TLS backend supports this option."; + } + else { + push @o, "\nThis option works only with the following TLS backends:\n"; + my @s = sort @t; + for my $e (@s) { + push @o, sprintf "%s$e", + $comma ? (($e eq $s[-1]) ? " and " : ", "): ""; + $comma = 1; + } + } + push @o, "\n"; + return @o; +} + +my %knownprotos = ( + 'DICT' => 1, + 'FILE' => 1, + 'FTP' => 1, + 'FTPS' => 1, + 'GOPHER' => 1, + 'GOPHERS' => 1, + 'HTTP' => 1, + 'HTTPS' => 1, + 'IMAP' => 1, + 'IMAPS' => 1, + 'LDAP' => 1, + 'LDAPS' => 1, + 'MQTT' => 1, + 'POP3' => 1, + 'POP3S' => 1, + 'RTMP' => 1, + 'RTMPS' => 1, + 'RTSP' => 1, + 'SCP' => 1, + 'SFTP' => 1, + 'SMB' => 1, + 'SMBS' => 1, + 'SMTP' => 1, + 'SMTPS' => 1, + 'TELNET' => 1, + 'TFTP' => 1, + 'WS' => 1, + 'WSS' => 1, + 'TLS' => 1, + 'TCP' => 1, + 'QUIC' => 1, + 'All' => 1 + ); + +my %knowntls = ( + 'GnuTLS' => 1, + 'mbedTLS' => 1, + 'OpenSSL' => 1, + 'rustls' => 1, + 'Schannel' => 1, + 'wolfSSL' => 1, + 'All' => 1, + 'none' => 1, + ); + +sub single { + my @seealso; + my @proto; + my @tls; + my $d; + my ($f)=@_; + my $copyright; + my $errors = 0; + my $fh; + my $line; + my $list; + my $tlslist; + my $section; + my $source; + my $addedin; + my $spdx; + my $start = 0; + my $title; + + if(defined($f)) { + if(!open($fh, "<:crlf", "$f")) { + print STDERR "cd2nroff failed to open '$f' for reading: $!\n"; + return 1; + } + } + else { + $f = "STDIN"; + $fh = \*STDIN; + binmode($fh, ":crlf"); + } + while(<$fh>) { + $line++; + if(!$start) { + if(/^---/) { + # header starts here + $start = 1; + } + next; + } + if(/^Title: *(.*)/i) { + $title=$1; + } + elsif(/^Section: *(.*)/i) { + $section=$1; + } + elsif(/^Source: *(.*)/i) { + $source=$1; + } + elsif(/^See-also: +(.*)/i) { + $list = 1; # 1 for see-also + push @seealso, $1; + } + elsif(/^See-also: */i) { + if($seealso[0]) { + print STDERR "$f:$line:1:ERROR: bad See-Also, needs list\n"; + return 2; + } + $list = 1; # 1 for see-also + } + elsif(/^Protocol:/i) { + $list = 2; # 2 for protocol + } + elsif(/^TLS-backend:/i) { + $list = 3; # 3 for TLS backend + } + elsif(/^Added-in: *(.*)/i) { + $addedin=$1; + if(($addedin !~ /^[0-9.]+[0-9]\z/) && + ($addedin ne "n/a")) { + print STDERR "$f:$line:1:ERROR: invalid version number in Added-in line: $addedin\n"; + return 2; + } + } + elsif(/^ +- (.*)/i) { + # the only lists we support are see-also and protocol + if($list == 1) { + push @seealso, $1; + } + elsif($list == 2) { + push @proto, $1; + } + elsif($list == 3) { + push @tls, $1; + } + else { + print STDERR "$f:$line:1:ERROR: list item without owner?\n"; + return 2; + } + } + # REUSE-IgnoreStart + elsif(/^C: (.*)/i) { + $copyright=$1; + } + elsif(/^SPDX-License-Identifier: (.*)/i) { + $spdx=$1; + } + # REUSE-IgnoreEnd + elsif(/^---/) { + # end of the header section + if(!$title) { + print STDERR "$f:$line:1:ERROR: no 'Title:' in $f\n"; + return 1; + } + if(!$section) { + print STDERR "$f:$line:1:ERROR: no 'Section:' in $f\n"; + return 2; + } + if(!$source) { + print STDERR "$f:$line:1:ERROR: no 'Source:' in $f\n"; + return 2; + } + if(($source eq "libcurl") && !$addedin) { + print STDERR "$f:$line:1:ERROR: no 'Added-in:' in $f\n"; + return 2; + } + if(!$copyright) { + print STDERR "$f:$line:1:ERROR: no 'C:' field present\n"; + return 2; + } + if(!$spdx) { + # REUSE-IgnoreStart + print STDERR "$f:$line:1:ERROR: no 'SPDX-License-Identifier:' field present\n"; + # REUSE-IgnoreEnd + return 2; + } + last; + } + else { + chomp; + print STDERR "$f:$line:1:ERROR: unrecognized header keyword: '$_'\n"; + $errors++; + } + } + + if(!$start) { + print STDERR "$f:$line:1:ERROR: no header present\n"; + return 2; + } + + my @desc; + my $quote = 0; + my $blankline = 0; + my $header = 0; + + # cut off the leading path from the file name, if any + $f =~ s/^(.*[\\\/])//; + + push @desc, ".\\\" generated by cd2nroff $cd2nroff from $f\n"; + push @desc, ".TH $title $section \"$date\" $source\n"; + while(<$fh>) { + $line++; + + $d = $_; + + if($quote) { + if($quote == 4) { + # remove the indentation + if($d =~ /^ (.*)/) { + push @desc, "$1\n"; + next; + } + else { + # end of quote + $quote = 0; + push @desc, ".fi\n"; + next; + } + } + if(/^~~~/) { + # end of quote + $quote = 0; + push @desc, ".fi\n"; + next; + } + # convert single backslashes to doubles + $d =~ s/\\/\\\\/g; + # lines starting with a period needs it escaped + $d =~ s/^\./\\&./; + push @desc, $d; + next; + } + + # remove single line HTML comments + $d =~ s///g; + + # **bold** + $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; + # *italics* + $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + + my $back = $d; + + # remove all backticked pieces + $back =~ s/\`(.*?)\`//g; + + if($back =~ /[^\\][\<\>]/) { + print STDERR "$f:$line:1:ERROR: un-escaped < or > used\n"; + $errors++; + } + # convert backslash-'<' or '> to just the second character + $d =~ s/\\([<>])/$1/g; + + # mentions of curl symbols with manpages use italics by default + $d =~ s/((lib|)curl([^ ]*\(3\)))/\\fI$1\\fP/gi; + + # backticked becomes italics + $d =~ s/\`(.*?)\`/\\fI$1\\fP/g; + + if(/^## (.*)/) { + my $word = $1; + # if there are enclosing quotes, remove them first + $word =~ s/[\"\'\`](.*)[\"\'\`]\z/$1/; + + # enclose in double quotes if there is a space present + if($word =~ / /) { + push @desc, ".IP \"$word\"\n"; + } + else { + push @desc, ".IP $word\n"; + } + $header = 1; + } + elsif(/^##/) { + # end of IP sequence + push @desc, ".PP\n"; + $header = 1; + } + elsif(/^# (.*)/) { + my $word = $1; + # if there are enclosing quotes, remove them first + $word =~ s/[\"\'](.*)[\"\']\z/$1/; + push @desc, ".SH $word\n"; + $header = 1; + } + elsif(/^~~~c/) { + # start of a code section, not indented + $quote = 1; + push @desc, "\n" if($blankline && !$header); + $header = 0; + push @desc, ".nf\n"; + } + elsif(/^~~~/) { + # start of a quote section; not code, not indented + $quote = 1; + push @desc, "\n" if($blankline && !$header); + $header = 0; + push @desc, ".nf\n"; + } + elsif(/^ (.*)/) { + # quoted, indented by 4 space + $quote = 4; + push @desc, "\n" if($blankline && !$header); + $header = 0; + push @desc, ".nf\n$1\n"; + } + elsif(/^[ \t]*\n/) { + # count and ignore blank lines + $blankline++; + } + else { + # don't output newlines if this is the first content after a + # header + push @desc, "\n" if($blankline && !$header); + $blankline = 0; + $header = 0; + + # quote minuses in the output + $d =~ s/([^\\])-/$1\\-/g; + # replace single quotes + $d =~ s/\'/\\(aq/g; + # handle double quotes first on the line + $d =~ s/^(\s*)\"/$1\\&\"/; + + # lines starting with a period needs it escaped + $d =~ s/^\./\\&./; + + if($d =~ /^(.*) /) { + printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n", + length($1); + $errors++; + } + if($d =~ /^[ \t]*\n/) { + # replaced away all contents + $blankline= 1; + } + else { + push @desc, $d; + } + } + } + if($fh != \*STDIN) { + close($fh); + } + push @desc, outseealso(@seealso); + if($dir) { + if($keepfilename) { + $title = $f; + $title =~ s/\.[^.]*$//; + } + my $outfile = "$dir/$title.$section"; + if(defined($extension)) { + $outfile .= $extension; + } + if(!open(O, ">", $outfile)) { + print STDERR "Failed to open $outfile : $!\n"; + return 1; + } + print O @desc; + close(O); + } + else { + print @desc; + } + return $errors; +} + +if(@ARGV) { + for my $f (@ARGV) { + my $r = single($f); + if($r) { + exit $r; + } + } +} +else { + exit single(); +} diff --git a/docs/libssh2_agent_connect.3 b/docs/libssh2_agent_connect.3 deleted file mode 100644 index 081ec39e..00000000 --- a/docs/libssh2_agent_connect.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_connect 3 "23 Dec 2009" "libssh2" "libssh2" -.SH NAME -libssh2_agent_connect - connect to an ssh-agent -.SH SYNOPSIS -.nf -#include - -int -libssh2_agent_connect(LIBSSH2_AGENT *agent); -.fi -.SH DESCRIPTION -Connect to an ssh-agent running on the system. - -Call \fBlibssh2_agent_disconnect(3)\fP to close the connection after -you are doing using it. -.SH RETURN VALUE -Returns 0 if succeeded, or a negative value for error. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_init(3) -.BR libssh2_agent_disconnect(3) diff --git a/docs/libssh2_agent_connect.md b/docs/libssh2_agent_connect.md new file mode 100644 index 00000000..8ef98913 --- /dev/null +++ b/docs/libssh2_agent_connect.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_connect +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_disconnect(3) + - libssh2_agent_init(3) +--- + +# NAME + +libssh2_agent_connect - connect to an ssh-agent + +# SYNOPSIS + +~~~c +#include + +int +libssh2_agent_connect(LIBSSH2_AGENT *agent); +~~~ + +# DESCRIPTION + +Connect to an ssh-agent running on the system. + +Call **libssh2_agent_disconnect(3)** to close the connection after +you are doing using it. + +# RETURN VALUE + +Returns 0 if succeeded, or a negative value for error. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_agent_disconnect.3 b/docs/libssh2_agent_disconnect.3 deleted file mode 100644 index 136a6e19..00000000 --- a/docs/libssh2_agent_disconnect.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_disconnect 3 "23 Dec 2009" "libssh2" "libssh2" -.SH NAME -libssh2_agent_disconnect - close a connection to an ssh-agent -.SH SYNOPSIS -.nf -#include - -int -libssh2_agent_disconnect(LIBSSH2_AGENT *agent); -.fi -.SH DESCRIPTION -Close a connection to an ssh-agent. - -.SH RETURN VALUE -Returns 0 if succeeded, or a negative value for error. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_connect(3) -.BR libssh2_agent_free(3) diff --git a/docs/libssh2_agent_disconnect.md b/docs/libssh2_agent_disconnect.md new file mode 100644 index 00000000..960c0dd4 --- /dev/null +++ b/docs/libssh2_agent_disconnect.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_disconnect +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_connect(3) + - libssh2_agent_free(3) +--- + +# NAME + +libssh2_agent_disconnect - close a connection to an ssh-agent + +# SYNOPSIS + +~~~c +#include + +int +libssh2_agent_disconnect(LIBSSH2_AGENT *agent); +~~~ + +# DESCRIPTION + +Close a connection to an ssh-agent. + +# RETURN VALUE + +Returns 0 if succeeded, or a negative value for error. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_agent_free.3 b/docs/libssh2_agent_free.3 deleted file mode 100644 index 1011f444..00000000 --- a/docs/libssh2_agent_free.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_free 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME -libssh2_agent_free - free an ssh-agent handle -.SH SYNOPSIS -.nf -#include - -void -libssh2_agent_free(LIBSSH2_AGENT *agent); -.fi -.SH DESCRIPTION -Free an ssh-agent handle. This function also frees the internal -collection of public keys. -.SH RETURN VALUE -None. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_init(3) -.BR libssh2_agent_disconnect(3) diff --git a/docs/libssh2_agent_free.md b/docs/libssh2_agent_free.md new file mode 100644 index 00000000..c340aac3 --- /dev/null +++ b/docs/libssh2_agent_free.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_free +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_disconnect(3) + - libssh2_agent_init(3) +--- + +# NAME + +libssh2_agent_free - free an ssh-agent handle + +# SYNOPSIS + +~~~c +#include + +void +libssh2_agent_free(LIBSSH2_AGENT *agent); +~~~ + +# DESCRIPTION + +Free an ssh-agent handle. This function also frees the internal +collection of public keys. + +# RETURN VALUE + +None. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_agent_get_identity.3 b/docs/libssh2_agent_get_identity.md similarity index 55% rename from docs/libssh2_agent_get_identity.3 rename to docs/libssh2_agent_get_identity.md index 2372e9c0..87ddded9 100644 --- a/docs/libssh2_agent_get_identity.3 +++ b/docs/libssh2_agent_get_identity.md @@ -1,36 +1,50 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_get_identity 3 "23 Dec 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_get_identity +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_list_identities(3) + - libssh2_agent_userauth(3) +--- + +# NAME + libssh2_agent_get_identity - get a public key off the collection of public keys managed by ssh-agent -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_agent_get_identity(LIBSSH2_AGENT *agent, struct libssh2_agent_publickey **store, struct libssh2_agent_publickey *prev); -.fi -.SH DESCRIPTION -\fIlibssh2_agent_get_identity(3)\fP allows an application to iterate +~~~ + +# DESCRIPTION + +*libssh2_agent_get_identity(3)* allows an application to iterate over all public keys in the collection managed by ssh-agent. -\fIstore\fP should point to a pointer that gets filled in to point to the +*store* should point to a pointer that gets filled in to point to the public key data. -\fIprev\fP is a pointer to a previous 'struct libssh2_agent_publickey' +*prev* is a pointer to a previous 'struct libssh2_agent_publickey' as returned by a previous invoke of this function, or NULL to get the first entry in the internal collection. -.SH RETURN VALUE + +# RETURN VALUE + Returns 0 if everything is fine and information about a host was stored in -the \fIstore\fP struct. +the *store* struct. Returns 1 if it reached the end of public keys. Returns negative values for error -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_list_identities(3) -.BR libssh2_agent_userauth(3) diff --git a/docs/libssh2_agent_get_identity_path.3 b/docs/libssh2_agent_get_identity_path.md similarity index 50% rename from docs/libssh2_agent_get_identity_path.3 rename to docs/libssh2_agent_get_identity_path.md index 703d04ab..ee6e6e4a 100644 --- a/docs/libssh2_agent_get_identity_path.3 +++ b/docs/libssh2_agent_get_identity_path.md @@ -1,22 +1,35 @@ -.\" Copyright (C) Will Cosgrove -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_get_identity_path 3 "6 Mar 2019" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Will Cosgrove +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_get_identity_path +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_init(3) + - libssh2_agent_set_identity_path(3) +--- + +# NAME + libssh2_agent_get_identity_path - gets the custom ssh-agent socket path -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include const char * libssh2_agent_get_identity_path(LIBSSH2_AGENT *agent); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Returns the custom agent identity socket path if set using libssh2_agent_set_identity_path() -.SH RETURN VALUE +# RETURN VALUE + Returns the socket path on disk. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.9 -.SH SEE ALSO -.BR libssh2_agent_init(3) -.BR libssh2_agent_set_identity_path(3) diff --git a/docs/libssh2_agent_init.3 b/docs/libssh2_agent_init.md similarity index 53% rename from docs/libssh2_agent_init.3 rename to docs/libssh2_agent_init.md index c3653617..e633f421 100644 --- a/docs/libssh2_agent_init.3 +++ b/docs/libssh2_agent_init.md @@ -1,28 +1,42 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_init 3 "23 Dec 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_init +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_connect(3) + - libssh2_agent_free(3) +--- + +# NAME + libssh2_agent_init - init an ssh-agent handle -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include LIBSSH2_AGENT * libssh2_agent_init(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Init an ssh-agent handle. Returns the handle to an internal representation of an ssh-agent connection. After the successful -initialization, an application can call \fBlibssh2_agent_connect(3)\fP +initialization, an application can call **libssh2_agent_connect(3)** to connect to a running ssh-agent. -Call \fBlibssh2_agent_free(3)\fP to free the handle again after you are +Call **libssh2_agent_free(3)** to free the handle again after you are doing using it. -.SH RETURN VALUE + +# RETURN VALUE + Returns a handle pointer or NULL if something went wrong. The returned handle is used as input to all other ssh-agent related functions libssh2 provides. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_connect(3) -.BR libssh2_agent_free(3) diff --git a/docs/libssh2_agent_list_identities.3 b/docs/libssh2_agent_list_identities.3 deleted file mode 100644 index bac2c735..00000000 --- a/docs/libssh2_agent_list_identities.3 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_list_identities 3 "23 Dec 2009" "libssh2" "libssh2" -.SH NAME -libssh2_agent_list_identities - request an ssh-agent to list of public keys. -.SH SYNOPSIS -.nf -#include - -int -libssh2_agent_list_identities(LIBSSH2_AGENT *agent); -.fi -.SH DESCRIPTION -Request an ssh-agent to list of public keys, and stores them in the -internal collection of the handle. Call -\fIlibssh2_agent_get_identity(3)\fP to get a public key off the -collection. - -.SH RETURN VALUE -Returns 0 if succeeded, or a negative value for error. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_connect(3) -.BR libssh2_agent_get_identity(3) diff --git a/docs/libssh2_agent_list_identities.md b/docs/libssh2_agent_list_identities.md new file mode 100644 index 00000000..f40e93b3 --- /dev/null +++ b/docs/libssh2_agent_list_identities.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_list_identities +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_connect(3) + - libssh2_agent_get_identity(3) +--- + +# NAME + +libssh2_agent_list_identities - request an ssh-agent to list of public keys. + +# SYNOPSIS + +~~~c +#include + +int +libssh2_agent_list_identities(LIBSSH2_AGENT *agent); +~~~ + +# DESCRIPTION + +Request an ssh-agent to list of public keys, and stores them in the +internal collection of the handle. Call *libssh2_agent_get_identity(3)* +to get a public key off the collection. + +# RETURN VALUE + +Returns 0 if succeeded, or a negative value for error. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_agent_set_identity_path.3 b/docs/libssh2_agent_set_identity_path.3 deleted file mode 100644 index 5a1a237d..00000000 --- a/docs/libssh2_agent_set_identity_path.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) Will Cosgrove -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_set_identity_path 3 "6 Mar 2019" "libssh2" "libssh2" -.SH NAME -libssh2_agent_set_identity_path - set an ssh-agent socket path on disk -.SH SYNOPSIS -.nf -#include - -void -libssh2_agent_set_identity_path(LIBSSH2_AGENT *agent, const char *path); -.fi -.SH DESCRIPTION -Allows a custom agent identity socket path instead of the default SSH_AUTH_SOCK env value - -.SH RETURN VALUE -Returns void -.SH AVAILABILITY -Added in libssh2 1.9 -.SH SEE ALSO -.BR libssh2_agent_init(3) -.BR libssh2_agent_get_identity_path(3) diff --git a/docs/libssh2_agent_set_identity_path.md b/docs/libssh2_agent_set_identity_path.md new file mode 100644 index 00000000..a79d5eee --- /dev/null +++ b/docs/libssh2_agent_set_identity_path.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) Will Cosgrove +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_set_identity_path +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_get_identity_path(3) + - libssh2_agent_init(3) +--- + +# NAME + +libssh2_agent_set_identity_path - set an ssh-agent socket path on disk + +# SYNOPSIS + +~~~c +#include + +void +libssh2_agent_set_identity_path(LIBSSH2_AGENT *agent, const char *path); +~~~ + +# DESCRIPTION + +Allows a custom agent identity socket path instead of the default SSH_AUTH_SOCK env value + +# RETURN VALUE + +Returns void + +# AVAILABILITY + +Added in libssh2 1.9 diff --git a/docs/libssh2_agent_sign.3 b/docs/libssh2_agent_sign.3 deleted file mode 100644 index c4ba95b3..00000000 --- a/docs/libssh2_agent_sign.3 +++ /dev/null @@ -1,54 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_sign 3 "1 Oct 2022" "libssh2" "libssh2" -.SH NAME -libssh2_agent_sign - sign data, with the help of ssh-agent -.SH SYNOPSIS -.nf -#include - -int -libssh2_agent_sign(LIBSSH2_AGENT *agent, - struct libssh2_agent_publickey *identity, - unsigned char **sig, - size_t *s_len, - const unsigned char *data, - size_t d_len, - const char *method, - unsigned int method_len); -.fi -.SH DESCRIPTION -\fIagent\fP - ssh-agent handle as returned by -.BR libssh2_agent_init(3) - -\fIidentity\fP - Public key to authenticate with, as returned by -.BR libssh2_agent_get_identity(3) - -\fIsig\fP - A pointer to a buffer in which to place the signature. The caller -is responsible for freeing the signature with LIBSSH2_FREE. - -\fIs_len\fP - A pointer to the length of the sig parameter. - -\fIdata\fP - The data to sign. - -\fId_len\fP - The length of the data parameter. - -\fImethod\fP - A buffer indicating the signing method. This should match the -string at the start of identity->blob. - -\fImethod_len\fP - The length of the method parameter. - -Sign data using an ssh-agent. This function can be used in a callback -registered with libssh2_session_callback_set2(3) using -LIBSSH2_CALLBACK_AUTHAGENT_SIGN to sign an authentication challenge from a -server. However, the client is responsible for implementing the code that calls -this callback in response to a SSH2_AGENTC_SIGN_REQUEST message. -.SH RETURN VALUE -Returns 0 if succeeded, or a negative value for error. -.SH AVAILABILITY -Added in libssh2 1.11.0 -.SH SEE ALSO -.BR libssh2_agent_init(3) -.BR libssh2_agent_get_identity(3) -.BR libssh2_agent_userauth(3) -.BR libssh2_session_callback_set2(3) diff --git a/docs/libssh2_agent_sign.md b/docs/libssh2_agent_sign.md new file mode 100644 index 00000000..48fb1b48 --- /dev/null +++ b/docs/libssh2_agent_sign.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_sign +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_get_identity(3) + - libssh2_agent_init(3) + - libssh2_agent_userauth(3) + - libssh2_session_callback_set2(3) +--- + +# NAME + +libssh2_agent_sign - sign data, with the help of ssh-agent + +# SYNOPSIS + +~~~c +#include + +int +libssh2_agent_sign(LIBSSH2_AGENT *agent, + struct libssh2_agent_publickey *identity, + unsigned char **sig, + size_t *s_len, + const unsigned char *data, + size_t d_len, + const char *method, + unsigned int method_len); +~~~ + +# DESCRIPTION + +*agent* - ssh-agent handle as returned by libssh2_agent_init(3). + +*identity* - Public key to authenticate with, as returned by +libssh2_agent_get_identity(3) + +*sig* - A pointer to a buffer in which to place the signature. The caller +is responsible for freeing the signature with LIBSSH2_FREE. + +*s_len* - A pointer to the length of the sig parameter. + +*data* - The data to sign. + +*d_len* - The length of the data parameter. + +*method* - A buffer indicating the signing method. This should match the +string at the start of identity-\>blob. + +*method_len* - The length of the method parameter. + +Sign data using an ssh-agent. This function can be used in a callback +registered with libssh2_session_callback_set2(3) using +LIBSSH2_CALLBACK_AUTHAGENT_SIGN to sign an authentication challenge from a +server. However, the client is responsible for implementing the code that calls +this callback in response to a SSH2_AGENTC_SIGN_REQUEST message. + +# RETURN VALUE + +Returns 0 if succeeded, or a negative value for error. + +# AVAILABILITY + +Added in libssh2 1.11.0 diff --git a/docs/libssh2_agent_userauth.3 b/docs/libssh2_agent_userauth.3 deleted file mode 100644 index 82a344c0..00000000 --- a/docs/libssh2_agent_userauth.3 +++ /dev/null @@ -1,32 +0,0 @@ -.\" Copyright (C) Daiki Ueno -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_agent_userauth 3 "23 Dec 2009" "libssh2" "libssh2" -.SH NAME -libssh2_agent_userauth - authenticate a session with a public key, with the help of ssh-agent -.SH SYNOPSIS -.nf -#include - -int -libssh2_agent_userauth(LIBSSH2_AGENT *agent, - const char *username, - struct libssh2_agent_publickey *identity); -.fi -.SH DESCRIPTION -\fIagent\fP - ssh-agent handle as returned by -.BR libssh2_agent_init(3) - -\fIusername\fP - Remote user name to authenticate as. - -\fIidentity\fP - Public key to authenticate with, as returned by -.BR libssh2_agent_get_identity(3) - -Attempt public key authentication with the help of ssh-agent. -.SH RETURN VALUE -Returns 0 if succeeded, or a negative value for error. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_agent_init(3) -.BR libssh2_agent_get_identity(3) -.BR libssh2_agent_sign(3) diff --git a/docs/libssh2_agent_userauth.md b/docs/libssh2_agent_userauth.md new file mode 100644 index 00000000..b6b08c2c --- /dev/null +++ b/docs/libssh2_agent_userauth.md @@ -0,0 +1,45 @@ +--- +c: Copyright (C) Daiki Ueno +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_agent_userauth +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_get_identity(3) + - libssh2_agent_init(3) + - libssh2_agent_sign(3) +--- + +# NAME + +libssh2_agent_userauth - authenticate a session with a public key, with the help of ssh-agent + +# SYNOPSIS + +~~~c +#include + +int +libssh2_agent_userauth(LIBSSH2_AGENT *agent, + const char *username, + struct libssh2_agent_publickey *identity); +~~~ + +# DESCRIPTION + +*agent* - ssh-agent handle as returned by libssh2_agent_init(3) + +*username* - Remote user name to authenticate as. + +*identity* - Public key to authenticate with, as returned by +libssh2_agent_get_identity(3) + +Attempt public key authentication with the help of ssh-agent. + +# RETURN VALUE + +Returns 0 if succeeded, or a negative value for error. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_banner_set.3 b/docs/libssh2_banner_set.3 deleted file mode 100644 index 5f687e5a..00000000 --- a/docs/libssh2_banner_set.3 +++ /dev/null @@ -1,36 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_banner_set 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_banner_set - set the SSH protocol banner for the local client -.SH SYNOPSIS -.nf -#include - -int -libssh2_banner_set(LIBSSH2_SESSION *session, const char *banner); -.fi -.SH DESCRIPTION -This function is \fBDEPRECATED\fP in 1.4.0. Use the -\fIlibssh2_session_banner_set(3)\fP function instead! - -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIbanner\fP - A pointer to a user defined banner - -Set the banner that will be sent to the remote host when the SSH session is -started with -.BR libssh2_session_handshake(3) -This is optional; a banner corresponding to the protocol and libssh2 version -will be sent by default. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH AVAILABILITY -Marked as deprecated since 1.4.0 -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -.SH SEE ALSO -.BR libssh2_session_handshake(3) diff --git a/docs/libssh2_banner_set.md b/docs/libssh2_banner_set.md new file mode 100644 index 00000000..364c1d45 --- /dev/null +++ b/docs/libssh2_banner_set.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_banner_set +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_handshake(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_banner_set - set the SSH protocol banner for the local client + +# SYNOPSIS + +~~~c +#include + +int +libssh2_banner_set(LIBSSH2_SESSION *session, const char *banner); +~~~ + +# DESCRIPTION + +This function is **DEPRECATED** in 1.4.0. Use the +*libssh2_session_banner_set(3)* function instead! + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*banner* - A pointer to a user defined banner + +Set the banner that will be sent to the remote host when the SSH session is +started with libssh2_session_handshake(3) +This is optional; a banner corresponding to the protocol and libssh2 version +will be sent by default. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# AVAILABILITY + +Marked as deprecated since 1.4.0 + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. diff --git a/docs/libssh2_base64_decode.3 b/docs/libssh2_base64_decode.md similarity index 73% rename from docs/libssh2_base64_decode.3 rename to docs/libssh2_base64_decode.md index 7a67202d..997ac03c 100644 --- a/docs/libssh2_base64_decode.3 +++ b/docs/libssh2_base64_decode.md @@ -1,18 +1,29 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_base64_decode 3 "23 Dec 2008" "libssh2 0.1" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_base64_decode +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_base64_decode - decode a base64 encoded string -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_base64_decode(LIBSSH2_SESSION *session, char **dest, unsigned int *dest_len, const char *src, unsigned int src_len); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This function is deemed DEPRECATED in 1.0 and will be removed from libssh2 in a future version. Do not use it! @@ -22,9 +33,13 @@ to. The returned buffer is allocated by this function, but it is not clear how to free that memory! -.SH BUGS + +# BUGS + The memory that *dest points to is allocated by the malloc function libssh2 uses, but there is no way for an application to free this data in a safe and reliable way! -.SH RETURN VALUE -0 if successful, \-1 if any error occurred. + +# RETURN VALUE + +0 if successful, -1 if any error occurred. diff --git a/docs/libssh2_channel_close.3 b/docs/libssh2_channel_close.md similarity index 54% rename from docs/libssh2_channel_close.3 rename to docs/libssh2_channel_close.md index fd9d0001..e723a20c 100644 --- a/docs/libssh2_channel_close.3 +++ b/docs/libssh2_channel_close.md @@ -1,29 +1,43 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_close 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_close +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_channel_wait_closed(3) +--- + +# NAME + libssh2_channel_close - close a channel -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_channel_close(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -\fIchannel\fP - active channel stream to set closed status on. +~~~ + +# DESCRIPTION + +*channel* - active channel stream to set closed status on. Close an active data channel. In practice this means sending an SSH_MSG_CLOSE packet to the remote host which serves as instruction that no further data will be sent to it. The remote host may still send data back until it sends its own close message in response. To wait for the remote end to close its -connection as well, follow this command with -.BR libssh2_channel_wait_closed(3) -.SH RETURN VALUE +connection as well, follow this command with libssh2_channel_wait_closed(3). + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) + +# ERRORS + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. diff --git a/docs/libssh2_channel_direct_streamlocal_ex.3 b/docs/libssh2_channel_direct_streamlocal_ex.3 deleted file mode 100644 index c2c3d5ca..00000000 --- a/docs/libssh2_channel_direct_streamlocal_ex.3 +++ /dev/null @@ -1,34 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_direct_streamlocal_ex 3 "10 Apr 2023" "libssh2 1.11.0" "libssh2" -.SH NAME -libssh2_channel_direct_streamlocal_ex - Tunnel a UNIX socket connection through an SSH session -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_channel_direct_streamlocal_ex(LIBSSH2_SESSION *session, - const char *socket_path, - const char *shost, int sport); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIsocket_path\fP - UNIX socket to connect to using the SSH host as a proxy. - -\fIshost\fP - Host to tell the SSH server the connection originated on. - -\fIsport\fP - Port to tell the SSH server the connection originated from. - -Tunnel a UNIX socket connection through the SSH transport via the remote host to -a third party. Communication from the client to the SSH server remains -encrypted, communication from the server to the 3rd party host travels -in cleartext. -.SH RETURN VALUE -Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_channel_direct_streamlocal_ex.md b/docs/libssh2_channel_direct_streamlocal_ex.md new file mode 100644 index 00000000..cc0b334c --- /dev/null +++ b/docs/libssh2_channel_direct_streamlocal_ex.md @@ -0,0 +1,47 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_direct_streamlocal_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_channel_direct_streamlocal_ex - Tunnel a UNIX socket connection through an SSH session + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_channel_direct_streamlocal_ex(LIBSSH2_SESSION *session, + const char *socket_path, + const char *shost, int sport); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*socket_path* - UNIX socket to connect to using the SSH host as a proxy. + +*shost* - Host to tell the SSH server the connection originated on. + +*sport* - Port to tell the SSH server the connection originated from. + +Tunnel a UNIX socket connection through the SSH transport via the remote host to +a third party. Communication from the client to the SSH server remains +encrypted, communication from the server to the 3rd party host travels +in cleartext. + +# RETURN VALUE + +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. diff --git a/docs/libssh2_channel_direct_tcpip.3 b/docs/libssh2_channel_direct_tcpip.3 deleted file mode 100644 index 02033fc0..00000000 --- a/docs/libssh2_channel_direct_tcpip.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_direct_tcpip 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_direct_tcpip - convenience macro for \fIlibssh2_channel_direct_tcpip_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, - const char *host, int port); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_direct_tcpip_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_direct_tcpip_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_direct_tcpip_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_direct_tcpip_ex(3) diff --git a/docs/libssh2_channel_direct_tcpip.md b/docs/libssh2_channel_direct_tcpip.md new file mode 100644 index 00000000..397b69aa --- /dev/null +++ b/docs/libssh2_channel_direct_tcpip.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_direct_tcpip +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_direct_tcpip_ex(3) +--- + +# NAME + +libssh2_channel_direct_tcpip - convenience macro for *libssh2_channel_direct_tcpip_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, + const char *host, int port); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_direct_tcpip_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_direct_tcpip_ex(3)* + +# ERRORS + +See *libssh2_channel_direct_tcpip_ex(3)* diff --git a/docs/libssh2_channel_direct_tcpip_ex.3 b/docs/libssh2_channel_direct_tcpip_ex.md similarity index 50% rename from docs/libssh2_channel_direct_tcpip_ex.3 rename to docs/libssh2_channel_direct_tcpip_ex.md index 02e8f84b..bd6f0ed4 100644 --- a/docs/libssh2_channel_direct_tcpip_ex.3 +++ b/docs/libssh2_channel_direct_tcpip_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_direct_tcpip_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_direct_tcpip_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_channel_direct_tcpip_ex - Tunnel a TCP connection through an SSH session -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include LIBSSH2_CHANNEL * @@ -15,26 +25,29 @@ libssh2_channel_direct_tcpip_ex(LIBSSH2_SESSION *session, LIBSSH2_CHANNEL * libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, const char *host, int port); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIhost\fP - Third party host to connect to using the SSH host as a proxy. +# DESCRIPTION -\fIport\fP - Port on third party host to connect to. +*session* - Session instance as returned by libssh2_session_init_ex(3) -\fIshost\fP - Host to tell the SSH server the connection originated on. +*host* - Third party host to connect to using the SSH host as a proxy. -\fIsport\fP - Port to tell the SSH server the connection originated from. +*port* - Port on third party host to connect to. + +*shost* - Host to tell the SSH server the connection originated on. + +*sport* - Port to tell the SSH server the connection originated from. Tunnel a TCP/IP connection through the SSH transport via the remote host to a third party. Communication from the client to the SSH server remains encrypted, communication from the server to the 3rd party host travels in cleartext. -.SH RETURN VALUE + +# RETURN VALUE + Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. diff --git a/docs/libssh2_channel_eof.3 b/docs/libssh2_channel_eof.3 deleted file mode 100644 index 9d9fd745..00000000 --- a/docs/libssh2_channel_eof.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_eof 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_eof - check a channel's EOF status -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_eof(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -\fIchannel\fP - active channel stream to set closed status on. - -Check if the remote host has sent an EOF status for the selected stream. -.SH RETURN VALUE -Returns 1 if the remote host has sent EOF, otherwise 0. Negative on -failure. -.SH SEE ALSO -.BR libssh2_channel_close(3) diff --git a/docs/libssh2_channel_eof.md b/docs/libssh2_channel_eof.md new file mode 100644 index 00000000..c8c0dc2f --- /dev/null +++ b/docs/libssh2_channel_eof.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_eof +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_close(3) +--- + +# NAME + +libssh2_channel_eof - check a channel's EOF status + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_eof(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +*channel* - active channel stream to set closed status on. + +Check if the remote host has sent an EOF status for the selected stream. + +# RETURN VALUE + +Returns 1 if the remote host has sent EOF, otherwise 0. Negative on +failure. diff --git a/docs/libssh2_channel_exec.3 b/docs/libssh2_channel_exec.3 deleted file mode 100644 index 08644d5e..00000000 --- a/docs/libssh2_channel_exec.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_exec 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_exec - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_exec(LIBSSH2_CHANNEL *channel, const char *command); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_process_startup(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_process_startup(3)\fP -.SH ERRORS -See \fIlibssh2_channel_process_startup(3)\fP -.SH SEE ALSO -.BR libssh2_channel_process_startup(3) diff --git a/docs/libssh2_channel_exec.md b/docs/libssh2_channel_exec.md new file mode 100644 index 00000000..cf59891b --- /dev/null +++ b/docs/libssh2_channel_exec.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_exec +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_process_startup(3) +--- + +# NAME + +libssh2_channel_exec - convenience macro for *libssh2_channel_process_startup(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_exec(LIBSSH2_CHANNEL *channel, const char *command); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_process_startup(3)*. + +# RETURN VALUE + +See *libssh2_channel_process_startup(3)* + +# ERRORS + +See *libssh2_channel_process_startup(3)* diff --git a/docs/libssh2_channel_flush.3 b/docs/libssh2_channel_flush.3 deleted file mode 100644 index 79a7750b..00000000 --- a/docs/libssh2_channel_flush.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_flush 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_flush - convenience macro for \fIlibssh2_channel_flush_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_flush(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_flush_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_flush_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_flush_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_flush_ex(3) diff --git a/docs/libssh2_channel_flush.md b/docs/libssh2_channel_flush.md new file mode 100644 index 00000000..8bdff482 --- /dev/null +++ b/docs/libssh2_channel_flush.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_flush +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_flush_ex(3) +--- + +# NAME + +libssh2_channel_flush - convenience macro for *libssh2_channel_flush_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_flush(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_flush_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_flush_ex(3)* + +# ERRORS + +See *libssh2_channel_flush_ex(3)* diff --git a/docs/libssh2_channel_flush_ex.3 b/docs/libssh2_channel_flush_ex.md similarity index 56% rename from docs/libssh2_channel_flush_ex.3 rename to docs/libssh2_channel_flush_ex.md index 4a445ba4..3c3455b4 100644 --- a/docs/libssh2_channel_flush_ex.3 +++ b/docs/libssh2_channel_flush_ex.md @@ -1,10 +1,19 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_flush_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_flush_ex +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_channel_flush_ex - flush a channel -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -15,20 +24,24 @@ libssh2_channel_flush(LIBSSH2_CHANNEL *channel); int libssh2_channel_flush_stderr(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -\fIchannel\fP - Active channel stream to flush. +~~~ -\fIstreamid\fP - Specific substream number to flush. Groups of substreams may +# DESCRIPTION + +*channel* - Active channel stream to flush. + +*streamid* - Specific substream number to flush. Groups of substreams may be flushed by passing on of the following Constants. -.br -\fBLIBSSH2_CHANNEL_FLUSH_EXTENDED_DATA\fP: Flush all extended data substreams -.br -\fBLIBSSH2_CHANNEL_FLUSH_ALL\fP: Flush all substreams + +**LIBSSH2_CHANNEL_FLUSH_EXTENDED_DATA**: Flush all extended data substreams + +**LIBSSH2_CHANNEL_FLUSH_ALL**: Flush all substreams Flush the read buffer for a given channel instance. Individual substreams may be flushed by number or using one of the provided macros. -.SH RETURN VALUE + +# RETURN VALUE + Return the number of bytes flushed or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. diff --git a/docs/libssh2_channel_flush_stderr.3 b/docs/libssh2_channel_flush_stderr.3 deleted file mode 100644 index 6cd8ade6..00000000 --- a/docs/libssh2_channel_flush_stderr.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_flush_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_flush_stderr - convenience macro for \fIlibssh2_channel_flush_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_flush_stderr(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_flush_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_flush_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_flush_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_flush_ex(3) diff --git a/docs/libssh2_channel_flush_stderr.md b/docs/libssh2_channel_flush_stderr.md new file mode 100644 index 00000000..a533a395 --- /dev/null +++ b/docs/libssh2_channel_flush_stderr.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_flush_stderr +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_flush_ex(3) +--- + +# NAME + +libssh2_channel_flush_stderr - convenience macro for *libssh2_channel_flush_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_flush_stderr(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_flush_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_flush_ex(3)* + +# ERRORS + +See *libssh2_channel_flush_ex(3)* diff --git a/docs/libssh2_channel_forward_accept.3 b/docs/libssh2_channel_forward_accept.3 deleted file mode 100644 index e6e57e21..00000000 --- a/docs/libssh2_channel_forward_accept.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_forward_accept 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_forward_accept - accept a queued connection -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_channel_forward_accept(LIBSSH2_LISTENER *listener); -.fi -.SH DESCRIPTION -\fIlistener\fP is a forwarding listener instance as returned by -\fBlibssh2_channel_forward_listen_ex(3)\fP. -.SH RETURN VALUE -A newly allocated channel instance or NULL on failure. -.SH ERRORS -When this function returns NULL use \fIlibssh2_session_last_errno(3)\fP to -extract the error code. If that code is \fILIBSSH2_ERROR_EAGAIN\fP, the -session is set to do non-blocking I/O but the call would block. -.SH SEE ALSO -.BR libssh2_channel_forward_listen_ex(3) diff --git a/docs/libssh2_channel_forward_accept.md b/docs/libssh2_channel_forward_accept.md new file mode 100644 index 00000000..21f29d2f --- /dev/null +++ b/docs/libssh2_channel_forward_accept.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_forward_accept +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_forward_listen_ex(3) +--- + +# NAME + +libssh2_channel_forward_accept - accept a queued connection + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_channel_forward_accept(LIBSSH2_LISTENER *listener); +~~~ + +# DESCRIPTION + +*listener* is a forwarding listener instance as returned by +**libssh2_channel_forward_listen_ex(3)**. + +# RETURN VALUE + +A newly allocated channel instance or NULL on failure. + +# ERRORS + +When this function returns NULL use *libssh2_session_last_errno(3)* to +extract the error code. If that code is *LIBSSH2_ERROR_EAGAIN*, the +session is set to do non-blocking I/O but the call would block. diff --git a/docs/libssh2_channel_forward_cancel.3 b/docs/libssh2_channel_forward_cancel.3 deleted file mode 100644 index 0e11f518..00000000 --- a/docs/libssh2_channel_forward_cancel.3 +++ /dev/null @@ -1,28 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_forward_cancel 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_forward_cancel - cancel a forwarded TCP port -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_forward_cancel(LIBSSH2_LISTENER *listener); -.fi -.SH DESCRIPTION -\fIlistener\fP - Forwarding listener instance as returned by -.BR libssh2_channel_forward_listen_ex(3) - -Instruct the remote host to stop listening for new connections on a previously -requested host/port. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. -.SH SEE ALSO -.BR libssh2_channel_forward_listen_ex(3) diff --git a/docs/libssh2_channel_forward_cancel.md b/docs/libssh2_channel_forward_cancel.md new file mode 100644 index 00000000..cc8d7316 --- /dev/null +++ b/docs/libssh2_channel_forward_cancel.md @@ -0,0 +1,42 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_forward_cancel +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_forward_listen_ex(3) +--- + +# NAME + +libssh2_channel_forward_cancel - cancel a forwarded TCP port + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_forward_cancel(LIBSSH2_LISTENER *listener); +~~~ + +# DESCRIPTION + +*listener* - Forwarding listener instance as returned by +libssh2_channel_forward_listen_ex(3) + +Instruct the remote host to stop listening for new connections on a previously +requested host/port. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. diff --git a/docs/libssh2_channel_forward_listen.3 b/docs/libssh2_channel_forward_listen.3 deleted file mode 100644 index ab1739cf..00000000 --- a/docs/libssh2_channel_forward_listen.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_forward_listen 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_forward_listen - convenience macro for \fIlibssh2_channel_forward_listen_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_forward_listen_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_forward_listen_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_forward_listen_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_forward_listen_ex(3) diff --git a/docs/libssh2_channel_forward_listen.md b/docs/libssh2_channel_forward_listen.md new file mode 100644 index 00000000..9cd3537b --- /dev/null +++ b/docs/libssh2_channel_forward_listen.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_forward_listen +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_forward_listen_ex(3) +--- + +# NAME + +libssh2_channel_forward_listen - convenience macro for *libssh2_channel_forward_listen_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_forward_listen_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_forward_listen_ex(3)* + +# ERRORS + +See *libssh2_channel_forward_listen_ex(3)* diff --git a/docs/libssh2_channel_forward_listen_ex.3 b/docs/libssh2_channel_forward_listen_ex.3 deleted file mode 100644 index c33115e6..00000000 --- a/docs/libssh2_channel_forward_listen_ex.3 +++ /dev/null @@ -1,51 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_forward_listen_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_forward_listen_ex - listen to inbound connections -.SH SYNOPSIS -.nf -#include - -LIBSSH2_LISTENER * -libssh2_channel_forward_listen_ex(LIBSSH2_SESSION *session, - char *host, int port, - int *bound_port, int queue_maxsize); - -LIBSSH2_LISTENER * -libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port); -.fi -.SH DESCRIPTION -Instruct the remote SSH server to begin listening for inbound TCP/IP -connections. New connections will be queued by the library until accepted by -\fIlibssh2_channel_forward_accept(3)\fP. - -\fIsession\fP - instance as returned by libssh2_session_init(). - -\fIhost\fP - specific address to bind to on the remote host. Binding to -0.0.0.0 (default when NULL is passed) will bind to all available addresses. - -\fIport\fP - port to bind to on the remote host. When 0 is passed, the remote -host will select the first available dynamic port. - -\fIbound_port\fP - Populated with the actual port bound on the remote -host. Useful when requesting dynamic port numbers. - -\fIqueue_maxsize\fP - Maximum number of pending connections to queue before -rejecting further attempts. - -\fIlibssh2_channel_forward_listen(3)\fP is a macro. -.SH RETURN VALUE -A newly allocated LIBSSH2_LISTENER instance or NULL on failure. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on the socket. - -\fILIBSSH2_ERROR_REQUEST_DENIED\fP - The remote server refused the request. - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. -.SH SEE ALSO -.BR libssh2_channel_forward_accept(3) diff --git a/docs/libssh2_channel_forward_listen_ex.md b/docs/libssh2_channel_forward_listen_ex.md new file mode 100644 index 00000000..8cb39ad0 --- /dev/null +++ b/docs/libssh2_channel_forward_listen_ex.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_forward_listen_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_forward_accept(3) +--- + +# NAME + +libssh2_channel_forward_listen_ex - listen to inbound connections + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_LISTENER * +libssh2_channel_forward_listen_ex(LIBSSH2_SESSION *session, + char *host, int port, + int *bound_port, int queue_maxsize); + +LIBSSH2_LISTENER * +libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port); +~~~ + +# DESCRIPTION + +Instruct the remote SSH server to begin listening for inbound TCP/IP +connections. New connections will be queued by the library until accepted by +*libssh2_channel_forward_accept(3)*. + +*session* - instance as returned by libssh2_session_init(). + +*host* - specific address to bind to on the remote host. Binding to +0.0.0.0 (default when NULL is passed) will bind to all available addresses. + +*port* - port to bind to on the remote host. When 0 is passed, the remote +host will select the first available dynamic port. + +*bound_port* - Populated with the actual port bound on the remote +host. Useful when requesting dynamic port numbers. + +*queue_maxsize* - Maximum number of pending connections to queue before +rejecting further attempts. + +*libssh2_channel_forward_listen(3)* is a macro. + +# RETURN VALUE + +A newly allocated LIBSSH2_LISTENER instance or NULL on failure. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_PROTO* - An invalid SSH protocol response was received on the socket. + +*LIBSSH2_ERROR_REQUEST_DENIED* - The remote server refused the request. + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would block. diff --git a/docs/libssh2_channel_free.3 b/docs/libssh2_channel_free.3 deleted file mode 100644 index 66fddc06..00000000 --- a/docs/libssh2_channel_free.3 +++ /dev/null @@ -1,26 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_free 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_free - free all resources associated with a channel -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_free(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -\fIchannel\fP - Channel stream to free. - -Release all resources associated with a channel stream. If the channel has -not yet been closed with -.BR libssh2_channel_close(3) -, it will be called automatically so that the remote end may know that it -can safely free its own resources. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH SEE ALSO -.BR libssh2_channel_close(3) diff --git a/docs/libssh2_channel_free.md b/docs/libssh2_channel_free.md new file mode 100644 index 00000000..d0530802 --- /dev/null +++ b/docs/libssh2_channel_free.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_free +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_close(3) +--- + +# NAME + +libssh2_channel_free - free all resources associated with a channel + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_free(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +*channel* - Channel stream to free. + +Release all resources associated with a channel stream. If the channel has +not yet been closed with libssh2_channel_close(3) it will be called +automatically so that the remote end may know that it can safely free its +own resources. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. diff --git a/docs/libssh2_channel_get_exit_signal.3 b/docs/libssh2_channel_get_exit_signal.md similarity index 52% rename from docs/libssh2_channel_get_exit_signal.3 rename to docs/libssh2_channel_get_exit_signal.md index e1ce01fd..35643c3d 100644 --- a/docs/libssh2_channel_get_exit_signal.3 +++ b/docs/libssh2_channel_get_exit_signal.md @@ -1,10 +1,19 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_get_exit_signal 3 "4 Oct 2010" "libssh2 1.2.8" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_get_exit_signal +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_channel_get_exit_signal - get the remote exit signal -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -12,28 +21,32 @@ libssh2_channel_get_exit_signal(LIBSSH2_CHANNEL *channel, char **exitsignal, size_t *exitsignal_len, char **errmsg, size_t *errmsg_len, char **langtag, size_t *langtag_len); -.fi -.SH DESCRIPTION -\fIchannel\fP - Closed channel stream to retrieve exit signal from. +~~~ -\fIexitsignal\fP - If not NULL, is populated by reference with the exit signal +# DESCRIPTION + +*channel* - Closed channel stream to retrieve exit signal from. + +*exitsignal* - If not NULL, is populated by reference with the exit signal (without leading "SIG"). Note that the string is stored in a newly allocated buffer. If the remote program exited cleanly, the referenced string pointer will be set to NULL. -\fIexitsignal_len\fP - If not NULL, is populated by reference with the length +*exitsignal_len* - If not NULL, is populated by reference with the length of exitsignal. -\fIerrmsg\fP - If not NULL, is populated by reference with the error message +*errmsg* - If not NULL, is populated by reference with the error message (if provided by remote server, if not it will be set to NULL). Note that the string is stored in a newly allocated buffer. -\fIerrmsg_len\fP - If not NULL, is populated by reference with the length of errmsg. +*errmsg_len* - If not NULL, is populated by reference with the length of errmsg. -\fIlangtag\fP - If not NULL, is populated by reference with the language tag +*langtag* - If not NULL, is populated by reference with the language tag (if provided by remote server, if not it will be set to NULL). Note that the string is stored in a newly allocated buffer. -\fIlangtag_len\fP - If not NULL, is populated by reference with the length of langtag. -.SH RETURN VALUE +*langtag_len* - If not NULL, is populated by reference with the length of langtag. + +# RETURN VALUE + Numeric error code corresponding to the the Error Code constants. diff --git a/docs/libssh2_channel_get_exit_status.3 b/docs/libssh2_channel_get_exit_status.3 deleted file mode 100644 index 7171b657..00000000 --- a/docs/libssh2_channel_get_exit_status.3 +++ /dev/null @@ -1,20 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_get_exit_status 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_get_exit_status - get the remote exit code -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_get_exit_status(LIBSSH2_CHANNEL* channel) -.fi -.SH DESCRIPTION -\fIchannel\fP - Closed channel stream to retrieve exit status from. - -Returns the exit code raised by the process running on the remote host at -the other end of the named channel. Note that the exit status may not be -available if the remote end has not yet set its status to closed. -.SH RETURN VALUE -Returns 0 on failure, otherwise the \fIExit Status\fP reported by remote host diff --git a/docs/libssh2_channel_get_exit_status.md b/docs/libssh2_channel_get_exit_status.md new file mode 100644 index 00000000..35cc338f --- /dev/null +++ b/docs/libssh2_channel_get_exit_status.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_get_exit_status +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_channel_get_exit_status - get the remote exit code + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_get_exit_status(LIBSSH2_CHANNEL* channel) +~~~ + +# DESCRIPTION + +*channel* - Closed channel stream to retrieve exit status from. + +Returns the exit code raised by the process running on the remote host at +the other end of the named channel. Note that the exit status may not be +available if the remote end has not yet set its status to closed. + +# RETURN VALUE + +Returns 0 on failure, otherwise the *Exit Status* reported by remote host diff --git a/docs/libssh2_channel_handle_extended_data.3 b/docs/libssh2_channel_handle_extended_data.3 deleted file mode 100644 index ff494383..00000000 --- a/docs/libssh2_channel_handle_extended_data.3 +++ /dev/null @@ -1,39 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_handle_extended_data 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_handle_extended_data - set extended data handling mode -.SH SYNOPSIS -.nf -#include - -void -libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel, - int ignore_mode); -.fi -.SH DESCRIPTION -This function is \fBDEPRECATED\fP in 1.1.0. Use the -\fIlibssh2_channel_handle_extended_data2(3)\fP function instead! - -\fIchannel\fP - Active channel stream to change extended data handling on. - -\fIignore_mode\fP - One of the three LIBSSH2_CHANNEL_EXTENDED_DATA_* Constants. -.br -\fBLIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL\fP: Queue extended data for eventual -reading -.br -\fBLIBSSH2_CHANNEL_EXTENDED_DATA_MERGE\fP: Treat extended data and ordinary -data the same. Merge all substreams such that calls to -\fIlibssh2_channel_read(3)\fP will pull from all substreams on a -first-in/first-out basis. -.br -\fBLIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE\fP: Discard all extended data as it -arrives. - -Change how a channel deals with extended data packets. By default all extended -data is queued until read by \fIlibssh2_channel_read_ex(3)\fP -.SH RETURN VALUE -None. -.SH SEE ALSO -.BR libssh2_channel_handle_extended_data2(3) -.BR libssh2_channel_read_ex(3) diff --git a/docs/libssh2_channel_handle_extended_data.md b/docs/libssh2_channel_handle_extended_data.md new file mode 100644 index 00000000..0562cc70 --- /dev/null +++ b/docs/libssh2_channel_handle_extended_data.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_handle_extended_data +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_handle_extended_data2(3) + - libssh2_channel_read_ex(3) +--- + +# NAME + +libssh2_channel_handle_extended_data - set extended data handling mode + +# SYNOPSIS + +~~~c +#include + +void +libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel, + int ignore_mode); +~~~ + +# DESCRIPTION + +This function is **DEPRECATED** in 1.1.0. Use the +*libssh2_channel_handle_extended_data2(3)* function instead! + +*channel* - Active channel stream to change extended data handling on. + +*ignore_mode* - One of the three LIBSSH2_CHANNEL_EXTENDED_DATA_* Constants. + +**LIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL**: Queue extended data for eventual +reading + +**LIBSSH2_CHANNEL_EXTENDED_DATA_MERGE**: Treat extended data and ordinary +data the same. Merge all substreams such that calls to +*libssh2_channel_read(3)* will pull from all substreams on a +first-in/first-out basis. + +**LIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE**: Discard all extended data as it +arrives. + +Change how a channel deals with extended data packets. By default all extended +data is queued until read by *libssh2_channel_read_ex(3)* + +# RETURN VALUE + +None. diff --git a/docs/libssh2_channel_handle_extended_data2.3 b/docs/libssh2_channel_handle_extended_data2.3 deleted file mode 100644 index ac970fcb..00000000 --- a/docs/libssh2_channel_handle_extended_data2.3 +++ /dev/null @@ -1,37 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_handle_extended_data2 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_handle_extended_data2 - set extended data handling mode -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel, - int ignore_mode); -.fi -.SH DESCRIPTION -\fIchannel\fP - Active channel stream to change extended data handling on. - -\fIignore_mode\fP - One of the three LIBSSH2_CHANNEL_EXTENDED_DATA_* Constants. -.br -\fBLIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL\fP: Queue extended data for eventual -reading -.br -\fBLIBSSH2_CHANNEL_EXTENDED_DATA_MERGE\fP: Treat extended data and ordinary -data the same. Merge all substreams such that calls to -.BR libssh2_channel_read(3) -will pull from all substreams on a first-in/first-out basis. -.br -\fBLIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE\fP: Discard all extended data as it -arrives. - -Change how a channel deals with extended data packets. By default all -extended data is queued until read by -.BR libssh2_channel_read_ex(3) -.SH RETURN VALUE -Return 0 on success or LIBSSH2_ERROR_EAGAIN when it would otherwise block. -.SH SEE ALSO -.BR libssh2_channel_handle_extended_data(3) -.BR libssh2_channel_read_ex(3) diff --git a/docs/libssh2_channel_handle_extended_data2.md b/docs/libssh2_channel_handle_extended_data2.md new file mode 100644 index 00000000..0018257b --- /dev/null +++ b/docs/libssh2_channel_handle_extended_data2.md @@ -0,0 +1,48 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_handle_extended_data2 +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_handle_extended_data(3) + - libssh2_channel_read(3) + - libssh2_channel_read_ex(3) +--- + +# NAME + +libssh2_channel_handle_extended_data2 - set extended data handling mode + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel, + int ignore_mode); +~~~ + +# DESCRIPTION + +*channel* - Active channel stream to change extended data handling on. + +*ignore_mode* - One of the three LIBSSH2_CHANNEL_EXTENDED_DATA_* Constants. + +**LIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL**: Queue extended data for eventual +reading + +**LIBSSH2_CHANNEL_EXTENDED_DATA_MERGE**: Treat extended data and ordinary +data the same. Merge all substreams such that calls to libssh2_channel_read(3) +will pull from all substreams on a first-in/first-out basis. + +**LIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE**: Discard all extended data as it +arrives. + +Change how a channel deals with extended data packets. By default all +extended data is queued until read by libssh2_channel_read_ex(3). + +# RETURN VALUE + +Return 0 on success or LIBSSH2_ERROR_EAGAIN when it would otherwise block. diff --git a/docs/libssh2_channel_ignore_extended_data.3 b/docs/libssh2_channel_ignore_extended_data.3 deleted file mode 100644 index ff8f4900..00000000 --- a/docs/libssh2_channel_ignore_extended_data.3 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_ignore_extended_data 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_ignore_extended_data - convenience macro for \fIlibssh2_channel_handle_extended_data(3)\fP calls -.SH SYNOPSIS -.nf -#include - -void -libssh2_channel_ignore_extended_data(LIBSSH2_CHANNEL *channel, - int ignore_mode); -.fi -.SH DESCRIPTION -This function is \fBDEPRECATED\fP in 0.3.0. Use the -\fIlibssh2_channel_handle_extended_data2(3)\fP function instead! - -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_handle_extended_data(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_handle_extended_data(3)\fP -.SH ERRORS -See \fIlibssh2_channel_handle_extended_data(3)\fP -.SH SEE ALSO -.BR libssh2_channel_handle_extended_data(3) diff --git a/docs/libssh2_channel_ignore_extended_data.md b/docs/libssh2_channel_ignore_extended_data.md new file mode 100644 index 00000000..9be14ea5 --- /dev/null +++ b/docs/libssh2_channel_ignore_extended_data.md @@ -0,0 +1,39 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_ignore_extended_data +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_handle_extended_data(3) +--- + +# NAME + +libssh2_channel_ignore_extended_data - convenience macro for *libssh2_channel_handle_extended_data(3)* calls + +# SYNOPSIS + +~~~c +#include + +void +libssh2_channel_ignore_extended_data(LIBSSH2_CHANNEL *channel, + int ignore_mode); +~~~ + +# DESCRIPTION + +This function is **DEPRECATED** in 0.3.0. Use the +*libssh2_channel_handle_extended_data2(3)* function instead! + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_handle_extended_data(3)*. + +# RETURN VALUE + +See *libssh2_channel_handle_extended_data(3)* + +# ERRORS + +See *libssh2_channel_handle_extended_data(3)* diff --git a/docs/libssh2_channel_open_ex.3 b/docs/libssh2_channel_open_ex.3 deleted file mode 100644 index 66fd8022..00000000 --- a/docs/libssh2_channel_open_ex.3 +++ /dev/null @@ -1,58 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_open_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_open_ex - establish a generic session channel -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_channel_open_ex(LIBSSH2_SESSION *session, const char *channel_type, - unsigned int channel_type_len, - unsigned int window_size, - unsigned int packet_size, - const char *message, unsigned int message_len); - -LIBSSH2_CHANNEL * -libssh2_channel_open_session(session); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIchannel_type\fP - Channel type to open. Typically one of session, -direct-tcpip, or tcpip-forward. The SSH2 protocol allowed for additional -types including local, custom channel types. - -\fIchannel_type_len\fP - Length of channel_type - -\fIwindow_size\fP - Maximum amount of unacknowledged data remote host is -allowed to send before receiving an SSH_MSG_CHANNEL_WINDOW_ADJUST packet. - -\fIpacket_size\fP - Maximum number of bytes remote host is allowed to send -in a single SSH_MSG_CHANNEL_DATA or SSG_MSG_CHANNEL_EXTENDED_DATA packet. - -\fImessage\fP - Additional data as required by the selected channel_type. - -\fImessage_len\fP - Length of message parameter. - -Allocate a new channel for exchanging data with the server. This method is -typically called through its macroized form: -.BR libssh2_channel_open_session(3) -or via -.BR libssh2_channel_direct_tcpip(3) -or -.BR libssh2_channel_forward_listen(3) -.SH RETURN VALUE -Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_CHANNEL_FAILURE\fP - - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. -.SH SEE ALSO -Add related functions diff --git a/docs/libssh2_channel_open_ex.md b/docs/libssh2_channel_open_ex.md new file mode 100644 index 00000000..302832df --- /dev/null +++ b/docs/libssh2_channel_open_ex.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_open_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_direct_tcpip(3) + - libssh2_channel_forward_listen(3) + - libssh2_channel_open_session(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_channel_open_ex - establish a generic session channel + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_channel_open_ex(LIBSSH2_SESSION *session, const char *channel_type, + unsigned int channel_type_len, + unsigned int window_size, + unsigned int packet_size, + const char *message, unsigned int message_len); + +LIBSSH2_CHANNEL * +libssh2_channel_open_session(session); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*channel_type* - Channel type to open. Typically one of session, +direct-tcpip, or tcpip-forward. The SSH2 protocol allowed for additional +types including local, custom channel types. + +*channel_type_len* - Length of channel_type + +*window_size* - Maximum amount of unacknowledged data remote host is +allowed to send before receiving an SSH_MSG_CHANNEL_WINDOW_ADJUST packet. + +*packet_size* - Maximum number of bytes remote host is allowed to send +in a single SSH_MSG_CHANNEL_DATA or SSG_MSG_CHANNEL_EXTENDED_DATA packet. + +*message* - Additional data as required by the selected channel_type. + +*message_len* - Length of message parameter. + +Allocate a new channel for exchanging data with the server. This method is +typically called through its macroized form: +*libssh2_channel_open_session(3)* or via *libssh2_channel_direct_tcpip(3)* +or *libssh2_channel_forward_listen(3)* + +# RETURN VALUE + +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_FAILURE* - + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would block. +Add related functions diff --git a/docs/libssh2_channel_open_session.3 b/docs/libssh2_channel_open_session.3 deleted file mode 100644 index 89039ea3..00000000 --- a/docs/libssh2_channel_open_session.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_open_session 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_open_session - convenience macro for \fIlibssh2_channel_open_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_channel_open_session(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_open_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_open_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_open_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_channel_open_session.md b/docs/libssh2_channel_open_session.md new file mode 100644 index 00000000..bf0636c7 --- /dev/null +++ b/docs/libssh2_channel_open_session.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_open_session +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) +--- + +# NAME + +libssh2_channel_open_session - convenience macro for *libssh2_channel_open_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_channel_open_session(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_open_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_open_ex(3)* + +# ERRORS + +See *libssh2_channel_open_ex(3)* diff --git a/docs/libssh2_channel_process_startup.3 b/docs/libssh2_channel_process_startup.3 deleted file mode 100644 index 5f827db1..00000000 --- a/docs/libssh2_channel_process_startup.3 +++ /dev/null @@ -1,42 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_process_startup 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_process_startup - request a shell on a channel -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_process_startup(LIBSSH2_CHANNEL *channel, - const char *request, - unsigned int request_len, - const char *message, - unsigned int message_len); -.fi -.SH DESCRIPTION -\fIchannel\fP - Active session channel instance. - -\fIrequest\fP - Type of process to startup. The SSH2 protocol currently -defines shell, exec, and subsystem as standard process services. - -\fIrequest_len\fP - Length of request parameter. - -\fImessage\fP - Request specific message data to include. - -\fImessage_len\fP - Length of message parameter. - -Initiate a request on a session type channel such as returned by -.BR libssh2_channel_open_ex(3) -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_channel_process_startup.md b/docs/libssh2_channel_process_startup.md new file mode 100644 index 00000000..fbb8ea10 --- /dev/null +++ b/docs/libssh2_channel_process_startup.md @@ -0,0 +1,56 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_process_startup +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) +--- + +# NAME + +libssh2_channel_process_startup - request a shell on a channel + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_process_startup(LIBSSH2_CHANNEL *channel, + const char *request, + unsigned int request_len, + const char *message, + unsigned int message_len); +~~~ + +# DESCRIPTION + +*channel* - Active session channel instance. + +*request* - Type of process to startup. The SSH2 protocol currently +defines shell, exec, and subsystem as standard process services. + +*request_len* - Length of request parameter. + +*message* - Request specific message data to include. + +*message_len* - Length of message parameter. + +Initiate a request on a session type channel such as returned by +libssh2_channel_open_ex(3). + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_REQUEST_DENIED* - diff --git a/docs/libssh2_channel_read.3 b/docs/libssh2_channel_read.3 deleted file mode 100644 index 0644e185..00000000 --- a/docs/libssh2_channel_read.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_read 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_read - convenience macro for \fIlibssh2_channel_read_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -ssize_t -libssh2_channel_read(LIBSSH2_CHANNEL *channel, - char *buf, size_t buflen); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_read_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_read_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_read_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_read_ex(3) diff --git a/docs/libssh2_channel_read.md b/docs/libssh2_channel_read.md new file mode 100644 index 00000000..455a69df --- /dev/null +++ b/docs/libssh2_channel_read.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_read +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_read_ex(3) +--- + +# NAME + +libssh2_channel_read - convenience macro for *libssh2_channel_read_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +ssize_t +libssh2_channel_read(LIBSSH2_CHANNEL *channel, + char *buf, size_t buflen); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_read_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_read_ex(3)* + +# ERRORS + +See *libssh2_channel_read_ex(3)* diff --git a/docs/libssh2_channel_read_ex.3 b/docs/libssh2_channel_read_ex.md similarity index 55% rename from docs/libssh2_channel_read_ex.3 rename to docs/libssh2_channel_read_ex.md index 200fe800..3ef73fcb 100644 --- a/docs/libssh2_channel_read_ex.3 +++ b/docs/libssh2_channel_read_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_read_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_read_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_poll_channel_read(3) +--- + +# NAME + libssh2_channel_read_ex - read data from a channel stream -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include ssize_t @@ -18,33 +28,37 @@ libssh2_channel_read(LIBSSH2_CHANNEL *channel, ssize_t libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Attempt to read data from an active channel stream. All channel streams have one standard I/O substream (stream_id == 0), and may have up to 2^32 extended -data streams as identified by the selected \fIstream_id\fP. The SSH2 protocol +data streams as identified by the selected *stream_id*. The SSH2 protocol currently defines a stream ID of 1 to be the stderr substream. -\fIchannel\fP - active channel stream to read from. +*channel* - active channel stream to read from. -\fIstream_id\fP - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) +*stream_id* - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) -\fIbuf\fP - pointer to storage buffer to read data into +*buf* - pointer to storage buffer to read data into -\fIbuflen\fP - size of the buf storage +*buflen* - size of the buf storage -\fIlibssh2_channel_read(3)\fP and \fIlibssh2_channel_read_stderr(3)\fP are +*libssh2_channel_read(3)* and *libssh2_channel_read_stderr(3)* are macros. -.SH RETURN VALUE + +# RETURN VALUE + Actual number of bytes read or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. Note that a return value of zero (0) can in fact be a legitimate value and only signals that no payload data was read. It is not an error. -.SH ERRORS -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. -\fILIBSSH2_ERROR_CHANNEL_CLOSED\fP - The channel has been closed. -.SH SEE ALSO -.BR libssh2_poll_channel_read(3) +# ERRORS + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_CLOSED* - The channel has been closed. diff --git a/docs/libssh2_channel_read_stderr.3 b/docs/libssh2_channel_read_stderr.3 deleted file mode 100644 index 25b5ba72..00000000 --- a/docs/libssh2_channel_read_stderr.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_read_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_read_stderr - convenience macro for \fIlibssh2_channel_read_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -ssize_t -libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, - char *buf, size_t buflen); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_read_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_read_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_read_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_read_ex(3) diff --git a/docs/libssh2_channel_read_stderr.md b/docs/libssh2_channel_read_stderr.md new file mode 100644 index 00000000..37ec2660 --- /dev/null +++ b/docs/libssh2_channel_read_stderr.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_read_stderr +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_read_ex(3) +--- + +# NAME + +libssh2_channel_read_stderr - convenience macro for *libssh2_channel_read_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +ssize_t +libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, + char *buf, size_t buflen); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_read_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_read_ex(3)* + +# ERRORS + +See *libssh2_channel_read_ex(3)* diff --git a/docs/libssh2_channel_receive_window_adjust.3 b/docs/libssh2_channel_receive_window_adjust.md similarity index 69% rename from docs/libssh2_channel_receive_window_adjust.3 rename to docs/libssh2_channel_receive_window_adjust.md index af0df2e2..26fd464b 100644 --- a/docs/libssh2_channel_receive_window_adjust.3 +++ b/docs/libssh2_channel_receive_window_adjust.md @@ -1,32 +1,46 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_receive_window_adjust 3 "15 Mar 2009" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_receive_window_adjust +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_window_read_ex(3) +--- + +# NAME + libssh2_channel_receive_window_adjust - adjust the channel window -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include unsigned long libssh2_channel_receive_window_adjust(LIBSSH2_CHANNEL * channel, unsigned long adjustment, unsigned char force); -.fi -.SH DESCRIPTION -This function is \fBDEPRECATED\fP in 1.1.0. Use the -\fIlibssh2_channel_receive_window_adjust2(3)\fP function instead! +~~~ + +# DESCRIPTION + +This function is **DEPRECATED** in 1.1.0. Use the +*libssh2_channel_receive_window_adjust2(3)* function instead! Adjust the receive window for a channel by adjustment bytes. If the amount to be adjusted is less than LIBSSH2_CHANNEL_MINADJUST and force is 0 the adjustment amount will be queued for a later packet. -.SH RETURN VALUE + +# RETURN VALUE + Returns the new size of the receive window (as understood by remote end). Note that the window value sent over the wire is strictly 32bit, but this API is made to return a 'long' which may not be 32 bit on all platforms. -.SH ERRORS + +# ERRORS + In 1.0 and earlier, this function returns LIBSSH2_ERROR_EAGAIN for non-blocking channels where it would otherwise block. However, that is a negative number and this function only returns an unsigned value and this then leads to a very strange value being returned. -.SH SEE ALSO -.BR libssh2_channel_window_read_ex(3) diff --git a/docs/libssh2_channel_receive_window_adjust2.3 b/docs/libssh2_channel_receive_window_adjust2.md similarity index 72% rename from docs/libssh2_channel_receive_window_adjust2.3 rename to docs/libssh2_channel_receive_window_adjust2.md index 730889af..117e2baa 100644 --- a/docs/libssh2_channel_receive_window_adjust2.3 +++ b/docs/libssh2_channel_receive_window_adjust2.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_receive_window_adjust2 3 "26 Mar 2009" "libssh2 1.1" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_receive_window_adjust2 +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_window_read_ex(3) +--- + +# NAME + libssh2_channel_receive_window_adjust2 - adjust the channel window -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -12,19 +22,24 @@ libssh2_channel_receive_window_adjust2(LIBSSH2_CHANNEL * channel, unsigned long adjustment, unsigned char force, unsigned int *window); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Adjust the receive window for a channel by adjustment bytes. If the amount to be adjusted is less than LIBSSH2_CHANNEL_MINADJUST and force is 0 the adjustment amount will be queued for a later packet. This function stores the new size of the receive window (as understood by remote end) in the variable 'window' points to. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success and a negative value on error. If used in non-blocking mode it will return LIBSSH2_ERROR_EAGAIN when it would otherwise block. -.SH ERRORS -.SH AVAILABILITY + +# ERRORS + +# AVAILABILITY + Added in libssh2 1.1 since the previous API has deficiencies. -.SH SEE ALSO -.BR libssh2_channel_window_read_ex(3) diff --git a/docs/libssh2_channel_request_auth_agent.3 b/docs/libssh2_channel_request_auth_agent.md similarity index 57% rename from docs/libssh2_channel_request_auth_agent.3 rename to docs/libssh2_channel_request_auth_agent.md index 4da47bab..826acda4 100644 --- a/docs/libssh2_channel_request_auth_agent.3 +++ b/docs/libssh2_channel_request_auth_agent.md @@ -1,33 +1,44 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_request_auth_agent 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_request_auth_agent +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_session_callback_set2(3) +--- + +# NAME + libssh2_channel_request_auth_agent - request agent forwarding for a session -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_channel_request_auth_agent(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Request that agent forwarding be enabled for this SSH session. This sends the request over this specific channel, which causes the agent listener to be started on the remote side upon success. This agent listener will then run for the duration of the SSH session. -To use agent forwarding, -.BR libssh2_session_callback_set2(3) -must first be called to set \fBLIBSSH2_CALLBACK_AUTHAGENT\fP. +To use agent forwarding, libssh2_session_callback_set2(3) +must first be called to set **LIBSSH2_CALLBACK_AUTHAGENT**. This callback will be invoked when the remote host opens a connection to the local agent. -\fIchannel\fP - Previously opened channel instance such as returned by -.BR libssh2_channel_open_ex(3) -.SH RETURN VALUE +*channel* - Previously opened channel instance such as returned by +libssh2_channel_open_ex(3) + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. - -.SH SEE ALSO -.BR libssh2_session_callback_set2(3) diff --git a/docs/libssh2_channel_request_pty.3 b/docs/libssh2_channel_request_pty.3 deleted file mode 100644 index 7a3b75ea..00000000 --- a/docs/libssh2_channel_request_pty.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_request_pty 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_request_pty - convenience macro for \fIlibssh2_channel_request_pty_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_request_pty(LIBSSH2_SESSION *session, const char *term); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_request_pty_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_request_pty_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_request_pty_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_request_pty_ex(3) diff --git a/docs/libssh2_channel_request_pty.md b/docs/libssh2_channel_request_pty.md new file mode 100644 index 00000000..e96f4ead --- /dev/null +++ b/docs/libssh2_channel_request_pty.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_request_pty +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_request_pty_ex(3) +--- + +# NAME + +libssh2_channel_request_pty - convenience macro for *libssh2_channel_request_pty_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_request_pty(LIBSSH2_SESSION *session, const char *term); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_request_pty_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_request_pty_ex(3)* + +# ERRORS + +See *libssh2_channel_request_pty_ex(3)* diff --git a/docs/libssh2_channel_request_pty_ex.3 b/docs/libssh2_channel_request_pty_ex.3 deleted file mode 100644 index 30ad750c..00000000 --- a/docs/libssh2_channel_request_pty_ex.3 +++ /dev/null @@ -1,54 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_request_pty_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_request_pty_ex - short function description -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_request_pty_ex(LIBSSH2_CHANNEL *channel, const char *term, - unsigned int term_len, - const char *modes, unsigned int modes_len, - int width, int height, - int width_px, int height_px); - -int -libssh2_channel_request_pty(LIBSSH2_CHANNEL *channel, const char *term); -.fi -.SH DESCRIPTION -\fIchannel\fP - Previously opened channel instance such as returned by -.BR libssh2_channel_open_ex(3) - -\fIterm\fP - Terminal emulation (e.g. vt102, ansi, etc...) - -\fIterm_len\fP - Length of term parameter - -\fImodes\fP - Terminal mode modifier values - -\fImodes_len\fP - Length of modes parameter. - -\fIwidth\fP - Width of pty in characters - -\fIheight\fP - Height of pty in characters - -\fIwidth_px\fP - Width of pty in pixels - -\fIheight_px\fP - Height of pty in pixels - -Request a PTY on an established channel. Note that this does not make sense -for all channel types and may be ignored by the server despite returning -success. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_channel_request_pty_ex.md b/docs/libssh2_channel_request_pty_ex.md new file mode 100644 index 00000000..0113458a --- /dev/null +++ b/docs/libssh2_channel_request_pty_ex.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_request_pty_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) +--- + +# NAME + +libssh2_channel_request_pty_ex - short function description + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_request_pty_ex(LIBSSH2_CHANNEL *channel, const char *term, + unsigned int term_len, + const char *modes, unsigned int modes_len, + int width, int height, + int width_px, int height_px); + +int +libssh2_channel_request_pty(LIBSSH2_CHANNEL *channel, const char *term); +~~~ + +# DESCRIPTION + +*channel* - Previously opened channel instance such as returned by +libssh2_channel_open_ex(3) + +*term* - Terminal emulation (e.g. vt102, ansi, etc...) + +*term_len* - Length of term parameter + +*modes* - Terminal mode modifier values + +*modes_len* - Length of modes parameter. + +*width* - Width of pty in characters + +*height* - Height of pty in characters + +*width_px* - Width of pty in pixels + +*height_px* - Height of pty in pixels + +Request a PTY on an established channel. Note that this does not make sense +for all channel types and may be ignored by the server despite returning +success. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_REQUEST_DENIED* - diff --git a/docs/libssh2_channel_request_pty_size.3 b/docs/libssh2_channel_request_pty_size.3 deleted file mode 100644 index 7de31d61..00000000 --- a/docs/libssh2_channel_request_pty_size.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_request_pty_size 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_request_pty_size - convenience macro for \fIlibssh2_channel_request_pty_size_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_request_pty_size(LIBSSH2_CHANNEL *channel, - int width, int height); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_request_pty_size_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_request_pty_size_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_request_pty_size_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_request_pty_size_ex(3) diff --git a/docs/libssh2_channel_request_pty_size.md b/docs/libssh2_channel_request_pty_size.md new file mode 100644 index 00000000..1e092e8d --- /dev/null +++ b/docs/libssh2_channel_request_pty_size.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_request_pty_size +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_request_pty_size_ex(3) +--- + +# NAME + +libssh2_channel_request_pty_size - convenience macro for *libssh2_channel_request_pty_size_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_request_pty_size(LIBSSH2_CHANNEL *channel, + int width, int height); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_request_pty_size_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_request_pty_size_ex(3)* + +# ERRORS + +See *libssh2_channel_request_pty_size_ex(3)* diff --git a/docs/libssh2_channel_request_pty_size_ex.3 b/docs/libssh2_channel_request_pty_size_ex.3 deleted file mode 100644 index 54daf4f5..00000000 --- a/docs/libssh2_channel_request_pty_size_ex.3 +++ /dev/null @@ -1,12 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_request_pty_size_ex 3 "1 Jun 2007" "libssh2" "libssh2" -.SH NAME -libssh2_channel_request_pty_size_ex - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH SEE ALSO diff --git a/docs/libssh2_channel_request_pty_size_ex.md b/docs/libssh2_channel_request_pty_size_ex.md new file mode 100644 index 00000000..67ff8976 --- /dev/null +++ b/docs/libssh2_channel_request_pty_size_ex.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_request_pty_size_ex +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_channel_request_pty_size_ex - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS diff --git a/docs/libssh2_channel_send_eof.3 b/docs/libssh2_channel_send_eof.md similarity index 55% rename from docs/libssh2_channel_send_eof.3 rename to docs/libssh2_channel_send_eof.md index d4bf52e5..db8f409e 100644 --- a/docs/libssh2_channel_send_eof.3 +++ b/docs/libssh2_channel_send_eof.md @@ -1,24 +1,38 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_send_eof 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_send_eof +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_eof(3) + - libssh2_channel_wait_eof(3) +--- + +# NAME + libssh2_channel_send_eof - send EOF to remote server -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_channel_send_eof(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Tell the remote host that no further data will be sent on the specified channel. Processes typically interpret this as a closed stdin descriptor. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. -.SH SEE ALSO -.BR libssh2_channel_wait_eof(3) -.BR libssh2_channel_eof(3) + +# ERRORS + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. diff --git a/docs/libssh2_channel_set_blocking.3 b/docs/libssh2_channel_set_blocking.3 deleted file mode 100644 index 07a1049a..00000000 --- a/docs/libssh2_channel_set_blocking.3 +++ /dev/null @@ -1,27 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_set_blocking 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_set_blocking - set or clear blocking mode on channel -.SH SYNOPSIS -.nf -#include - -void -libssh2_channel_set_blocking(LIBSSH2_CHANNEL *channel, int blocking); -.fi -.SH DESCRIPTION -\fIchannel\fP - channel stream to set or clean blocking status on. - -\fIblocking\fP - Set to a non-zero value to make the channel block, or zero to -make it non-blocking. - -Currently this is a short cut call to -.BR libssh2_session_set_blocking(3) -and therefore will affect the session and all channels. -.SH RETURN VALUE -None -.SH SEE ALSO -.BR libssh2_session_set_blocking(3) -.BR libssh2_channel_read_ex(3) -.BR libssh2_channel_write_ex(3) diff --git a/docs/libssh2_channel_set_blocking.md b/docs/libssh2_channel_set_blocking.md new file mode 100644 index 00000000..05bf1286 --- /dev/null +++ b/docs/libssh2_channel_set_blocking.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_set_blocking +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_read_ex(3) + - libssh2_channel_write_ex(3) + - libssh2_session_set_blocking(3) +--- + +# NAME + +libssh2_channel_set_blocking - set or clear blocking mode on channel + +# SYNOPSIS + +~~~c +#include + +void +libssh2_channel_set_blocking(LIBSSH2_CHANNEL *channel, int blocking); +~~~ + +# DESCRIPTION + +*channel* - channel stream to set or clean blocking status on. + +*blocking* - Set to a non-zero value to make the channel block, or zero to +make it non-blocking. + +Currently this is a short cut call to libssh2_session_set_blocking(3) +and therefore will affect the session and all channels. + +# RETURN VALUE + +None diff --git a/docs/libssh2_channel_setenv.3 b/docs/libssh2_channel_setenv.3 deleted file mode 100644 index 0fa097b5..00000000 --- a/docs/libssh2_channel_setenv.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_setenv 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_setenv - convenience macro for \fIlibssh2_channel_setenv_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_setenv(LIBSSH2_CHANNEL *channel, - const char *varname, const char *value); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_setenv_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_setenv_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_setenv_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_setenv_ex(3) diff --git a/docs/libssh2_channel_setenv.md b/docs/libssh2_channel_setenv.md new file mode 100644 index 00000000..c72a0a59 --- /dev/null +++ b/docs/libssh2_channel_setenv.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_setenv +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_setenv_ex(3) +--- + +# NAME + +libssh2_channel_setenv - convenience macro for *libssh2_channel_setenv_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_setenv(LIBSSH2_CHANNEL *channel, + const char *varname, const char *value); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_setenv_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_setenv_ex(3)* + +# ERRORS + +See *libssh2_channel_setenv_ex(3)* diff --git a/docs/libssh2_channel_setenv_ex.3 b/docs/libssh2_channel_setenv_ex.md similarity index 50% rename from docs/libssh2_channel_setenv_ex.3 rename to docs/libssh2_channel_setenv_ex.md index 692d9f8e..4c9c9471 100644 --- a/docs/libssh2_channel_setenv_ex.3 +++ b/docs/libssh2_channel_setenv_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_setenv_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_setenv_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) +--- + +# NAME + libssh2_channel_setenv_ex - set an environment variable on the channel -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -15,33 +25,36 @@ libssh2_channel_setenv_ex(LIBSSH2_CHANNEL *channel, int libssh2_channel_setenv(LIBSSH2_CHANNEL *channel, char *varname, const char *value); -.fi -.SH DESCRIPTION -\fIchannel\fP - Previously opened channel instance such as returned by -.BR libssh2_channel_open_ex(3) +~~~ -\fIvarname\fP - Name of environment variable to set on the remote +# DESCRIPTION + +*channel* - Previously opened channel instance such as returned by +libssh2_channel_open_ex(3) + +*varname* - Name of environment variable to set on the remote channel instance. -\fIvarname_len\fP - Length of passed varname parameter. +*varname_len* - Length of passed varname parameter. -\fIvalue\fP - Value to set varname to. +*value* - Value to set varname to. -\fIvalue_len\fP - Length of value parameter. +*value_len* - Length of value parameter. Set an environment variable in the remote channel's process space. Note that this does not make sense for all channel types and may be ignored by the server despite returning success. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_REQUEST_DENIED* - diff --git a/docs/libssh2_channel_shell.3 b/docs/libssh2_channel_shell.3 deleted file mode 100644 index 70ba6d45..00000000 --- a/docs/libssh2_channel_shell.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_shell 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_shell - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_shell(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_process_startup(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_process_startup(3)\fP -.SH ERRORS -See \fIlibssh2_channel_process_startup(3)\fP -.SH SEE ALSO -.BR libssh2_channel_process_startup(3) diff --git a/docs/libssh2_channel_shell.md b/docs/libssh2_channel_shell.md new file mode 100644 index 00000000..325b16de --- /dev/null +++ b/docs/libssh2_channel_shell.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_shell +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_process_startup(3) +--- + +# NAME + +libssh2_channel_shell - convenience macro for *libssh2_channel_process_startup(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_shell(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_process_startup(3)*. + +# RETURN VALUE + +See *libssh2_channel_process_startup(3)* + +# ERRORS + +See *libssh2_channel_process_startup(3)* diff --git a/docs/libssh2_channel_signal_ex.3 b/docs/libssh2_channel_signal_ex.3 deleted file mode 100644 index aadea41b..00000000 --- a/docs/libssh2_channel_signal_ex.3 +++ /dev/null @@ -1,32 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_signal_ex 3 "20 Apr 2023" "libssh2 1.11.0" "libssh2" -.SH NAME -libssh2_channel_signal_ex -- Send a signal to process previously opened on channel. -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_signal_ex(LIBSSH2_CHANNEL *channel, - const char *signame, - size_t signame_len) -.fi -.SH DESCRIPTION -A signal can be delivered to the remote process/service. Some servers or -systems may not implement signals, in which case they will probably ignore this -message. - -\fIchannel\fP - Previously opened channel instance such as returned by -.BR libssh2_channel_open_ex(3) - -\fIsigname\fP - The signal name is the same as the signal name constant, without the leading "SIG". - -\fIsigname_len\fP - Length of passed signal name parameter. - -There is also a macro \fIlibssh2_channel_signal(channel, signame)\fP that supplies the strlen of the signame. -.SH RETURN VALUE -Normal channel error codes. -LIBSSH2_ERROR_EAGAIN when it would block. -.SH SEE ALSO -.BR libssh2_channel_get_exit_signal(3) diff --git a/docs/libssh2_channel_signal_ex.md b/docs/libssh2_channel_signal_ex.md new file mode 100644 index 00000000..1c080772 --- /dev/null +++ b/docs/libssh2_channel_signal_ex.md @@ -0,0 +1,44 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_signal_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_get_exit_signal(3) + - libssh2_channel_open_ex(3) +--- + +# NAME + +libssh2_channel_signal_ex -- Send a signal to process previously opened on channel. + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_signal_ex(LIBSSH2_CHANNEL *channel, + const char *signame, + size_t signame_len) +~~~ + +# DESCRIPTION + +A signal can be delivered to the remote process/service. Some servers or +systems may not implement signals, in which case they will probably ignore this +message. + +*channel* - Previously opened channel instance such as returned by libssh2_channel_open_ex(3). + +*signame* - The signal name is the same as the signal name constant, without the leading "SIG". + +*signame_len* - Length of passed signal name parameter. + +There is also a macro *libssh2_channel_signal(channel, signame)* that supplies the strlen of the signame. + +# RETURN VALUE + +Normal channel error codes. +LIBSSH2_ERROR_EAGAIN when it would block. diff --git a/docs/libssh2_channel_subsystem.3 b/docs/libssh2_channel_subsystem.3 deleted file mode 100644 index 31d0b333..00000000 --- a/docs/libssh2_channel_subsystem.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_subsystem 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_subsystem - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_subsystem(LIBSSH2_CHANNEL *channel, const char *subsystem); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_process_startup(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_process_startup(3)\fP -.SH ERRORS -See \fIlibssh2_channel_process_startup(3)\fP -.SH SEE ALSO -.BR libssh2_channel_process_startup(3) diff --git a/docs/libssh2_channel_subsystem.md b/docs/libssh2_channel_subsystem.md new file mode 100644 index 00000000..12ff7c86 --- /dev/null +++ b/docs/libssh2_channel_subsystem.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_subsystem +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_process_startup(3) +--- + +# NAME + +libssh2_channel_subsystem - convenience macro for *libssh2_channel_process_startup(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_subsystem(LIBSSH2_CHANNEL *channel, const char *subsystem); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_process_startup(3)*. + +# RETURN VALUE + +See *libssh2_channel_process_startup(3)* + +# ERRORS + +See *libssh2_channel_process_startup(3)* diff --git a/docs/libssh2_channel_wait_closed.3 b/docs/libssh2_channel_wait_closed.md similarity index 51% rename from docs/libssh2_channel_wait_closed.3 rename to docs/libssh2_channel_wait_closed.md index 7ef058cf..e77399b0 100644 --- a/docs/libssh2_channel_wait_closed.3 +++ b/docs/libssh2_channel_wait_closed.md @@ -1,25 +1,36 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_wait_closed 3 "29 Nov 2007" "libssh2 0.19" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_wait_closed +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_eof(3) + - libssh2_channel_send_eof(3) + - libssh2_channel_wait_eof(3) +--- + +# NAME + libssh2_channel_wait_closed - wait for the remote to close the channel -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_channel_wait_closed(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Enter a temporary blocking state until the remote host closes the named -channel. Typically sent after \fIlibssh2_channel_close(3)\fP in order to +channel. Typically sent after *libssh2_channel_close(3)* in order to examine the exit status. -.SH RETURN VALUE +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH SEE ALSO -.BR libssh2_channel_send_eof(3) -.BR libssh2_channel_eof(3) -.BR libssh2_channel_wait_eof(3) diff --git a/docs/libssh2_channel_wait_eof.3 b/docs/libssh2_channel_wait_eof.md similarity index 55% rename from docs/libssh2_channel_wait_eof.3 rename to docs/libssh2_channel_wait_eof.md index dcd1f5d5..ca4cb828 100644 --- a/docs/libssh2_channel_wait_eof.3 +++ b/docs/libssh2_channel_wait_eof.md @@ -1,22 +1,33 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_wait_eof 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_wait_eof +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_eof(3) + - libssh2_channel_send_eof(3) +--- + +# NAME + libssh2_channel_wait_eof - wait for the remote to reply to an EOF request -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_channel_wait_eof(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Wait for the remote end to send EOF. -.SH RETURN VALUE +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH SEE ALSO -.BR libssh2_channel_send_eof(3) -.BR libssh2_channel_eof(3) diff --git a/docs/libssh2_channel_window_read.3 b/docs/libssh2_channel_window_read.3 deleted file mode 100644 index f6218cb6..00000000 --- a/docs/libssh2_channel_window_read.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_window_read 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_window_read - convenience macro for \fIlibssh2_channel_window_read_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -unsigned long -libssh2_channel_window_read(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_window_read_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_window_read_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_window_read_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_window_read_ex(3) diff --git a/docs/libssh2_channel_window_read.md b/docs/libssh2_channel_window_read.md new file mode 100644 index 00000000..ecb2033c --- /dev/null +++ b/docs/libssh2_channel_window_read.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_window_read +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_window_read_ex(3) +--- + +# NAME + +libssh2_channel_window_read - convenience macro for *libssh2_channel_window_read_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +unsigned long +libssh2_channel_window_read(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_window_read_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_window_read_ex(3)* + +# ERRORS + +See *libssh2_channel_window_read_ex(3)* diff --git a/docs/libssh2_channel_window_read_ex.3 b/docs/libssh2_channel_window_read_ex.md similarity index 67% rename from docs/libssh2_channel_window_read_ex.3 rename to docs/libssh2_channel_window_read_ex.md index 3e1eebce..c6ffa4c3 100644 --- a/docs/libssh2_channel_window_read_ex.3 +++ b/docs/libssh2_channel_window_read_ex.md @@ -1,27 +1,40 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_window_read_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_window_read_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_receive_window_adjust(3) + - libssh2_channel_window_write_ex(3) +--- + +# NAME + libssh2_channel_window_read_ex - Check the status of the read window -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include unsigned long libssh2_channel_window_read_ex(LIBSSH2_CHANNEL *channel, unsigned long *read_avail, unsigned long *window_size_initial) -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Check the status of the read window. Returns the number of bytes which the remote end may send without overflowing the window limit read_avail (if passed) will be populated with the number of bytes actually available to be read window_size_initial (if passed) will be populated with the window_size_initial as defined by the channel_open request -.SH RETURN VALUE + +# RETURN VALUE + The number of bytes which the remote end may send without overflowing the window limit -.SH ERRORS -.SH SEE ALSO -.BR libssh2_channel_receive_window_adjust(3), -.BR libssh2_channel_window_write_ex(3) + +# ERRORS diff --git a/docs/libssh2_channel_window_write.3 b/docs/libssh2_channel_window_write.3 deleted file mode 100644 index aa20d02d..00000000 --- a/docs/libssh2_channel_window_write.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_window_write 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_window_write - convenience macro for \fIlibssh2_channel_window_write_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -unsigned long -libssh2_channel_window_write(LIBSSH2_CHANNEL *channel); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_window_write_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_window_write_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_window_write_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_window_write_ex(3) diff --git a/docs/libssh2_channel_window_write.md b/docs/libssh2_channel_window_write.md new file mode 100644 index 00000000..389c449d --- /dev/null +++ b/docs/libssh2_channel_window_write.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_window_write +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_window_write_ex(3) +--- + +# NAME + +libssh2_channel_window_write - convenience macro for *libssh2_channel_window_write_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +unsigned long +libssh2_channel_window_write(LIBSSH2_CHANNEL *channel); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_window_write_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_window_write_ex(3)* + +# ERRORS + +See *libssh2_channel_window_write_ex(3)* diff --git a/docs/libssh2_channel_window_write_ex.3 b/docs/libssh2_channel_window_write_ex.md similarity index 61% rename from docs/libssh2_channel_window_write_ex.3 rename to docs/libssh2_channel_window_write_ex.md index 7e8ff5fe..fd2c3ebe 100644 --- a/docs/libssh2_channel_window_write_ex.3 +++ b/docs/libssh2_channel_window_write_ex.md @@ -1,24 +1,37 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_window_write_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_window_write_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_receive_window_adjust(3) + - libssh2_channel_window_read_ex(3) +--- + +# NAME + libssh2_channel_window_write_ex - Check the status of the write window -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include unsigned long libssh2_channel_window_write_ex(LIBSSH2_CHANNEL *channel, unsigned long *window_size_initial) -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Check the status of the write window Returns the number of bytes which may be safely written on the channel without blocking. 'window_size_initial' (if passed) will be populated with the size of the initial window as defined by the channel_open request -.SH RETURN VALUE + +# RETURN VALUE + Number of bytes which may be safely written on the channel without blocking. -.SH ERRORS -.SH SEE ALSO -.BR libssh2_channel_window_read_ex(3), -.BR libssh2_channel_receive_window_adjust(3) + +# ERRORS diff --git a/docs/libssh2_channel_write.3 b/docs/libssh2_channel_write.3 deleted file mode 100644 index 6ced72d9..00000000 --- a/docs/libssh2_channel_write.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_write 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_write - convenience macro for \fIlibssh2_channel_write_ex(3)\fP -.SH SYNOPSIS -.nf -#include - -ssize_t -libssh2_channel_write(LIBSSH2_CHANNEL *channel, - const char *buf, size_t buflen); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_write_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_write_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_write_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_write_ex(3) diff --git a/docs/libssh2_channel_write.md b/docs/libssh2_channel_write.md new file mode 100644 index 00000000..3ed7b779 --- /dev/null +++ b/docs/libssh2_channel_write.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_write +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_write_ex(3) +--- + +# NAME + +libssh2_channel_write - convenience macro for *libssh2_channel_write_ex(3)* + +# SYNOPSIS + +~~~c +#include + +ssize_t +libssh2_channel_write(LIBSSH2_CHANNEL *channel, + const char *buf, size_t buflen); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_write_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_write_ex(3)* + +# ERRORS + +See *libssh2_channel_write_ex(3)* diff --git a/docs/libssh2_channel_write_ex.3 b/docs/libssh2_channel_write_ex.3 deleted file mode 100644 index 934a79c2..00000000 --- a/docs/libssh2_channel_write_ex.3 +++ /dev/null @@ -1,56 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_write_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_write_ex - write data to a channel stream blocking -.SH SYNOPSIS -.nf -#include - -ssize_t -libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, - int stream_id, char *buf, - size_t buflen); -.fi -.SH DESCRIPTION -Write data to a channel stream. All channel streams have one standard I/O -substream (stream_id == 0), and may have up to 2^32 extended data streams as -identified by the selected \fIstream_id\fP. The SSH2 protocol currently -defines a stream ID of 1 to be the stderr substream. - -\fIchannel\fP - active channel stream to write to. - -\fIstream_id\fP - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) - -\fIbuf\fP - pointer to buffer to write - -\fIbuflen\fP - size of the data to write - -\fIlibssh2_channel_write(3)\fP and \fIlibssh2_channel_write_stderr(3)\fP are -convenience macros for this function. - -\fIlibssh2_channel_write_ex(3)\fP will use as much as possible of the buffer -and put it into a single SSH protocol packet. This means that to get maximum -performance when sending larger files, you should try to always pass in at -least 32K of data to this function. -.SH RETURN VALUE -Actual number of bytes written or negative on failure. -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_CHANNEL_CLOSED\fP - The channel has been closed. - -\fILIBSSH2_ERROR_CHANNEL_EOF_SENT\fP - The channel has been requested to be - -\fILIBSSH2_ERROR_BAD_USE\fP - This can be returned if you ignored a previous -return for LIBSSH2_ERROR_EAGAIN and rather than sending the original buffer with -the original size, you sent a new buffer with a different size. - -closed. -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) -.BR libssh2_channel_read_ex(3) diff --git a/docs/libssh2_channel_write_ex.md b/docs/libssh2_channel_write_ex.md new file mode 100644 index 00000000..2c950d40 --- /dev/null +++ b/docs/libssh2_channel_write_ex.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_write_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_channel_read_ex(3) +--- + +# NAME + +libssh2_channel_write_ex - write data to a channel stream blocking + +# SYNOPSIS + +~~~c +#include + +ssize_t +libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, + int stream_id, char *buf, + size_t buflen); +~~~ + +# DESCRIPTION + +Write data to a channel stream. All channel streams have one standard I/O +substream (stream_id == 0), and may have up to 2^32 extended data streams as +identified by the selected *stream_id*. The SSH2 protocol currently +defines a stream ID of 1 to be the stderr substream. + +*channel* - active channel stream to write to. + +*stream_id* - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) + +*buf* - pointer to buffer to write + +*buflen* - size of the data to write + +*libssh2_channel_write(3)* and *libssh2_channel_write_stderr(3)* are +convenience macros for this function. + +*libssh2_channel_write_ex(3)* will use as much as possible of the buffer +and put it into a single SSH protocol packet. This means that to get maximum +performance when sending larger files, you should try to always pass in at +least 32K of data to this function. + +# RETURN VALUE + +Actual number of bytes written or negative on failure. +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_CLOSED* - The channel has been closed. + +*LIBSSH2_ERROR_CHANNEL_EOF_SENT* - The channel has been requested to be + +*LIBSSH2_ERROR_BAD_USE* - This can be returned if you ignored a previous +return for LIBSSH2_ERROR_EAGAIN and rather than sending the original buffer with +the original size, you sent a new buffer with a different size. + +closed. diff --git a/docs/libssh2_channel_write_stderr.3 b/docs/libssh2_channel_write_stderr.3 deleted file mode 100644 index 832a5c26..00000000 --- a/docs/libssh2_channel_write_stderr.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_write_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_write_stderr - convenience macro for \fIlibssh2_channel_write_ex(3)\fP -.SH SYNOPSIS -.nf -#include - -ssize_t -libssh2_channel_write_stderr(LIBSSH2_CHANNEL *channel, - const char *buf, size_t buflen); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_write_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_write_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_write_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_write_ex(3) diff --git a/docs/libssh2_channel_write_stderr.md b/docs/libssh2_channel_write_stderr.md new file mode 100644 index 00000000..07699e16 --- /dev/null +++ b/docs/libssh2_channel_write_stderr.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_write_stderr +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_write_ex(3) +--- + +# NAME + +libssh2_channel_write_stderr - convenience macro for *libssh2_channel_write_ex(3)* + +# SYNOPSIS + +~~~c +#include + +ssize_t +libssh2_channel_write_stderr(LIBSSH2_CHANNEL *channel, + const char *buf, size_t buflen); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_write_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_write_ex(3)* + +# ERRORS + +See *libssh2_channel_write_ex(3)* diff --git a/docs/libssh2_channel_x11_req.3 b/docs/libssh2_channel_x11_req.3 deleted file mode 100644 index 15300a22..00000000 --- a/docs/libssh2_channel_x11_req.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_x11_req 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_channel_x11_req - convenience macro for \fIlibssh2_channel_x11_req_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_x11_req(LIBSSH2_CHANNEL *channel, int screen_number); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_channel_x11_req_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_channel_x11_req_ex(3)\fP -.SH ERRORS -See \fIlibssh2_channel_x11_req_ex(3)\fP -.SH SEE ALSO -.BR libssh2_channel_x11_req_ex(3) diff --git a/docs/libssh2_channel_x11_req.md b/docs/libssh2_channel_x11_req.md new file mode 100644 index 00000000..08b21df1 --- /dev/null +++ b/docs/libssh2_channel_x11_req.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_x11_req +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_x11_req_ex(3) +--- + +# NAME + +libssh2_channel_x11_req - convenience macro for *libssh2_channel_x11_req_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_x11_req(LIBSSH2_CHANNEL *channel, int screen_number); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_channel_x11_req_ex(3)*. + +# RETURN VALUE + +See *libssh2_channel_x11_req_ex(3)* + +# ERRORS + +See *libssh2_channel_x11_req_ex(3)* diff --git a/docs/libssh2_channel_x11_req_ex.3 b/docs/libssh2_channel_x11_req_ex.3 deleted file mode 100644 index a87e40ee..00000000 --- a/docs/libssh2_channel_x11_req_ex.3 +++ /dev/null @@ -1,47 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_channel_x11_req_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_channel_x11_req_ex - request an X11 forwarding channel -.SH SYNOPSIS -.nf -#include - -int -libssh2_channel_x11_req_ex(LIBSSH2_CHANNEL *channel, int single_connection, - const char *auth_proto, const char *auth_cookie, - int screen_number); - -int -libssh2_channel_x11_req(LIBSSH2_CHANNEL *channel, - int screen_number); -.fi -.SH DESCRIPTION -\fIchannel\fP - Previously opened channel instance such as returned by -.BR libssh2_channel_open_ex(3) - -\fIsingle_connection\fP - non-zero to only forward a single connection. - -\fIauth_proto\fP - X11 authentication protocol to use - -\fIauth_cookie\fP - the cookie (hexadecimal encoded). - -\fIscreen_number\fP - the XLL screen to forward - -Request an X11 forwarding on \fIchannel\fP. To use X11 forwarding, -.BR libssh2_session_callback_set2(3) -must first be called to set \fBLIBSSH2_CALLBACK_X11\fP. This callback will be -invoked when the remote host accepts the X11 forwarding. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) -.BR libssh2_session_callback_set2(3) diff --git a/docs/libssh2_channel_x11_req_ex.md b/docs/libssh2_channel_x11_req_ex.md new file mode 100644 index 00000000..5d550368 --- /dev/null +++ b/docs/libssh2_channel_x11_req_ex.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_channel_x11_req_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_session_callback_set2(3) +--- + +# NAME + +libssh2_channel_x11_req_ex - request an X11 forwarding channel + +# SYNOPSIS + +~~~c +#include + +int +libssh2_channel_x11_req_ex(LIBSSH2_CHANNEL *channel, int single_connection, + const char *auth_proto, const char *auth_cookie, + int screen_number); + +int +libssh2_channel_x11_req(LIBSSH2_CHANNEL *channel, + int screen_number); +~~~ + +# DESCRIPTION + +*channel* - Previously opened channel instance such as returned by +libssh2_channel_open_ex(3). + +*single_connection* - non-zero to only forward a single connection. + +*auth_proto* - X11 authentication protocol to use + +*auth_cookie* - the cookie (hexadecimal encoded). + +*screen_number* - the XLL screen to forward + +Request an X11 forwarding on *channel*. To use X11 forwarding, +libssh2_session_callback_set2(3) +must first be called to set **LIBSSH2_CALLBACK_X11**. This callback will be +invoked when the remote host accepts the X11 forwarding. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_CHANNEL_REQUEST_DENIED* - diff --git a/docs/libssh2_crypto_engine.3 b/docs/libssh2_crypto_engine.3 deleted file mode 100644 index 591a84ac..00000000 --- a/docs/libssh2_crypto_engine.3 +++ /dev/null @@ -1,16 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_crypto_engine 3 "22 Nov 2021" "libssh2" "libssh2" -.SH NAME -libssh2_crypto_engine - retrieve used crypto engine -.SH SYNOPSIS -.nf -#include - -libssh2_crypto_engine_t -libssh2_crypto_engine(void); -.fi -.SH DESCRIPTION -Returns currently used crypto engine, as en enum value. -.SH AVAILABILITY -Added in libssh2 1.11 diff --git a/docs/libssh2_crypto_engine.md b/docs/libssh2_crypto_engine.md new file mode 100644 index 00000000..6457be7f --- /dev/null +++ b/docs/libssh2_crypto_engine.md @@ -0,0 +1,29 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_crypto_engine +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_crypto_engine - retrieve used crypto engine + +# SYNOPSIS + +~~~c +#include + +libssh2_crypto_engine_t +libssh2_crypto_engine(void); +~~~ + +# DESCRIPTION + +Returns currently used crypto engine, as en enum value. + +# AVAILABILITY + +Added in libssh2 1.11 diff --git a/docs/libssh2_exit.3 b/docs/libssh2_exit.3 deleted file mode 100644 index cc5f158f..00000000 --- a/docs/libssh2_exit.3 +++ /dev/null @@ -1,18 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_exit 3 "19 Mar 2010" "libssh2" "libssh2" -.SH NAME -libssh2_exit - global library deinitialization -.SH SYNOPSIS -.nf -#include - -void -libssh2_exit(void); -.fi -.SH DESCRIPTION -Exit the libssh2 functions and frees all memory used internal. -.SH AVAILABILITY -Added in libssh2 1.2.5 -.SH SEE ALSO -.BR libssh2_init(3) diff --git a/docs/libssh2_exit.md b/docs/libssh2_exit.md new file mode 100644 index 00000000..3f02dc3a --- /dev/null +++ b/docs/libssh2_exit.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_exit +Section: 3 +Source: libssh2 +See-also: + - libssh2_init(3) +--- + +# NAME + +libssh2_exit - global library deinitialization + +# SYNOPSIS + +~~~c +#include + +void +libssh2_exit(void); +~~~ + +# DESCRIPTION + +Exit the libssh2 functions and frees all memory used internal. + +# AVAILABILITY + +Added in libssh2 1.2.5 diff --git a/docs/libssh2_free.3 b/docs/libssh2_free.md similarity index 62% rename from docs/libssh2_free.3 rename to docs/libssh2_free.md index 3aeed4af..cfb6a034 100644 --- a/docs/libssh2_free.3 +++ b/docs/libssh2_free.md @@ -1,23 +1,35 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_free 3 "13 Oct 2010" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_free +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_free - deallocate libssh2 memory -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include void libssh2_free(LIBSSH2_SESSION *session, void *ptr); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Deallocate memory allocated by earlier call to libssh2 functions. It uses the memory allocation callbacks provided by the application, if any. Otherwise, this will call free(). This function is mostly useful under Windows when libssh2 is linked to one run-time library and the application to another. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2.8 -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_hostkey_hash.3 b/docs/libssh2_hostkey_hash.md similarity index 55% rename from docs/libssh2_hostkey_hash.3 rename to docs/libssh2_hostkey_hash.md index a33edac0..3c4e84de 100644 --- a/docs/libssh2_hostkey_hash.3 +++ b/docs/libssh2_hostkey_hash.md @@ -1,29 +1,40 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_hostkey_hash 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_hostkey_hash +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_hostkey_hash - return a hash of the remote host's key -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include const char * libssh2_hostkey_hash(LIBSSH2_SESSION *session, int hash_type); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIhash_type\fP - One of: \fBLIBSSH2_HOSTKEY_HASH_MD5\fP, -\fBLIBSSH2_HOSTKEY_HASH_SHA1\fP or \fBLIBSSH2_HOSTKEY_HASH_SHA256\fP. +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*hash_type* - One of: **LIBSSH2_HOSTKEY_HASH_MD5**, +**LIBSSH2_HOSTKEY_HASH_SHA1** or **LIBSSH2_HOSTKEY_HASH_SHA256**. Returns the computed digest of the remote system's hostkey. The length of the returned string is hash_type specific (e.g. 16 bytes for MD5, 20 bytes for SHA1, 32 bytes for SHA256). -.SH RETURN VALUE + +# RETURN VALUE + Computed hostkey hash value, or NULL if the information is not available (either the session has not yet been started up, or the requested hash algorithm was not available). The hash consists of raw binary bytes, not hex digits, so it is not directly printable. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_init.3 b/docs/libssh2_init.md similarity index 60% rename from docs/libssh2_init.3 rename to docs/libssh2_init.md index 5631d7f7..167dbe0f 100644 --- a/docs/libssh2_init.3 +++ b/docs/libssh2_init.md @@ -1,24 +1,38 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_init 3 "19 Mar 2010" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_init +Section: 3 +Source: libssh2 +See-also: + - libssh2_exit(3) +--- + +# NAME + libssh2_init - global library initialization -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #define LIBSSH2_INIT_NO_CRYPTO 0x0001 int libssh2_init(int flags); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Initialize the libssh2 functions. This typically initialize the crypto library. It uses a global state, and is not thread safe -- you must make sure this function is not called concurrently. -.SH RETURN VALUE + +# RETURN VALUE + Returns 0 if succeeded, or a negative value for error. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2.5 -.SH SEE ALSO -.BR libssh2_exit(3) diff --git a/docs/libssh2_keepalive_config.3 b/docs/libssh2_keepalive_config.md similarity index 52% rename from docs/libssh2_keepalive_config.3 rename to docs/libssh2_keepalive_config.md index c78053e9..b7509475 100644 --- a/docs/libssh2_keepalive_config.3 +++ b/docs/libssh2_keepalive_config.md @@ -1,29 +1,43 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_keepalive_config 3 "12 Apr 2011" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_keepalive_config +Section: 3 +Source: libssh2 +See-also: + - libssh2_keepalive_send(3) +--- + +# NAME + libssh2_keepalive_config - short function description -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include void libssh2_keepalive_config(LIBSSH2_SESSION *session, int want_reply, unsigned int interval); -.fi -.SH DESCRIPTION -Set how often keepalive messages should be sent. \fBwant_reply\fP indicates +~~~ + +# DESCRIPTION + +Set how often keepalive messages should be sent. **want_reply** indicates whether the keepalive messages should request a response from the server. -\fBinterval\fP is number of seconds that can pass without any I/O, use 0 (the +**interval** is number of seconds that can pass without any I/O, use 0 (the default) to disable keepalives. To avoid some busy-loop corner-cases, if you specify an interval of 1 it will be treated as 2. Note that non-blocking applications are responsible for sending the keepalive -messages using \fBlibssh2_keepalive_send(3)\fP. -.SH RETURN VALUE +messages using **libssh2_keepalive_send(3)**. + +# RETURN VALUE + Nothing -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2.5 -.SH SEE ALSO -.BR libssh2_keepalive_send(3) diff --git a/docs/libssh2_keepalive_send.3 b/docs/libssh2_keepalive_send.3 deleted file mode 100644 index b660d461..00000000 --- a/docs/libssh2_keepalive_send.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_keepalive_send 3 "13 Apr 2011" "libssh2" "libssh2" -.SH NAME -libssh2_keepalive_send - short function description -.SH SYNOPSIS -.nf -#include - -int -libssh2_keepalive_send(LIBSSH2_SESSION *session, - int *seconds_to_next); -.fi -.SH DESCRIPTION -Send a keepalive message if needed. \fBseconds_to_next\fP indicates how many -seconds you can sleep after this call before you need to call it again. -.SH RETURN VALUE -Returns 0 on success, or LIBSSH2_ERROR_SOCKET_SEND on I/O errors. -.SH AVAILABILITY -Added in libssh2 1.2.5 -.SH SEE ALSO -.BR libssh2_keepalive_config(3) diff --git a/docs/libssh2_keepalive_send.md b/docs/libssh2_keepalive_send.md new file mode 100644 index 00000000..4832ebb5 --- /dev/null +++ b/docs/libssh2_keepalive_send.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_keepalive_send +Section: 3 +Source: libssh2 +See-also: + - libssh2_keepalive_config(3) +--- + +# NAME + +libssh2_keepalive_send - short function description + +# SYNOPSIS + +~~~c +#include + +int +libssh2_keepalive_send(LIBSSH2_SESSION *session, + int *seconds_to_next); +~~~ + +# DESCRIPTION + +Send a keepalive message if needed. **seconds_to_next** indicates how many +seconds you can sleep after this call before you need to call it again. + +# RETURN VALUE + +Returns 0 on success, or LIBSSH2_ERROR_SOCKET_SEND on I/O errors. + +# AVAILABILITY + +Added in libssh2 1.2.5 diff --git a/docs/libssh2_knownhost_add.3 b/docs/libssh2_knownhost_add.md similarity index 61% rename from docs/libssh2_knownhost_add.3 rename to docs/libssh2_knownhost_add.md index c881e36f..c80a9141 100644 --- a/docs/libssh2_knownhost_add.3 +++ b/docs/libssh2_knownhost_add.md @@ -1,10 +1,23 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_add 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_add +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_addc(3) + - libssh2_knownhost_check(3) + - libssh2_knownhost_free(3) + - libssh2_knownhost_init(3) +--- + +# NAME + libssh2_knownhost_add - add a known host -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -13,30 +26,32 @@ libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts, char *key, size_t keylen, int typemask, struct libssh2_knownhost **store); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + We discourage use of this function as of libssh2 1.2.5. Instead we strongly -urge users to use \fIlibssh2_knownhost_addc(3)\fP instead, which as a more -complete API. \fIlibssh2_knownhost_add(3)\fP is subject for removal in a +urge users to use *libssh2_knownhost_addc(3)* instead, which as a more +complete API. *libssh2_knownhost_add(3)* is subject for removal in a future release. Adds a known host to the collection of known hosts identified by the 'hosts' handle. -\fIhost\fP is a pointer the host name in plain text or hashed. If hashed, it +*host* is a pointer the host name in plain text or hashed. If hashed, it must be provided base64 encoded. The host name can be the IP numerical address of the host or the full name. -\fIsalt\P is a pointer to the salt used for the host hashing, if the host is +*saltP is a pointer to the salt used for the host hashing, if the host is provided hashed. If the host is provided in plain text, salt has no meaning. The salt has to be provided base64 encoded with a trailing zero byte. -\fIkey\fP is a pointer to the key for the given host. +*key* is a pointer to the key for the given host. -\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +*keylen* is the total size in bytes of the key pointed to by the *key* argument -\fItypemask\fP is a bitmask that specifies format and info about the data +*typemask* is a bitmask that specifies format and info about the data passed to this function. Specifically, it details what format the host name is, what format the key is and what key type it is. @@ -51,17 +66,16 @@ The key is using one of these algorithms: LIBSSH2_KNOWNHOST_KEY_RSA1, LIBSSH2_KNOWNHOST_KEY_SSHRSA or LIBSSH2_KNOWNHOST_KEY_SSHDSS (deprecated). -\fIstore\fP should point to a pointer that gets filled in to point to the +*store* should point to a pointer that gets filled in to point to the known host data after the addition. NULL can be passed if you do not care about this pointer. -.SH RETURN VALUE + +# RETURN VALUE + Returns a regular libssh2 error code, where negative values are error codes and 0 indicates success. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2, deprecated since libssh2 1.2.5. Use -\fIlibssh2_knownhost_addc(3)\fP instead! -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_check(3) -.BR libssh2_knownhost_addc(3) +*libssh2_knownhost_addc(3)* instead! diff --git a/docs/libssh2_knownhost_addc.3 b/docs/libssh2_knownhost_addc.md similarity index 63% rename from docs/libssh2_knownhost_addc.3 rename to docs/libssh2_knownhost_addc.md index 5a1b8c56..7cea89c1 100644 --- a/docs/libssh2_knownhost_addc.3 +++ b/docs/libssh2_knownhost_addc.md @@ -1,10 +1,22 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_addc 3 "28 May 2009" "libssh2 1.2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_addc +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_check(3) + - libssh2_knownhost_free(3) + - libssh2_knownhost_init(3) +--- + +# NAME + libssh2_knownhost_addc - add a known host -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -14,34 +26,36 @@ libssh2_knownhost_addc(LIBSSH2_KNOWNHOSTS *hosts, const char *comment, size_t commentlen, int typemask, struct libssh2_knownhost **store); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Adds a known host to the collection of known hosts identified by the 'hosts' handle. -\fIhost\fP is a pointer the host name in plain text or hashed. If hashed, it +*host* is a pointer the host name in plain text or hashed. If hashed, it must be provided base64 encoded. The host name can be the IP numerical address of the host or the full name. If you want to add a key for a specific port number for the given host, you must provide the host name like '[host]:port' with the actual characters '[' and ']' enclosing the host name and a colon separating the host part from the -port number. For example: \&"[host.example.com]:222". +port number. For example: "[host.example.com]:222". -\fIsalt\fP is a pointer to the salt used for the host hashing, if the host is +*salt* is a pointer to the salt used for the host hashing, if the host is provided hashed. If the host is provided in plain text, salt has no meaning. The salt has to be provided base64 encoded with a trailing zero byte. -\fIkey\fP is a pointer to the key for the given host. +*key* is a pointer to the key for the given host. -\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +*keylen* is the total size in bytes of the key pointed to by the *key* argument -\fIcomment\fP is a pointer to a comment for the key. +*comment* is a pointer to a comment for the key. -\fIcommentlen\fP is the total size in bytes of the comment pointed to by the \fIcomment\fP argument +*commentlen* is the total size in bytes of the comment pointed to by the *comment* argument -\fItypemask\fP is a bitmask that specifies format and info about the data +*typemask* is a bitmask that specifies format and info about the data passed to this function. Specifically, it details what format the host name is, what format the key is and what key type it is. @@ -56,15 +70,15 @@ The key is using one of these algorithms: LIBSSH2_KNOWNHOST_KEY_RSA1, LIBSSH2_KNOWNHOST_KEY_SSHRSA or LIBSSH2_KNOWNHOST_KEY_SSHDSS (deprecated). -\fIstore\fP should point to a pointer that gets filled in to point to the +*store* should point to a pointer that gets filled in to point to the known host data after the addition. NULL can be passed if you do not care about this pointer. -.SH RETURN VALUE + +# RETURN VALUE + Returns a regular libssh2 error code, where negative values are error codes and 0 indicates success. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2.5 -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_check.3 b/docs/libssh2_knownhost_check.md similarity index 65% rename from docs/libssh2_knownhost_check.3 rename to docs/libssh2_knownhost_check.md index 37d5c230..52d9f6fb 100644 --- a/docs/libssh2_knownhost_check.3 +++ b/docs/libssh2_knownhost_check.md @@ -1,10 +1,22 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_check 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_check +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_free(3) + - libssh2_knownhost_init(3) +--- + +# NAME + libssh2_knownhost_check - check a host+key against the list of known hosts -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -13,20 +25,22 @@ libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts, const char *key, size_t keylen, int typemask, struct libssh2_knownhost **knownhost); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Checks a host and its associated key against the collection of known hosts, and returns info back about the (partially) matched entry. -\fIhost\fP is a pointer the host name in plain text. The host name can be the +*host* is a pointer the host name in plain text. The host name can be the IP numerical address of the host or the full name. -\fIkey\fP is a pointer to the key for the given host. +*key* is a pointer to the key for the given host. -\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +*keylen* is the total size in bytes of the key pointed to by the *key* argument -\fItypemask\fP is a bitmask that specifies format and info about the data +*typemask* is a bitmask that specifies format and info about the data passed to this function. Specifically, it details what format the host name is, what format the key is and what key type it is. @@ -36,11 +50,13 @@ LIBSSH2_KNOWNHOST_TYPE_PLAIN or LIBSSH2_KNOWNHOST_TYPE_CUSTOM. The key is encoded using one of the following encodings: LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. -\fIknownhost\fP if set to non-NULL, it must be a pointer to a 'struct +*knownhost* if set to non-NULL, it must be a pointer to a 'struct libssh2_knownhost' pointer that gets filled in to point to info about a known host that matches or partially matches. -.SH RETURN VALUE -\fIlibssh2_knownhost_check(3)\fP returns info about how well the provided + +# RETURN VALUE + +*libssh2_knownhost_check(3)* returns info about how well the provided host + key pair matched one of the entries in the list of known hosts. LIBSSH2_KNOWNHOST_CHECK_FAILURE - something prevented the check to be made @@ -50,11 +66,11 @@ LIBSSH2_KNOWNHOST_CHECK_NOTFOUND - no host match was found LIBSSH2_KNOWNHOST_CHECK_MATCH - hosts and keys match. LIBSSH2_KNOWNHOST_CHECK_MISMATCH - host was found, but the keys did not match! -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2 -.SH EXAMPLE + +# EXAMPLE + See the ssh2_exec.c example as provided in the tarball. -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_knownhost_checkp.3 b/docs/libssh2_knownhost_checkp.md similarity index 66% rename from docs/libssh2_knownhost_checkp.3 rename to docs/libssh2_knownhost_checkp.md index de603909..bba88fc9 100644 --- a/docs/libssh2_knownhost_checkp.3 +++ b/docs/libssh2_knownhost_checkp.md @@ -1,10 +1,22 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_checkp 3 "1 May 2010" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_checkp +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_free(3) + - libssh2_knownhost_init(3) +--- + +# NAME + libssh2_knownhost_checkp - check a host+key against the list of known hosts -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -13,25 +25,27 @@ libssh2_knownhost_checkp(LIBSSH2_KNOWNHOSTS *hosts, const char *key, size_t keylen, int typemask, struct libssh2_knownhost **knownhost); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Checks a host and its associated key against the collection of known hosts, and returns info back about the (partially) matched entry. -\fIhost\fP is a pointer the host name in plain text. The host name can be the +*host* is a pointer the host name in plain text. The host name can be the IP numerical address of the host or the full name. -\fIport\fP is the port number used by the host (or a negative number +*port* is the port number used by the host (or a negative number to check the generic host). If the port number is given, libssh2 will check the key for the specific host + port number combination in addition to the plain host name only check. -\fIkey\fP is a pointer to the key for the given host. +*key* is a pointer to the key for the given host. -\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +*keylen* is the total size in bytes of the key pointed to by the *key* argument -\fItypemask\fP is a bitmask that specifies format and info about the data +*typemask* is a bitmask that specifies format and info about the data passed to this function. Specifically, it details what format the host name is, what format the key is and what key type it is. @@ -41,11 +55,13 @@ LIBSSH2_KNOWNHOST_TYPE_PLAIN or LIBSSH2_KNOWNHOST_TYPE_CUSTOM. The key is encoded using one of the following encodings: LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. -\fIknownhost\fP if set to non-NULL, it must be a pointer to a 'struct +*knownhost* if set to non-NULL, it must be a pointer to a 'struct libssh2_knownhost' pointer that gets filled in to point to info about a known host that matches or partially matches. -.SH RETURN VALUE -\fIlibssh2_knownhost_check(3)\fP returns info about how well the provided + +# RETURN VALUE + +*libssh2_knownhost_check(3)* returns info about how well the provided host + key pair matched one of the entries in the list of known hosts. LIBSSH2_KNOWNHOST_CHECK_FAILURE - something prevented the check to be made @@ -55,11 +71,11 @@ LIBSSH2_KNOWNHOST_CHECK_NOTFOUND - no host match was found LIBSSH2_KNOWNHOST_CHECK_MATCH - hosts and keys match. LIBSSH2_KNOWNHOST_CHECK_MISMATCH - host was found, but the keys did not match! -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2.6 -.SH EXAMPLE + +# EXAMPLE + See the ssh2_exec.c example as provided in the tarball. -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_knownhost_del.3 b/docs/libssh2_knownhost_del.3 deleted file mode 100644 index 9efc4c67..00000000 --- a/docs/libssh2_knownhost_del.3 +++ /dev/null @@ -1,28 +0,0 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_del 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME -libssh2_knownhost_del - delete a known host entry -.SH SYNOPSIS -.nf -#include - -int -libssh2_knownhost_del(LIBSSH2_KNOWNHOSTS *hosts, - struct libssh2_knownhost *entry); -.fi -.SH DESCRIPTION -Delete a known host entry from the collection of known hosts. - -\fIentry\fP is a pointer to a struct that you can extract with -\fIlibssh2_knownhost_check(3)\fP or \fIlibssh2_knownhost_get(3)\fP. -.SH RETURN VALUE -Returns a regular libssh2 error code, where negative values are error codes -and 0 indicates success. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_add(3) -.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_del.md b/docs/libssh2_knownhost_del.md new file mode 100644 index 00000000..93fc8d0f --- /dev/null +++ b/docs/libssh2_knownhost_del.md @@ -0,0 +1,42 @@ +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_del +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_check(3) + - libssh2_knownhost_free(3) + - libssh2_knownhost_init(3) +--- + +# NAME + +libssh2_knownhost_del - delete a known host entry + +# SYNOPSIS + +~~~c +#include + +int +libssh2_knownhost_del(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost *entry); +~~~ + +# DESCRIPTION + +Delete a known host entry from the collection of known hosts. + +*entry* is a pointer to a struct that you can extract with +*libssh2_knownhost_check(3)* or *libssh2_knownhost_get(3)*. + +# RETURN VALUE + +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_knownhost_free.3 b/docs/libssh2_knownhost_free.3 deleted file mode 100644 index f9e17344..00000000 --- a/docs/libssh2_knownhost_free.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_free 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME -libssh2_knownhost_free - free a collection of known hosts -.SH SYNOPSIS -.nf -#include - -void -libssh2_knownhost_free(LIBSSH2_KNOWNHOSTS *hosts); -.fi -.SH DESCRIPTION -Free a collection of known hosts. -.SH RETURN VALUE -None. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_add(3) -.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_free.md b/docs/libssh2_knownhost_free.md new file mode 100644 index 00000000..16fa6313 --- /dev/null +++ b/docs/libssh2_knownhost_free.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_free +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_check(3) + - libssh2_knownhost_init(3) +--- + +# NAME + +libssh2_knownhost_free - free a collection of known hosts + +# SYNOPSIS + +~~~c +#include + +void +libssh2_knownhost_free(LIBSSH2_KNOWNHOSTS *hosts); +~~~ + +# DESCRIPTION + +Free a collection of known hosts. + +# RETURN VALUE + +None. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_knownhost_get.3 b/docs/libssh2_knownhost_get.3 deleted file mode 100644 index 318a7fc4..00000000 --- a/docs/libssh2_knownhost_get.3 +++ /dev/null @@ -1,37 +0,0 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_get 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME -libssh2_knownhost_get - get a known host off the collection of known hosts -.SH SYNOPSIS -.nf -#include - -int -libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts, - struct libssh2_knownhost **store, - struct libssh2_knownhost *prev): -.fi -.SH DESCRIPTION -\fIlibssh2_knownhost_get(3)\fP allows an application to iterate over all known -hosts in the collection. - -\fIstore\fP should point to a pointer that gets filled in to point to the -known host data. - -\fIprev\fP is a pointer to a previous 'struct libssh2_knownhost' as returned -by a previous invoke of this function, or NULL to get the first entry in the -internal collection. -.SH RETURN VALUE -Returns 0 if everything is fine and information about a host was stored in -the \fIstore\fP struct. - -Returns 1 if it reached the end of hosts. - -Returns negative values for error -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_readfile(3) -.BR libssh2_knownhost_writefile(3) -.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_knownhost_get.md b/docs/libssh2_knownhost_get.md new file mode 100644 index 00000000..190a04c1 --- /dev/null +++ b/docs/libssh2_knownhost_get.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_get +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_readfile(3) + - libssh2_knownhost_writefile(3) +--- + +# NAME + +libssh2_knownhost_get - get a known host off the collection of known hosts + +# SYNOPSIS + +~~~c +#include + +int +libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost **store, + struct libssh2_knownhost *prev): +~~~ + +# DESCRIPTION + +*libssh2_knownhost_get(3)* allows an application to iterate over all known +hosts in the collection. + +*store* should point to a pointer that gets filled in to point to the +known host data. + +*prev* is a pointer to a previous 'struct libssh2_knownhost' as returned +by a previous invoke of this function, or NULL to get the first entry in the +internal collection. + +# RETURN VALUE + +Returns 0 if everything is fine and information about a host was stored in +the *store* struct. + +Returns 1 if it reached the end of hosts. + +Returns negative values for error + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_knownhost_init.3 b/docs/libssh2_knownhost_init.md similarity index 54% rename from docs/libssh2_knownhost_init.3 rename to docs/libssh2_knownhost_init.md index 95b7c62e..9b05555d 100644 --- a/docs/libssh2_knownhost_init.3 +++ b/docs/libssh2_knownhost_init.md @@ -1,27 +1,41 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_init 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_init +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_check(3) + - libssh2_knownhost_free(3) +--- + +# NAME + libssh2_knownhost_init - init a collection of known hosts -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include LIBSSH2_KNOWNHOSTS * libssh2_knownhost_init(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Init a collection of known hosts for this session. Returns the handle to an internal representation of a known host collection. -Call \fBlibssh2_knownhost_free(3)\fP to free the collection again after you are +Call **libssh2_knownhost_free(3)** to free the collection again after you are doing using it. -.SH RETURN VALUE + +# RETURN VALUE + Returns a handle pointer or NULL if something went wrong. The returned handle is used as input to all other known host related functions libssh2 provides. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_add(3) -.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_readfile.3 b/docs/libssh2_knownhost_readfile.md similarity index 51% rename from docs/libssh2_knownhost_readfile.3 rename to docs/libssh2_knownhost_readfile.md index c5a46970..f1d583df 100644 --- a/docs/libssh2_knownhost_readfile.3 +++ b/docs/libssh2_knownhost_readfile.md @@ -1,31 +1,45 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_readfile 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_readfile +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_check(3) + - libssh2_knownhost_free(3) + - libssh2_knownhost_init(3) +--- + +# NAME + libssh2_knownhost_readfile - parse a file of known hosts -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_knownhost_readfile(LIBSSH2_KNOWNHOSTS *hosts, const char *filename, int type); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Reads a collection of known hosts from a specified file and adds them to the collection of known hosts. -\fIfilename\fP specifies which file to read +*filename* specifies which file to read -\fItype\fP specifies what file type it is, and -\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +*type* specifies what file type it is, and +*LIBSSH2_KNOWNHOST_FILE_OPENSSH* is the only currently supported format. This file is normally found named ~/.ssh/known_hosts -.SH RETURN VALUE + +# RETURN VALUE + Returns a negative value, a regular libssh2 error code for errors, or a positive number as number of parsed known hosts in the file. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_init(3) -.BR libssh2_knownhost_free(3) -.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_readline.3 b/docs/libssh2_knownhost_readline.3 deleted file mode 100644 index 24184942..00000000 --- a/docs/libssh2_knownhost_readline.3 +++ /dev/null @@ -1,32 +0,0 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_readline 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME -libssh2_knownhost_readline - read a known host line -.SH SYNOPSIS -.nf -#include - -int -libssh2_knownhost_readline(LIBSSH2_KNOWNHOSTS *hosts, - const char *line, size_t len, int type): -.fi -.SH DESCRIPTION -Tell libssh2 to read a buffer as it if is a line from a known hosts file. - -\fIline\fP points to the start of the line - -\fIlen\fP is the length of the line in bytes - -\fItype\fP specifies what file type it is, and -\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported -format. This file is normally found named ~/.ssh/known_hosts -.SH RETURN VALUE -Returns a regular libssh2 error code, where negative values are error codes -and 0 indicates success. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_get(3) -.BR libssh2_knownhost_writeline(3) -.BR libssh2_knownhost_readfile(3) diff --git a/docs/libssh2_knownhost_readline.md b/docs/libssh2_knownhost_readline.md new file mode 100644 index 00000000..dc56dbc6 --- /dev/null +++ b/docs/libssh2_knownhost_readline.md @@ -0,0 +1,46 @@ +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_readline +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_get(3) + - libssh2_knownhost_readfile(3) + - libssh2_knownhost_writeline(3) +--- + +# NAME + +libssh2_knownhost_readline - read a known host line + +# SYNOPSIS + +~~~c +#include + +int +libssh2_knownhost_readline(LIBSSH2_KNOWNHOSTS *hosts, + const char *line, size_t len, int type): +~~~ + +# DESCRIPTION + +Tell libssh2 to read a buffer as it if is a line from a known hosts file. + +*line* points to the start of the line + +*len* is the length of the line in bytes + +*type* specifies what file type it is, and +*LIBSSH2_KNOWNHOST_FILE_OPENSSH* is the only currently supported +format. This file is normally found named ~/.ssh/known_hosts + +# RETURN VALUE + +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_knownhost_writefile.3 b/docs/libssh2_knownhost_writefile.3 deleted file mode 100644 index 2e2b0a2f..00000000 --- a/docs/libssh2_knownhost_writefile.3 +++ /dev/null @@ -1,30 +0,0 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_writefile 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME -libssh2_knownhost_writefile - write a collection of known hosts to a file -.SH SYNOPSIS -.nf -#include - -int -libssh2_knownhost_writefile(LIBSSH2_KNOWNHOSTS *hosts, - const char *filename, int type); -.fi -.SH DESCRIPTION -Writes all the known hosts to the specified file using the specified file -format. - -\fIfilename\fP specifies what filename to create - -\fItype\fP specifies what file type it is, and -\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported -format. -.SH RETURN VALUE -Returns a regular libssh2 error code, where negative values are error codes -and 0 indicates success. -.SH AVAILABILITY -Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_readfile(3) -.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_knownhost_writefile.md b/docs/libssh2_knownhost_writefile.md new file mode 100644 index 00000000..ff3ee0bd --- /dev/null +++ b/docs/libssh2_knownhost_writefile.md @@ -0,0 +1,44 @@ +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_writefile +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_readfile(3) +--- + +# NAME + +libssh2_knownhost_writefile - write a collection of known hosts to a file + +# SYNOPSIS + +~~~c +#include + +int +libssh2_knownhost_writefile(LIBSSH2_KNOWNHOSTS *hosts, + const char *filename, int type); +~~~ + +# DESCRIPTION + +Writes all the known hosts to the specified file using the specified file +format. + +*filename* specifies what filename to create + +*type* specifies what file type it is, and +*LIBSSH2_KNOWNHOST_FILE_OPENSSH* is the only currently supported +format. + +# RETURN VALUE + +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. + +# AVAILABILITY + +Added in libssh2 1.2 diff --git a/docs/libssh2_knownhost_writeline.3 b/docs/libssh2_knownhost_writeline.md similarity index 54% rename from docs/libssh2_knownhost_writeline.3 rename to docs/libssh2_knownhost_writeline.md index 03023f72..361864eb 100644 --- a/docs/libssh2_knownhost_writeline.3 +++ b/docs/libssh2_knownhost_writeline.md @@ -1,10 +1,22 @@ -.\" Copyright (C) Daniel Stenberg -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_knownhost_writeline 3 "28 May 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_knownhost_writeline +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_get(3) + - libssh2_knownhost_readline(3) + - libssh2_knownhost_writefile(3) +--- + +# NAME + libssh2_knownhost_writeline - convert a known host to a line for storage -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -13,35 +25,37 @@ libssh2_knownhost_writeline(LIBSSH2_KNOWNHOSTS *hosts, char *buffer, size_t buflen, size_t *outlen, int type); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Converts a single known host to a single line of output for storage, using the 'type' output format. -\fIknown\fP identifies which particular known host +*known* identifies which particular known host -\fIbuffer\fP points to an allocated buffer +*buffer* points to an allocated buffer -\fIbuflen\fP is the size of the \fIbuffer\fP. See RETURN VALUE about the size. +*buflen* is the size of the *buffer*. See RETURN VALUE about the size. -\fIoutlen\fP must be a pointer to a size_t variable that will get the output +*outlen* must be a pointer to a size_t variable that will get the output length of the stored data chunk. The number does not included the trailing zero! -\fItype\fP specifies what file type it is, and -\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +*type* specifies what file type it is, and +*LIBSSH2_KNOWNHOST_FILE_OPENSSH* is the only currently supported format. -.SH RETURN VALUE + +# RETURN VALUE + Returns a regular libssh2 error code, where negative values are error codes and 0 indicates success. If the provided buffer is deemed too small to fit the data libssh2 wants to store in it, LIBSSH2_ERROR_BUFFER_TOO_SMALL will be returned. The application is then advised to call the function again with a larger buffer. The -\fIoutlen\fP size will then hold the requested size. -.SH AVAILABILITY +*outlen* size will then hold the requested size. + +# AVAILABILITY + Added in libssh2 1.2 -.SH SEE ALSO -.BR libssh2_knownhost_get(3) -.BR libssh2_knownhost_readline(3) -.BR libssh2_knownhost_writefile(3) diff --git a/docs/libssh2_poll.3 b/docs/libssh2_poll.md similarity index 60% rename from docs/libssh2_poll.3 rename to docs/libssh2_poll.md index 7bda2f2a..11c7d067 100644 --- a/docs/libssh2_poll.3 +++ b/docs/libssh2_poll.md @@ -1,26 +1,38 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_poll 3 "14 Dec 2006" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_poll +Section: 3 +Source: libssh2 +See-also: + - libssh2_poll_channel_read(3) +--- + +# NAME + libssh2_poll - poll for activity on a socket, channel or listener -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_poll(LIBSSH2_POLLFD *fds, unsigned int nfds, long timeout); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This function is deprecated. Do note use. We encourage users to instead use -the \fIpoll(3)\fP or \fIselect(3)\fP functions to check for socket activity or +the *poll(3)* or *select(3)* functions to check for socket activity or when specific sockets are ready to get received from or send to. Poll for activity on a socket, channel, listener, or any combination of these three types. The calling semantics for this function generally match -\fIpoll(2)\fP however the structure of fds is somewhat more complex in order +*poll(2)* however the structure of fds is somewhat more complex in order to accommodate the disparate datatypes, POLLFD constants have been namespaced to avoid platform discrepancies, and revents has additional values defined. -.SH "RETURN VALUE" + +# RETURN VALUE + Number of fds with interesting events. -.SH SEE ALSO -.BR libssh2_poll_channel_read(3) diff --git a/docs/libssh2_poll_channel_read.3 b/docs/libssh2_poll_channel_read.3 deleted file mode 100644 index 9878c3b1..00000000 --- a/docs/libssh2_poll_channel_read.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_poll_channel_read 3 "14 Dec 2006" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_poll_channel_read - check if data is available -.SH SYNOPSIS -.nf -#include - -int -libssh2_poll_channel_read(LIBSSH2_CHANNEL *channel, int extended); -.fi -.SH DESCRIPTION -This function is deprecated. Do note use. - -\fIlibssh2_poll_channel_read(3)\fP checks to see if data is available in the -\fIchannel\fP's read buffer. No attempt is made with this method to see if -packets are available to be processed. For full polling support, use -\fIlibssh2_poll(3)\fP. -.SH RETURN VALUE -Returns 1 when data is available and 0 otherwise. -.SH SEE ALSO -.BR libssh2_poll(3) diff --git a/docs/libssh2_poll_channel_read.md b/docs/libssh2_poll_channel_read.md new file mode 100644 index 00000000..9dce2f8a --- /dev/null +++ b/docs/libssh2_poll_channel_read.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_poll_channel_read +Section: 3 +Source: libssh2 +See-also: + - libssh2_poll(3) +--- + +# NAME + +libssh2_poll_channel_read - check if data is available + +# SYNOPSIS + +~~~c +#include + +int +libssh2_poll_channel_read(LIBSSH2_CHANNEL *channel, int extended); +~~~ + +# DESCRIPTION + +This function is deprecated. Do note use. + +*libssh2_poll_channel_read(3)* checks to see if data is available in the +*channel*'s read buffer. No attempt is made with this method to see if +packets are available to be processed. For full polling support, use +*libssh2_poll(3)*. + +# RETURN VALUE + +Returns 1 when data is available and 0 otherwise. diff --git a/docs/libssh2_publickey_add.3 b/docs/libssh2_publickey_add.3 deleted file mode 100644 index 75abb115..00000000 --- a/docs/libssh2_publickey_add.3 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_add 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_publickey_add - convenience macro for \fIlibssh2_publickey_add_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_publickey_add(LIBSSH2_PUBLICKEY *pkey, - const unsigned char *name, - const unsigned char *blob, unsigned long blob_len, - char overwrite, unsigned long num_attrs, - const libssh2_publickey_attribute attrs[]); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_publickey_add_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_publickey_add_ex(3)\fP -.SH ERRORS -See \fIlibssh2_publickey_add_ex(3)\fP -.SH SEE ALSO -.BR libssh2_publickey_add_ex(3) diff --git a/docs/libssh2_publickey_add.md b/docs/libssh2_publickey_add.md new file mode 100644 index 00000000..ecd687d1 --- /dev/null +++ b/docs/libssh2_publickey_add.md @@ -0,0 +1,39 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_add +Section: 3 +Source: libssh2 +See-also: + - libssh2_publickey_add_ex(3) +--- + +# NAME + +libssh2_publickey_add - convenience macro for *libssh2_publickey_add_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_publickey_add(LIBSSH2_PUBLICKEY *pkey, + const unsigned char *name, + const unsigned char *blob, unsigned long blob_len, + char overwrite, unsigned long num_attrs, + const libssh2_publickey_attribute attrs[]); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_publickey_add_ex(3)*. + +# RETURN VALUE + +See *libssh2_publickey_add_ex(3)* + +# ERRORS + +See *libssh2_publickey_add_ex(3)* diff --git a/docs/libssh2_publickey_add_ex.3 b/docs/libssh2_publickey_add_ex.md similarity index 70% rename from docs/libssh2_publickey_add_ex.3 rename to docs/libssh2_publickey_add_ex.md index 2446915b..fe3661ca 100644 --- a/docs/libssh2_publickey_add_ex.3 +++ b/docs/libssh2_publickey_add_ex.md @@ -1,10 +1,19 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_add_ex 3 "1 Jun 2007" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_add_ex +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_publickey_add_ex - Add a public key entry -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -13,16 +22,21 @@ libssh2_publickey_add_ex(LIBSSH2_PUBLICKEY *pkey, const unsigned char *blob, unsigned long blob_len, char overwrite, unsigned long num_attrs, const libssh2_publickey_attribute attrs[]) -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + TBD -.SH RETURN VALUE + +# RETURN VALUE + Returns 0 on success, negative on failure. -.SH ERRORS + +# ERRORS + LIBSSH2_ERROR_BAD_USE LIBSSH2_ERROR_ALLOC, LIBSSH2_ERROR_EAGAIN LIBSSH2_ERROR_SOCKET_SEND, LIBSSH2_ERROR_SOCKET_TIMEOUT, LIBSSH2_ERROR_PUBLICKEY_PROTOCOL, -.SH SEE ALSO diff --git a/docs/libssh2_publickey_init.3 b/docs/libssh2_publickey_init.3 deleted file mode 100644 index 6703ebe3..00000000 --- a/docs/libssh2_publickey_init.3 +++ /dev/null @@ -1,14 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_init 3 "1 Jun 2007" "libssh2" "libssh2" -.SH NAME -libssh2_publickey_init - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH AVAILABILITY -Added in libssh2 ?.?.? -.SH SEE ALSO diff --git a/docs/libssh2_publickey_init.md b/docs/libssh2_publickey_init.md new file mode 100644 index 00000000..d4b3c5bb --- /dev/null +++ b/docs/libssh2_publickey_init.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_init +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_publickey_init - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS + +# AVAILABILITY + +Added in libssh2 ?.?.? diff --git a/docs/libssh2_publickey_list_fetch.3 b/docs/libssh2_publickey_list_fetch.3 deleted file mode 100644 index aa23b7c5..00000000 --- a/docs/libssh2_publickey_list_fetch.3 +++ /dev/null @@ -1,14 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_list_fetch 3 "1 Jun 2007" "libssh2" "libssh2" -.SH NAME -libssh2_publickey_list_fetch - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH AVAILABILITY -Added in libssh2 ?.?.? -.SH SEE ALSO diff --git a/docs/libssh2_publickey_list_fetch.md b/docs/libssh2_publickey_list_fetch.md new file mode 100644 index 00000000..01d5c9e7 --- /dev/null +++ b/docs/libssh2_publickey_list_fetch.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_list_fetch +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_publickey_list_fetch - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS + +# AVAILABILITY + +Added in libssh2 ?.?.? diff --git a/docs/libssh2_publickey_list_free.3 b/docs/libssh2_publickey_list_free.3 deleted file mode 100644 index 17c15304..00000000 --- a/docs/libssh2_publickey_list_free.3 +++ /dev/null @@ -1,14 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_list_free 3 "1 Jun 2007" "libssh2" "libssh2" -.SH NAME -libssh2_publickey_list_free - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH AVAILABILITY -Added in libssh2 ?.?.? -.SH SEE ALSO diff --git a/docs/libssh2_publickey_list_free.md b/docs/libssh2_publickey_list_free.md new file mode 100644 index 00000000..aac09491 --- /dev/null +++ b/docs/libssh2_publickey_list_free.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_list_free +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_publickey_list_free - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS + +# AVAILABILITY + +Added in libssh2 ?.?.? diff --git a/docs/libssh2_publickey_remove.3 b/docs/libssh2_publickey_remove.3 deleted file mode 100644 index a07c9b2b..00000000 --- a/docs/libssh2_publickey_remove.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_remove 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_publickey_remove - convenience macro for \fIlibssh2_publickey_remove_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_publickey_remove(LIBSSH2_PUBLICKEY *pkey, - const unsigned char *name, unsigned long name_len, - const unsigned char *blob, unsigned long blob_len); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_publickey_remove_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_publickey_remove_ex(3)\fP -.SH ERRORS -See \fIlibssh2_publickey_remove_ex(3)\fP -.SH SEE ALSO -.BR libssh2_publickey_remove_ex(3) diff --git a/docs/libssh2_publickey_remove.md b/docs/libssh2_publickey_remove.md new file mode 100644 index 00000000..ecff1e65 --- /dev/null +++ b/docs/libssh2_publickey_remove.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_remove +Section: 3 +Source: libssh2 +See-also: + - libssh2_publickey_remove_ex(3) +--- + +# NAME + +libssh2_publickey_remove - convenience macro for *libssh2_publickey_remove_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_publickey_remove(LIBSSH2_PUBLICKEY *pkey, + const unsigned char *name, unsigned long name_len, + const unsigned char *blob, unsigned long blob_len); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_publickey_remove_ex(3)*. + +# RETURN VALUE + +See *libssh2_publickey_remove_ex(3)* + +# ERRORS + +See *libssh2_publickey_remove_ex(3)* diff --git a/docs/libssh2_publickey_remove_ex.3 b/docs/libssh2_publickey_remove_ex.3 deleted file mode 100644 index 8a2ce834..00000000 --- a/docs/libssh2_publickey_remove_ex.3 +++ /dev/null @@ -1,14 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_list_remove_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_publickey_list_remove_ex - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH AVAILABILITY -Added in libssh2 ?.?.? -.SH SEE ALSO diff --git a/docs/libssh2_publickey_remove_ex.md b/docs/libssh2_publickey_remove_ex.md new file mode 100644 index 00000000..87298796 --- /dev/null +++ b/docs/libssh2_publickey_remove_ex.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_list_remove_ex +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_publickey_list_remove_ex - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS + +# AVAILABILITY + +Added in libssh2 ?.?.? diff --git a/docs/libssh2_publickey_shutdown.3 b/docs/libssh2_publickey_shutdown.3 deleted file mode 100644 index 6ad80196..00000000 --- a/docs/libssh2_publickey_shutdown.3 +++ /dev/null @@ -1,14 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_publickey_shutdown 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_publickey_shutdown - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH AVAILABILITY -Added in libssh2 ?.?.? -.SH SEE ALSO diff --git a/docs/libssh2_publickey_shutdown.md b/docs/libssh2_publickey_shutdown.md new file mode 100644 index 00000000..4f9e4efa --- /dev/null +++ b/docs/libssh2_publickey_shutdown.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_publickey_shutdown +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_publickey_shutdown - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS + +# AVAILABILITY + +Added in libssh2 ?.?.? diff --git a/docs/libssh2_scp_recv.3 b/docs/libssh2_scp_recv.3 deleted file mode 100644 index df04aea4..00000000 --- a/docs/libssh2_scp_recv.3 +++ /dev/null @@ -1,39 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_scp_recv 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_scp_recv - request a remote file via SCP -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_scp_recv(LIBSSH2_SESSION *session, const char *path, struct stat *sb); -.fi -.SH DESCRIPTION -This function is \fBDEPRECATED\fP in 1.7.0. Use the -\fIlibssh2_scp_recv2(3)\fP function instead! - -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIpath\fP - Full path and filename of file to transfer. That is the remote -file name. - -\fIsb\fP - Populated with remote file's size, mode, mtime, and atime - -Request a file from the remote host via SCP. -.SH RETURN VALUE -Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_INVAL\fP - Invalid argument used in function call. - -\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would -block. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_scp_recv.md b/docs/libssh2_scp_recv.md new file mode 100644 index 00000000..3b8b4cf5 --- /dev/null +++ b/docs/libssh2_scp_recv.md @@ -0,0 +1,52 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_scp_recv +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_scp_recv - request a remote file via SCP + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_scp_recv(LIBSSH2_SESSION *session, const char *path, struct stat *sb); +~~~ + +# DESCRIPTION + +This function is **DEPRECATED** in 1.7.0. Use the +*libssh2_scp_recv2(3)* function instead! + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*path* - Full path and filename of file to transfer. That is the remote +file name. + +*sb* - Populated with remote file's size, mode, mtime, and atime + +Request a file from the remote host via SCP. + +# RETURN VALUE + +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_INVAL* - Invalid argument used in function call. + +*LIBSSH2_ERROR_SCP_PROTOCOL* - + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would +block. diff --git a/docs/libssh2_scp_recv2.3 b/docs/libssh2_scp_recv2.3 deleted file mode 100644 index 4408b4d5..00000000 --- a/docs/libssh2_scp_recv2.3 +++ /dev/null @@ -1,36 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_scp_recv2 3 "29 Jun 2015" "libssh2 1.6.1" "libssh2" -.SH NAME -libssh2_scp_recv2 - request a remote file via SCP -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_scp_recv2(LIBSSH2_SESSION *session, const char *path, struct_stat *sb); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIpath\fP - Full path and filename of file to transfer. That is the remote -file name. - -\fIsb\fP - Populated with remote file's size, mode, mtime, and atime - -Request a file from the remote host via SCP. -.SH RETURN VALUE -Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_INVAL\fP - Invalid argument used in function call. - -\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would -block. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_scp_recv2.md b/docs/libssh2_scp_recv2.md new file mode 100644 index 00000000..d70b45ed --- /dev/null +++ b/docs/libssh2_scp_recv2.md @@ -0,0 +1,49 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_scp_recv2 +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_scp_recv2 - request a remote file via SCP + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_scp_recv2(LIBSSH2_SESSION *session, const char *path, struct_stat *sb); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*path* - Full path and filename of file to transfer. That is the remote +file name. + +*sb* - Populated with remote file's size, mode, mtime, and atime + +Request a file from the remote host via SCP. + +# RETURN VALUE + +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_INVAL* - Invalid argument used in function call. + +*LIBSSH2_ERROR_SCP_PROTOCOL* - + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would +block. diff --git a/docs/libssh2_scp_send.3 b/docs/libssh2_scp_send.3 deleted file mode 100644 index c2289e79..00000000 --- a/docs/libssh2_scp_send.3 +++ /dev/null @@ -1,26 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_scp_send 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_scp_send - convenience macro for \fIlibssh2_scp_send_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_scp_send(LIBSSH2_SESSION *session, const char *path, - int mode, size_t size); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_scp_send_ex(3)\fP. - -This macro has been deemed deprecated since libssh2 1.2.6. See -\fIlibssh2_scp_send64(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_scp_send_ex(3)\fP -.SH ERRORS -See \fIlibssh2_scp_send_ex(3)\fP -.SH SEE ALSO -.BR libssh2_scp_send_ex(3), -.BR libssh2_scp_send64(3) diff --git a/docs/libssh2_scp_send.md b/docs/libssh2_scp_send.md new file mode 100644 index 00000000..476ae242 --- /dev/null +++ b/docs/libssh2_scp_send.md @@ -0,0 +1,40 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_scp_send +Section: 3 +Source: libssh2 +See-also: + - libssh2_scp_send64(3) + - libssh2_scp_send_ex(3) +--- + +# NAME + +libssh2_scp_send - convenience macro for *libssh2_scp_send_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_scp_send(LIBSSH2_SESSION *session, const char *path, + int mode, size_t size); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_scp_send_ex(3)*. + +This macro has been deemed deprecated since libssh2 1.2.6. See +*libssh2_scp_send64(3)*. + +# RETURN VALUE + +See *libssh2_scp_send_ex(3)* + +# ERRORS + +See *libssh2_scp_send_ex(3)* diff --git a/docs/libssh2_scp_send64.3 b/docs/libssh2_scp_send64.3 deleted file mode 100644 index 401f99bc..00000000 --- a/docs/libssh2_scp_send64.3 +++ /dev/null @@ -1,52 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_scp_send64 3 "17 Apr 2010" "libssh2 1.2.6" "libssh2" -.SH NAME -libssh2_scp_send64 - Send a file via SCP -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode, - libssh2_uint64_t size, time_t mtime, time_t atime); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIpath\fP - Full path and filename of file to transfer to. That is the remote -file name. - -\fImode\fP - File access mode to create file with - -\fIsize\fP - Size of file being transmitted (Must be known ahead of -time). Note that this needs to be passed on as variable type -libssh2_uint64_t. This type is 64 bit on modern operating systems and -compilers. - -\fImtime\fP - mtime to assign to file being created - -\fIatime\fP - atime to assign to file being created (Set this and -mtime to zero to instruct remote host to use current time). - -Send a file to the remote host via SCP. -.SH RETURN VALUE -Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. - -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_INVAL\fP - Invalid argument used in function call. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would -block. -.SH AVAILABILITY -This function was added in libssh2 1.2.6 and is meant to replace the former -\fIlibssh2_scp_send_ex(3)\fP function. -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_scp_send64.md b/docs/libssh2_scp_send64.md new file mode 100644 index 00000000..e0903cfb --- /dev/null +++ b/docs/libssh2_scp_send64.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_scp_send64 +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_scp_send64 - Send a file via SCP + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode, + libssh2_uint64_t size, time_t mtime, time_t atime); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*path* - Full path and filename of file to transfer to. That is the remote +file name. + +*mode* - File access mode to create file with + +*size* - Size of file being transmitted (Must be known ahead of +time). Note that this needs to be passed on as variable type +libssh2_uint64_t. This type is 64 bit on modern operating systems and +compilers. + +*mtime* - mtime to assign to file being created + +*atime* - atime to assign to file being created (Set this and +mtime to zero to instruct remote host to use current time). + +Send a file to the remote host via SCP. + +# RETURN VALUE + +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_INVAL* - Invalid argument used in function call. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SCP_PROTOCOL* - + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would +block. + +# AVAILABILITY + +This function was added in libssh2 1.2.6 and is meant to replace the former +*libssh2_scp_send_ex(3)* function. diff --git a/docs/libssh2_scp_send_ex.3 b/docs/libssh2_scp_send_ex.3 deleted file mode 100644 index f5d287fb..00000000 --- a/docs/libssh2_scp_send_ex.3 +++ /dev/null @@ -1,51 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_scp_send_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_scp_send_ex - Send a file via SCP -.SH SYNOPSIS -.nf -#include - -LIBSSH2_CHANNEL * -libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode, - size_t size, long mtime, long atime); -.fi -.SH DESCRIPTION -This function has been deemed deprecated since libssh2 1.2.6. See -\fIlibssh2_scp_send64(3)\fP. - -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIpath\fP - Full path and filename of file to transfer to. That is the remote -file name. - -\fImode\fP - File access mode to create file with - -\fIsize\fP - Size of file being transmitted (Must be known -ahead of time precisely) - -\fImtime\fP - mtime to assign to file being created - -\fIatime\fP - atime to assign to file being created (Set this and -mtime to zero to instruct remote host to use current time). - -Send a file to the remote host via SCP. -.SH RETURN VALUE -Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. - -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would -block. -.SH AVAILABILITY -This function was marked deprecated in libssh2 1.2.6 as -\fIlibssh2_scp_send64(3)\fP has been introduced to replace this function. -.SH SEE ALSO -.BR libssh2_channel_open_ex(3) diff --git a/docs/libssh2_scp_send_ex.md b/docs/libssh2_scp_send_ex.md new file mode 100644 index 00000000..3d0544df --- /dev/null +++ b/docs/libssh2_scp_send_ex.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_scp_send_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_channel_open_ex(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_scp_send_ex - Send a file via SCP + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_CHANNEL * +libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode, + size_t size, long mtime, long atime); +~~~ + +# DESCRIPTION + +This function has been deemed deprecated since libssh2 1.2.6. See +*libssh2_scp_send64(3)*. + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*path* - Full path and filename of file to transfer to. That is the remote +file name. + +*mode* - File access mode to create file with + +*size* - Size of file being transmitted (Must be known +ahead of time precisely) + +*mtime* - mtime to assign to file being created + +*atime* - atime to assign to file being created (Set this and +mtime to zero to instruct remote host to use current time). + +Send a file to the remote host via SCP. + +# RETURN VALUE + +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SCP_PROTOCOL* - + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would +block. + +# AVAILABILITY + +This function was marked deprecated in libssh2 1.2.6 as +*libssh2_scp_send64(3)* has been introduced to replace this function. diff --git a/docs/libssh2_session_abstract.3 b/docs/libssh2_session_abstract.3 deleted file mode 100644 index 09f0e4de..00000000 --- a/docs/libssh2_session_abstract.3 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_abstract 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_abstract - return a pointer to a session's abstract pointer -.SH SYNOPSIS -.nf -#include - -void ** -libssh2_session_abstract(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -Return a pointer to where the abstract pointer provided to -\fBlibssh2_session_init_ex(3)\fP is stored. By providing a doubly -de-referenced pointer, the internal storage of the session instance may be -modified in place. -.SH RETURN VALUE -A pointer to session internal storage whose contents point to previously -provided abstract data. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_abstract.md b/docs/libssh2_session_abstract.md new file mode 100644 index 00000000..659a394b --- /dev/null +++ b/docs/libssh2_session_abstract.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_abstract +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_abstract - return a pointer to a session's abstract pointer + +# SYNOPSIS + +~~~c +#include + +void ** +libssh2_session_abstract(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +Return a pointer to where the abstract pointer provided to +**libssh2_session_init_ex(3)** is stored. By providing a doubly +de-referenced pointer, the internal storage of the session instance may be +modified in place. + +# RETURN VALUE + +A pointer to session internal storage whose contents point to previously +provided abstract data. diff --git a/docs/libssh2_session_banner_get.3 b/docs/libssh2_session_banner_get.3 deleted file mode 100644 index 88f23995..00000000 --- a/docs/libssh2_session_banner_get.3 +++ /dev/null @@ -1,26 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_banner_get 3 "9 Sep 2011" "libssh2" "libssh2" -.SH NAME -libssh2_session_banner_get - get the remote banner -.SH SYNOPSIS -.nf -#include - -const char * -libssh2_session_banner_get(oLIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -Once the session has been setup and \fIlibssh2_session_handshake(3)\fP has -completed successfully, this function can be used to get the server id from -the banner each server presents. -.SH RETURN VALUE -A pointer to a string or NULL if something failed. The data pointed to will be -allocated and associated to the session handle and will be freed by libssh2 -when \fIlibssh2_session_free(3)\fP is used. -.SH AVAILABILITY -Added in 1.4.0 -.SH SEE ALSO -.BR libssh2_session_banner_set(3), -.BR libssh2_session_handshake(3), -.BR libssh2_session_free(3) diff --git a/docs/libssh2_session_banner_get.md b/docs/libssh2_session_banner_get.md new file mode 100644 index 00000000..44cb8ae8 --- /dev/null +++ b/docs/libssh2_session_banner_get.md @@ -0,0 +1,40 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_banner_get +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_banner_set(3) + - libssh2_session_free(3) + - libssh2_session_handshake(3) +--- + +# NAME + +libssh2_session_banner_get - get the remote banner + +# SYNOPSIS + +~~~c +#include + +const char * +libssh2_session_banner_get(oLIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +Once the session has been setup and *libssh2_session_handshake(3)* has +completed successfully, this function can be used to get the server id from +the banner each server presents. + +# RETURN VALUE + +A pointer to a string or NULL if something failed. The data pointed to will be +allocated and associated to the session handle and will be freed by libssh2 +when *libssh2_session_free(3)* is used. + +# AVAILABILITY + +Added in 1.4.0 diff --git a/docs/libssh2_session_banner_set.3 b/docs/libssh2_session_banner_set.3 deleted file mode 100644 index 037a4d6a..00000000 --- a/docs/libssh2_session_banner_set.3 +++ /dev/null @@ -1,35 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_banner_set 3 "9 Sep 2011" "libssh2" "libssh2" -.SH NAME -libssh2_session_banner_set - set the SSH protocol banner for the local client -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_banner_set(LIBSSH2_SESSION *session, const char *banner); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIbanner\fP - A pointer to a zero-terminated string holding the user defined -banner - -Set the banner that will be sent to the remote host when the SSH session is -started with \fIlibssh2_session_handshake(3)\fP This is optional; a banner -corresponding to the protocol and libssh2 version will be sent by default. -.SH RETURN VALUE -Returns 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN -when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative -number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -.SH AVAILABILITY -Added in 1.4.0. - -Before 1.4.0 this function was known as libssh2_banner_set(3) -.SH SEE ALSO -.BR libssh2_session_handshake(3), -.BR libssh2_session_banner_get(3) diff --git a/docs/libssh2_session_banner_set.md b/docs/libssh2_session_banner_set.md new file mode 100644 index 00000000..f9a2becc --- /dev/null +++ b/docs/libssh2_session_banner_set.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_banner_set +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_banner_get(3) + - libssh2_session_handshake(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_banner_set - set the SSH protocol banner for the local client + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_banner_set(LIBSSH2_SESSION *session, const char *banner); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*banner* - A pointer to a zero-terminated string holding the user defined +banner + +Set the banner that will be sent to the remote host when the SSH session is +started with *libssh2_session_handshake(3)* This is optional; a banner +corresponding to the protocol and libssh2 version will be sent by default. + +# RETURN VALUE + +Returns 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN +when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative +number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +# AVAILABILITY + +Added in 1.4.0. + +Before 1.4.0 this function was known as libssh2_banner_set(3) diff --git a/docs/libssh2_session_block_directions.3 b/docs/libssh2_session_block_directions.3 deleted file mode 100644 index 106de221..00000000 --- a/docs/libssh2_session_block_directions.3 +++ /dev/null @@ -1,33 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_block_directions 3 "1 Oct 2008" "libssh2" "libssh2" -.SH NAME -libssh2_session_block_directions - get directions to wait for -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_block_directions(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by \fBlibssh2_session_init_ex(3)\fP - -When any of libssh2 functions return \fBLIBSSH2_ERROR_EAGAIN\fP an application -should wait for the socket to have data available for reading or -writing. Depending on the return value of -\fIlibssh2_session_block_directions(3)\fP an application should wait for read, -write or both. -.SH RETURN VALUE -Returns the set of directions as a binary mask. Can be a combination of: - -LIBSSH2_SESSION_BLOCK_INBOUND: Inbound direction blocked. - -LIBSSH2_SESSION_BLOCK_OUTBOUND: Outbound direction blocked. - -Application should wait for data to be available for socket prior to calling a -libssh2 function again. If \fBLIBSSH2_SESSION_BLOCK_INBOUND\fP is set select -should contain the session socket in readfds set. Correspondingly in case of -\fBLIBSSH2_SESSION_BLOCK_OUTBOUND\fP writefds set should contain the socket. -.SH AVAILABILITY -Added in 1.0 diff --git a/docs/libssh2_session_block_directions.md b/docs/libssh2_session_block_directions.md new file mode 100644 index 00000000..cb180ad0 --- /dev/null +++ b/docs/libssh2_session_block_directions.md @@ -0,0 +1,48 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_block_directions +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_session_block_directions - get directions to wait for + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_block_directions(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by **libssh2_session_init_ex(3)** + +When any of libssh2 functions return **LIBSSH2_ERROR_EAGAIN** an application +should wait for the socket to have data available for reading or +writing. Depending on the return value of +*libssh2_session_block_directions(3)* an application should wait for read, +write or both. + +# RETURN VALUE + +Returns the set of directions as a binary mask. Can be a combination of: + +LIBSSH2_SESSION_BLOCK_INBOUND: Inbound direction blocked. + +LIBSSH2_SESSION_BLOCK_OUTBOUND: Outbound direction blocked. + +Application should wait for data to be available for socket prior to calling a +libssh2 function again. If **LIBSSH2_SESSION_BLOCK_INBOUND** is set select +should contain the session socket in readfds set. Correspondingly in case of +**LIBSSH2_SESSION_BLOCK_OUTBOUND** writefds set should contain the socket. + +# AVAILABILITY + +Added in 1.0 diff --git a/docs/libssh2_session_callback_set.3 b/docs/libssh2_session_callback_set.3 deleted file mode 100644 index 70c94c13..00000000 --- a/docs/libssh2_session_callback_set.3 +++ /dev/null @@ -1,31 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_callback_set 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_callback_set - set a callback function -.SH SYNOPSIS -.nf -#include - -void * -libssh2_session_callback_set(LIBSSH2_SESSION *session, - int cbtype, void *callback); -.fi -.SH DESCRIPTION -This function is \fBDEPRECATED\fP in 1.11.1. Use the -\fIlibssh2_session_callback_set2(3)\fP function instead! - -This implementation is expecting and returning a data pointer for callback -functions. - -For the details about the replacement function, see -.BR libssh2_session_callback_set2(3) -which is expecting and returning a function pointer. - -.SH RETURN VALUE -Pointer to previous callback handler. Returns NULL if no prior callback -handler was set or the callback type was unknown. -.SH SEE ALSO -.BR libssh2_session_callback_set2(3) -.BR libssh2_session_init_ex(3) -.BR libssh2_agent_sign(3) diff --git a/docs/libssh2_session_callback_set.md b/docs/libssh2_session_callback_set.md new file mode 100644 index 00000000..cd21a821 --- /dev/null +++ b/docs/libssh2_session_callback_set.md @@ -0,0 +1,41 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_callback_set +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_sign(3) + - libssh2_session_callback_set2(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_callback_set - set a callback function + +# SYNOPSIS + +~~~c +#include + +void * +libssh2_session_callback_set(LIBSSH2_SESSION *session, + int cbtype, void *callback); +~~~ + +# DESCRIPTION + +This function is **DEPRECATED** in 1.11.1. Use the +*libssh2_session_callback_set2(3)* function instead! + +This implementation is expecting and returning a data pointer for callback +functions. + +For the details about the replacement function, see libssh2_session_callback_set2(3) +which is expecting and returning a function pointer. + +# RETURN VALUE + +Pointer to previous callback handler. Returns NULL if no prior callback +handler was set or the callback type was unknown. diff --git a/docs/libssh2_session_callback_set2.3 b/docs/libssh2_session_callback_set2.md similarity index 61% rename from docs/libssh2_session_callback_set2.3 rename to docs/libssh2_session_callback_set2.md index ee55af94..e30222f8 100644 --- a/docs/libssh2_session_callback_set2.3 +++ b/docs/libssh2_session_callback_set2.md @@ -1,101 +1,132 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_callback_set2 3 "13 Dec 2023" "libssh2 1.11.1" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_callback_set2 +Section: 3 +Source: libssh2 +See-also: + - libssh2_agent_sign(3) + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_session_callback_set2 - set a callback function -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include libssh2_cb_generic * libssh2_session_callback_set2(LIBSSH2_SESSION *session, int cbtype, libssh2_cb_generic *callback); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Sets a custom callback handler for a previously initialized session object. Callbacks are triggered by the receipt of special packets at the Transport layer. To disable a callback, set it to NULL. -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +*session* - Session instance as returned by libssh2_session_init_ex(3) -\fIcbtype\fP - Callback type. One of the types listed in Callback Types. +*cbtype* - Callback type. One of the types listed in Callback Types. -\fIcallback\fP - Pointer to custom callback function. The prototype for +*callback* - Pointer to custom callback function. The prototype for this function must match the associated callback declaration macro. -.SH CALLBACK TYPES -.IP LIBSSH2_CALLBACK_IGNORE + +# CALLBACK TYPES + +## LIBSSH2_CALLBACK_IGNORE + Called when a SSH_MSG_IGNORE message is received -.IP LIBSSH2_CALLBACK_DEBUG + +## LIBSSH2_CALLBACK_DEBUG + Called when a SSH_MSG_DEBUG message is received -.IP LIBSSH2_CALLBACK_DISCONNECT + +## LIBSSH2_CALLBACK_DISCONNECT + Called when a SSH_MSG_DISCONNECT message is received -.IP LIBSSH2_CALLBACK_MACERROR + +## LIBSSH2_CALLBACK_MACERROR + Called when a mismatched MAC has been detected in the transport layer. If the function returns 0, the packet will be accepted nonetheless. -.IP LIBSSH2_CALLBACK_X11 + +## LIBSSH2_CALLBACK_X11 + Called when an X11 connection has been accepted -.IP LIBSSH2_CALLBACK_SEND + +## LIBSSH2_CALLBACK_SEND + Called when libssh2 wants to send data on the connection. Can be set to a custom function to handle I/O your own way. The prototype of the callback: -.nf +~~~c ssize_t sendcb(libssh2_socket_t sockfd, const void *buffer, size_t length, int flags, void **abstract); -.fi +~~~ -\fBsockfd\fP is the socket to write to, \fBbuffer\fP points to the data to -send, \fBlength\fP is the size of the data, \fBflags\fP is the flags that -would have been used to a \fIsend()\fP call and \fBabstract\fP is a pointer -to the abstract pointer set in the \fIlibssh2_session_init_ex(3)\fP call. +**sockfd** is the socket to write to, **buffer** points to the data to +send, **length** is the size of the data, **flags** is the flags that +would have been used to a *send()* call and **abstract** is a pointer +to the abstract pointer set in the *libssh2_session_init_ex(3)* call. -The callback returns the number of bytes sent, or \-1 for error. The special -return code \fB-EAGAIN\fP can be returned to signal that the send was aborted +The callback returns the number of bytes sent, or -1 for error. The special +return code **-EAGAIN** can be returned to signal that the send was aborted to prevent getting blocked and it needs to be called again. -.IP LIBSSH2_CALLBACK_RECV + +## LIBSSH2_CALLBACK_RECV + Called when libssh2 wants to read data from the connection. Can be set to a custom function to handle I/O your own way. The prototype of the callback: -.nf +~~~c ssize_t recvcb(libssh2_socket_t sockfd, void *buffer, size_t length, int flags, void **abstract); -.fi +~~~ -\fBsockfd\fP is the socket to read from, \fBbuffer\fP where to store received -data into, \fBlength\fP is the size of the buffer, \fBflags\fP is the flags -that would have been used to a \fIrecv()\fP call and \fBabstract\fP is a pointer -to the abstract pointer set in the \fIlibssh2_session_init_ex(3)\fP call. +**sockfd** is the socket to read from, **buffer** where to store received +data into, **length** is the size of the buffer, **flags** is the flags +that would have been used to a *recv()* call and **abstract** is a pointer +to the abstract pointer set in the *libssh2_session_init_ex(3)* call. -The callback returns the number of bytes read, or \-1 for error. The special -return code \fB-EAGAIN\fP can be returned to signal that the read was aborted +The callback returns the number of bytes read, or -1 for error. The special +return code **-EAGAIN** can be returned to signal that the read was aborted to prevent getting blocked and it needs to be called again. -.IP LIBSSH2_CALLBACK_AUTHAGENT + +## LIBSSH2_CALLBACK_AUTHAGENT + Called during authentication process to allow the client to connect to the ssh-agent and perform any setup, such as configuring the agent or adding keys. The prototype of the callback: -.nf +~~~c void authagent(LIBSSH2_SESSION* session, LIBSSH2_CHANNEL *channel, void **abstract); -.fi -.IP LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES +~~~ + +## LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES + Not called by libssh2. The client is responsible for calling this method when a SSH2_AGENTC_REQUEST_IDENTITIES message has been received. The prototype of the callback: -.nf +~~~c void identities(LIBSSH2_SESSION* session, void *buffer, const char *agent_path, void **abstract) -.fi +~~~ -\fBbuffer\fP must be filled in by the callback. Different clients may implement +**buffer** must be filled in by the callback. Different clients may implement this differently. For example, one client may pass in an unsigned char ** for this parameter, while another may pass in a pointer to a struct. @@ -111,29 +142,29 @@ Where each entry in the entries list is of the format: string data cstring comment -\fBagent_path\fP The path to a running ssh-agent on the client machine, from +**agent_path** The path to a running ssh-agent on the client machine, from which identities can be listed. -.IP LIBSSH2_CALLBACK_AUTHAGENT_SIGN + +## LIBSSH2_CALLBACK_AUTHAGENT_SIGN + Not called by libssh2. The client is responsible for calling this method when a SSH2_AGENTC_SIGN_REQUEST message has been received. The prototype of the callback: -.nf +~~~c void sign(LIBSSH2_SESSION* session, unsigned char *blob, unsigned int blen, const unsigned char *data, unsigned int dlen, unsigned char **sig, unsigned int *sig_len, const char *agent_path, void **abstract); -.fi +~~~ When interfacing with an ssh-agent installed on the client system, this method can call libssh2_agent_sign(3) to perform signing. -.SH RETURN VALUE +# RETURN VALUE + Pointer to previous callback handler. Returns NULL if no prior callback handler was set or the callback type was unknown. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) -.BR libssh2_agent_sign(3) diff --git a/docs/libssh2_session_disconnect.3 b/docs/libssh2_session_disconnect.3 deleted file mode 100644 index 85e14199..00000000 --- a/docs/libssh2_session_disconnect.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_disconnect 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_session_disconnect - convenience macro for \fIlibssh2_session_disconnect_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_disconnect(LIBSSH2_SESSION *session, const char *description); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_session_disconnect_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_session_disconnect_ex(3)\fP -.SH ERRORS -See \fIlibssh2_session_disconnect_ex(3)\fP -.SH SEE ALSO -.BR libssh2_session_disconnect_ex(3) diff --git a/docs/libssh2_session_disconnect.md b/docs/libssh2_session_disconnect.md new file mode 100644 index 00000000..1b4239a0 --- /dev/null +++ b/docs/libssh2_session_disconnect.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_disconnect +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_disconnect_ex(3) +--- + +# NAME + +libssh2_session_disconnect - convenience macro for *libssh2_session_disconnect_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_disconnect(LIBSSH2_SESSION *session, const char *description); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_session_disconnect_ex(3)*. + +# RETURN VALUE + +See *libssh2_session_disconnect_ex(3)* + +# ERRORS + +See *libssh2_session_disconnect_ex(3)* diff --git a/docs/libssh2_session_disconnect_ex.3 b/docs/libssh2_session_disconnect_ex.3 deleted file mode 100644 index b1674eb6..00000000 --- a/docs/libssh2_session_disconnect_ex.3 +++ /dev/null @@ -1,43 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_disconnect_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_disconnect_ex - terminate transport layer -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, int reason, - const char *description, - const char *lang); - -int -libssh2_session_disconnect(LIBSSH2_SESSION *session, - const char *description); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIreason\fP - One of the Disconnect Reason constants. - -\fIdescription\fP - Human readable reason for disconnection. - -\fIlang\fP - Localization string describing the language/encoding of the description provided. - -Send a disconnect message to the remote host associated with \fIsession\fP, -along with a \fIreason\fP symbol and a verbose \fIdescription\fP. - -As a convenience, the macro -.BR libssh2_session_disconnect(3) -is provided. It calls -.BR libssh2_session_disconnect_ex(3) -with \fIreason\fP set to SSH_DISCONNECT_BY_APPLICATION -and \fIlang\fP set to an empty string. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_disconnect_ex.md b/docs/libssh2_session_disconnect_ex.md new file mode 100644 index 00000000..b75c4e1a --- /dev/null +++ b/docs/libssh2_session_disconnect_ex.md @@ -0,0 +1,54 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_disconnect_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_disconnect(3) + - libssh2_session_disconnect_ex(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_disconnect_ex - terminate transport layer + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, int reason, + const char *description, + const char *lang); + +int +libssh2_session_disconnect(LIBSSH2_SESSION *session, + const char *description); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*reason* - One of the Disconnect Reason constants. + +*description* - Human readable reason for disconnection. + +*lang* - Localization string describing the language/encoding of the description provided. + +Send a disconnect message to the remote host associated with *session*, +along with a *reason* symbol and a verbose *description*. + +As a convenience, the macro libssh2_session_disconnect(3) +is provided. It calls libssh2_session_disconnect_ex(3) +with *reason* set to SSH_DISCONNECT_BY_APPLICATION +and *lang* set to an empty string. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. diff --git a/docs/libssh2_session_flag.3 b/docs/libssh2_session_flag.md similarity index 54% rename from docs/libssh2_session_flag.3 rename to docs/libssh2_session_flag.md index b8e8fec8..4bb6b753 100644 --- a/docs/libssh2_session_flag.3 +++ b/docs/libssh2_session_flag.md @@ -1,29 +1,48 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_flag 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_flag +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_session_flag - TODO -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_session_flag(LIBSSH2_SESSION *session, int flag, int value); -.fi -.SH DESCRIPTION -Set options for the created session. \fIflag\fP is the option to set, while -\fIvalue\fP is typically set to 1 or 0 to enable or disable the option. -.SH FLAGS -.IP LIBSSH2_FLAG_SIGPIPE +~~~ + +# DESCRIPTION + +Set options for the created session. *flag* is the option to set, while +*value* is typically set to 1 or 0 to enable or disable the option. + +# FLAGS + +## LIBSSH2_FLAG_SIGPIPE + If set, libssh2 will not attempt to block SIGPIPEs but will let them trigger from the underlying socket layer. -.IP LIBSSH2_FLAG_COMPRESS + +## LIBSSH2_FLAG_COMPRESS + If set - before the connection negotiation is performed - libssh2 will try to negotiate compression enabling for this connection. By default libssh2 will not attempt to use compression. -.SH RETURN VALUE + +# RETURN VALUE + Returns regular libssh2 error code. -.SH AVAILABILITY + +# AVAILABILITY + This function has existed since the age of dawn. LIBSSH2_FLAG_COMPRESS was added in version 1.2.8. -.SH SEE ALSO diff --git a/docs/libssh2_session_free.3 b/docs/libssh2_session_free.md similarity index 52% rename from docs/libssh2_session_free.3 rename to docs/libssh2_session_free.md index 618653ac..1f66add0 100644 --- a/docs/libssh2_session_free.3 +++ b/docs/libssh2_session_free.md @@ -1,22 +1,35 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_free 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_free +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_disconnect_ex(3) + - libssh2_session_disconnect_ex(3) + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_session_free - frees resources associated with a session instance -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_session_free(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Frees all resources associated with a session instance. Typically called after -.BR libssh2_session_disconnect_ex(3) -.SH RETURN VALUE +libssh2_session_disconnect_ex(3). + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) -.BR libssh2_session_disconnect_ex(3) diff --git a/docs/libssh2_session_get_blocking.3 b/docs/libssh2_session_get_blocking.md similarity index 50% rename from docs/libssh2_session_get_blocking.3 rename to docs/libssh2_session_get_blocking.md index 2d3b793e..603567d8 100644 --- a/docs/libssh2_session_get_blocking.3 +++ b/docs/libssh2_session_get_blocking.md @@ -1,19 +1,31 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_get_blocking 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_get_blocking +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_set_blocking(3) +--- + +# NAME + libssh2_session_get_blocking - evaluate blocking mode on session -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_session_get_blocking(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Returns 0 if the state of the session has previously be set to non-blocking and it returns 1 if the state was set to blocking. -.SH RETURN VALUE + +# RETURN VALUE + See description. -.SH SEE ALSO -.BR libssh2_session_set_blocking(3) diff --git a/docs/libssh2_session_get_read_timeout.3 b/docs/libssh2_session_get_read_timeout.3 deleted file mode 100644 index 81b0cb1f..00000000 --- a/docs/libssh2_session_get_read_timeout.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_get_read_timeout 3 "13 Jan 2023" "libssh2" "libssh2" -.SH NAME -libssh2_session_get_read_timeout - get the timeout for packet read functions -.SH SYNOPSIS -.nf -#include - -long -libssh2_session_get_read_timeout(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -Returns the \fBtimeout\fP (in seconds) for how long the ssh2 packet receive -function calls may wait until they consider the situation an error and -return LIBSSH2_ERROR_TIMEOUT. - -By default the timeout is 60 seconds. -.SH RETURN VALUE -The value of the timeout setting. -.SH AVAILABILITY -Added in 1.10.1 -.SH SEE ALSO -.BR libssh2_session_set_read_timeout(3) diff --git a/docs/libssh2_session_get_read_timeout.md b/docs/libssh2_session_get_read_timeout.md new file mode 100644 index 00000000..b14d2d15 --- /dev/null +++ b/docs/libssh2_session_get_read_timeout.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_get_read_timeout +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_set_read_timeout(3) +--- + +# NAME + +libssh2_session_get_read_timeout - get the timeout for packet read functions + +# SYNOPSIS + +~~~c +#include + +long +libssh2_session_get_read_timeout(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +Returns the **timeout** (in seconds) for how long the ssh2 packet receive +function calls may wait until they consider the situation an error and +return LIBSSH2_ERROR_TIMEOUT. + +By default the timeout is 60 seconds. + +# RETURN VALUE + +The value of the timeout setting. + +# AVAILABILITY + +Added in 1.10.1 diff --git a/docs/libssh2_session_get_timeout.3 b/docs/libssh2_session_get_timeout.md similarity index 50% rename from docs/libssh2_session_get_timeout.3 rename to docs/libssh2_session_get_timeout.md index 4a57cedf..81e4a3f7 100644 --- a/docs/libssh2_session_get_timeout.3 +++ b/docs/libssh2_session_get_timeout.md @@ -1,24 +1,38 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_get_timeout 3 "4 May 2011" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_get_timeout +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_set_timeout(3) +--- + +# NAME + libssh2_session_get_timeout - get the timeout for blocking functions -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include long libssh2_session_get_timeout(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -Returns the \fBtimeout\fP (in milliseconds) for how long a blocking the +~~~ + +# DESCRIPTION + +Returns the **timeout** (in milliseconds) for how long a blocking the libssh2 function calls may wait until they consider the situation an error and return LIBSSH2_ERROR_TIMEOUT. By default libssh2 has no timeout (zero) for blocking functions. -.SH RETURN VALUE + +# RETURN VALUE + The value of the timeout setting. -.SH AVAILABILITY + +# AVAILABILITY + Added in 1.2.9 -.SH SEE ALSO -.BR libssh2_session_set_timeout(3) diff --git a/docs/libssh2_session_handshake.3 b/docs/libssh2_session_handshake.3 deleted file mode 100644 index 4d5cc511..00000000 --- a/docs/libssh2_session_handshake.3 +++ /dev/null @@ -1,44 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_handshake 3 "7 Oct 2010" "libssh2" "libssh2" -.SH NAME -libssh2_session_handshake - perform the SSH handshake -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t socket); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIsocket\fP - Connected socket descriptor. Typically a TCP connection -though the protocol allows for any reliable transport and the library will -attempt to use any berkeley socket. - -Begin transport layer protocol negotiation with the connected host. -.SH RETURN VALUE -Returns 0 on success, negative on failure. -.SH ERRORS -\fILIBSSH2_ERROR_SOCKET_NONE\fP - The socket is invalid. - -\fILIBSSH2_ERROR_BANNER_SEND\fP - Unable to send banner to remote host. - -\fILIBSSH2_ERROR_KEX_FAILURE\fP - Encryption key exchange with the remote -host failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_DISCONNECT\fP - The socket was disconnected. - -\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on -the socket. - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. -.SH AVAILABILITY -Added in 1.2.8 -.SH SEE ALSO -.BR libssh2_session_free(3) -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_handshake.md b/docs/libssh2_session_handshake.md new file mode 100644 index 00000000..eedd7536 --- /dev/null +++ b/docs/libssh2_session_handshake.md @@ -0,0 +1,59 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_handshake +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_free(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_handshake - perform the SSH handshake + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t socket); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*socket* - Connected socket descriptor. Typically a TCP connection +though the protocol allows for any reliable transport and the library will +attempt to use any berkeley socket. + +Begin transport layer protocol negotiation with the connected host. + +# RETURN VALUE + +Returns 0 on success, negative on failure. + +# ERRORS + +*LIBSSH2_ERROR_SOCKET_NONE* - The socket is invalid. + +*LIBSSH2_ERROR_BANNER_SEND* - Unable to send banner to remote host. + +*LIBSSH2_ERROR_KEX_FAILURE* - Encryption key exchange with the remote +host failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_DISCONNECT* - The socket was disconnected. + +*LIBSSH2_ERROR_PROTO* - An invalid SSH protocol response was received on +the socket. + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would block. + +# AVAILABILITY + +Added in 1.2.8 diff --git a/docs/libssh2_session_hostkey.3 b/docs/libssh2_session_hostkey.3 deleted file mode 100644 index 4190843d..00000000 --- a/docs/libssh2_session_hostkey.3 +++ /dev/null @@ -1,26 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_hostkey 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_hostkey - get the remote key -.SH SYNOPSIS -.nf -#include - -const char * -libssh2_session_hostkey(LIBSSH2_SESSION *session, - size_t *len, int *type); -.fi -.SH DESCRIPTION -Returns a pointer to the current host key, the value \fIlen\fP points to will -get the length of the key. - -The value \fItype\fP points to the type of hostkey which is one of: -LIBSSH2_HOSTKEY_TYPE_RSA, LIBSSH2_HOSTKEY_TYPE_DSS (deprecated), or -LIBSSH2_HOSTKEY_TYPE_UNKNOWN. - -.SH RETURN VALUE -A pointer, or NULL if something went wrong. -.SH SEE ALSO -.BR libssh2_knownhost_check(3) -.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_session_hostkey.md b/docs/libssh2_session_hostkey.md new file mode 100644 index 00000000..7442ddfc --- /dev/null +++ b/docs/libssh2_session_hostkey.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_hostkey +Section: 3 +Source: libssh2 +See-also: + - libssh2_knownhost_add(3) + - libssh2_knownhost_check(3) +--- + +# NAME + +libssh2_session_hostkey - get the remote key + +# SYNOPSIS + +~~~c +#include + +const char * +libssh2_session_hostkey(LIBSSH2_SESSION *session, + size_t *len, int *type); +~~~ + +# DESCRIPTION + +Returns a pointer to the current host key, the value *len* points to will +get the length of the key. + +The value *type* points to the type of hostkey which is one of: +LIBSSH2_HOSTKEY_TYPE_RSA, LIBSSH2_HOSTKEY_TYPE_DSS (deprecated), or +LIBSSH2_HOSTKEY_TYPE_UNKNOWN. + +# RETURN VALUE + +A pointer, or NULL if something went wrong. diff --git a/docs/libssh2_session_init.3 b/docs/libssh2_session_init.3 deleted file mode 100644 index 88f1fa8c..00000000 --- a/docs/libssh2_session_init.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_init 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_session_init - convenience macro for \fIlibssh2_session_init_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -LIBSSH2_SESSION * -libssh2_session_init(void); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_session_init_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_session_init_ex(3)\fP -.SH ERRORS -See \fIlibssh2_session_init_ex(3)\fP -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_init.md b/docs/libssh2_session_init.md new file mode 100644 index 00000000..a34663e3 --- /dev/null +++ b/docs/libssh2_session_init.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_init +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_init - convenience macro for *libssh2_session_init_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +LIBSSH2_SESSION * +libssh2_session_init(void); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_session_init_ex(3)*. + +# RETURN VALUE + +See *libssh2_session_init_ex(3)* + +# ERRORS + +See *libssh2_session_init_ex(3)* diff --git a/docs/libssh2_session_init_ex.3 b/docs/libssh2_session_init_ex.md similarity index 68% rename from docs/libssh2_session_init_ex.3 rename to docs/libssh2_session_init_ex.md index 3a79e786..775b1610 100644 --- a/docs/libssh2_session_init_ex.3 +++ b/docs/libssh2_session_init_ex.md @@ -1,10 +1,21 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_init_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_init_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_free(3) + - libssh2_session_handshake(3) +--- + +# NAME + libssh2_session_init_ex - initializes an SSH session object -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include LIBSSH2_SESSION * @@ -15,21 +26,23 @@ libssh2_session_init_ex(LIBSSH2_ALLOC_FUNC((*myalloc)), LIBSSH2_SESSION * libssh2_session_init(void); -.fi -.SH DESCRIPTION -\fImyalloc\fP - Custom allocator function. Refer to the section on Callbacks +~~~ + +# DESCRIPTION + +*myalloc* - Custom allocator function. Refer to the section on Callbacks for implementing an allocator callback. Pass a value of NULL to use the default system allocator. -\fImyfree\fP - Custom de-allocator function. Refer to the section on Callbacks +*myfree* - Custom de-allocator function. Refer to the section on Callbacks for implementing a deallocator callback. Pass a value of NULL to use the default system deallocator. -\fImyrealloc\fP - Custom re-allocator function. Refer to the section on +*myrealloc* - Custom re-allocator function. Refer to the section on Callbacks for implementing a reallocator callback. Pass a value of NULL to use the default system reallocator. -\fIabstract\fP - Arbitrary pointer to application specific callback data. +*abstract* - Arbitrary pointer to application specific callback data. This value will be passed to any callback function associated with the named session instance. @@ -41,8 +54,7 @@ may be attached to the session object. This method must be called first, prior to configuring session options or starting up an SSH session with a remote server. -.SH RETURN VALUE + +# RETURN VALUE + Pointer to a newly allocated LIBSSH2_SESSION instance, or NULL on errors. -.SH SEE ALSO -.BR libssh2_session_free(3) -.BR libssh2_session_handshake(3) diff --git a/docs/libssh2_session_last_errno.3 b/docs/libssh2_session_last_errno.3 deleted file mode 100644 index 029f49c2..00000000 --- a/docs/libssh2_session_last_errno.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_last_errno 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_last_errno - get the most recent error number -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_last_errno(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -Determine the most recent error condition. -.SH RETURN VALUE -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_errno.md b/docs/libssh2_session_last_errno.md new file mode 100644 index 00000000..34044bb8 --- /dev/null +++ b/docs/libssh2_session_last_errno.md @@ -0,0 +1,34 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_last_errno +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) + - libssh2_session_last_error(3) + - libssh2_session_set_last_error(3) +--- + +# NAME + +libssh2_session_last_errno - get the most recent error number + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_last_errno(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +Determine the most recent error condition. + +# RETURN VALUE + +Numeric error code corresponding to the the Error Code constants. diff --git a/docs/libssh2_session_last_error.3 b/docs/libssh2_session_last_error.3 deleted file mode 100644 index f11d65ff..00000000 --- a/docs/libssh2_session_last_error.3 +++ /dev/null @@ -1,34 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_last_error 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_last_error - get the most recent error -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_last_error(LIBSSH2_SESSION *session, - char **errmsg, int *errmsg_len, int want_buf); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIerrmsg\fP - If not NULL, is populated by reference with the human -readable form of the most recent error message. - -\fIerrmsg_len\fP - If not NULL, is populated by reference with the length -of errmsg. (The string is NUL-terminated, so the length is only useful as -an optimization, to avoid calling strlen.) - -\fIwant_buf\fP - If set to a non-zero value, "ownership" of the errmsg -buffer will be given to the calling scope. If necessary, the errmsg buffer -will be duplicated. - -Determine the most recent error condition and its cause. -.SH RETURN VALUE -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_last_error.md b/docs/libssh2_session_last_error.md new file mode 100644 index 00000000..d83b8acd --- /dev/null +++ b/docs/libssh2_session_last_error.md @@ -0,0 +1,46 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_last_error +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) + - libssh2_session_last_errno(3) + - libssh2_session_set_last_error(3) +--- + +# NAME + +libssh2_session_last_error - get the most recent error + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_last_error(LIBSSH2_SESSION *session, + char **errmsg, int *errmsg_len, int want_buf); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*errmsg* - If not NULL, is populated by reference with the human +readable form of the most recent error message. + +*errmsg_len* - If not NULL, is populated by reference with the length +of errmsg. (The string is NUL-terminated, so the length is only useful as +an optimization, to avoid calling strlen.) + +*want_buf* - If set to a non-zero value, "ownership" of the errmsg +buffer will be given to the calling scope. If necessary, the errmsg buffer +will be duplicated. + +Determine the most recent error condition and its cause. + +# RETURN VALUE + +Numeric error code corresponding to the the Error Code constants. diff --git a/docs/libssh2_session_method_pref.3 b/docs/libssh2_session_method_pref.3 deleted file mode 100644 index 310d5026..00000000 --- a/docs/libssh2_session_method_pref.3 +++ /dev/null @@ -1,41 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_method_pref 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_method_pref - set preferred key exchange method -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_method_pref(LIBSSH2_SESSION *session, - int method_type, const char *prefs); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fImethod_type\fP - One of the Method Type constants. - -\fIprefs\fP - Coma delimited list of preferred methods to use with -the most preferred listed first and the least preferred listed last. -If a method is listed which is not supported by libssh2 it will be -ignored and not sent to the remote host during protocol negotiation. - -Set preferred methods to be negotiated. These -preferences must be set prior to calling -.BR libssh2_session_handshake(3) -as they are used during the protocol initiation phase. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_INVAL\fP - The requested method type was invalid. - -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_METHOD_NOT_SUPPORTED\fP - The requested method is not supported. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) -.BR libssh2_session_handshake(3) diff --git a/docs/libssh2_session_method_pref.md b/docs/libssh2_session_method_pref.md new file mode 100644 index 00000000..aae83958 --- /dev/null +++ b/docs/libssh2_session_method_pref.md @@ -0,0 +1,53 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_method_pref +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_handshake(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_method_pref - set preferred key exchange method + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_method_pref(LIBSSH2_SESSION *session, + int method_type, const char *prefs); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*method_type* - One of the Method Type constants. + +*prefs* - Coma delimited list of preferred methods to use with +the most preferred listed first and the least preferred listed last. +If a method is listed which is not supported by libssh2 it will be +ignored and not sent to the remote host during protocol negotiation. + +Set preferred methods to be negotiated. These +preferences must be set prior to calling libssh2_session_handshake(3) +as they are used during the protocol initiation phase. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_INVAL* - The requested method type was invalid. + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_METHOD_NOT_SUPPORTED* - The requested method is not supported. diff --git a/docs/libssh2_session_methods.3 b/docs/libssh2_session_methods.3 deleted file mode 100644 index 5748626d..00000000 --- a/docs/libssh2_session_methods.3 +++ /dev/null @@ -1,31 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_methods 3 "8 Nov 2021" "libssh2 1.11" "libssh2" -.SH NAME -libssh2_session_methods - return the currently active algorithms -.SH SYNOPSIS -.nf -#include - -const char * -libssh2_session_methods(LIBSSH2_SESSION *session, int method_type); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fImethod_type\fP - one of the method type constants: LIBSSH2_METHOD_KEX, -LIBSSH2_METHOD_HOSTKEY, LIBSSH2_METHOD_CRYPT_CS, LIBSSH2_METHOD_CRYPT_SC, -LIBSSH2_METHOD_MAC_CS, LIBSSH2_METHOD_MAC_SC, LIBSSH2_METHOD_COMP_CS, -LIBSSH2_METHOD_COMP_SC, LIBSSH2_METHOD_LANG_CS, LIBSSH2_METHOD_LANG_SC, -LIBSSH2_METHOD_SIGN_ALGO. - -Returns the actual method negotiated for a particular transport parameter. -.SH RETURN VALUE -Negotiated method or NULL if the session has not yet been started. -.SH ERRORS -\fILIBSSH2_ERROR_INVAL\fP - The requested method type was invalid. - -\fILIBSSH2_ERROR_METHOD_NONE\fP - no method has been set -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_methods.md b/docs/libssh2_session_methods.md new file mode 100644 index 00000000..8fd03f56 --- /dev/null +++ b/docs/libssh2_session_methods.md @@ -0,0 +1,44 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_methods +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_methods - return the currently active algorithms + +# SYNOPSIS + +~~~c +#include + +const char * +libssh2_session_methods(LIBSSH2_SESSION *session, int method_type); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*method_type* - one of the method type constants: LIBSSH2_METHOD_KEX, +LIBSSH2_METHOD_HOSTKEY, LIBSSH2_METHOD_CRYPT_CS, LIBSSH2_METHOD_CRYPT_SC, +LIBSSH2_METHOD_MAC_CS, LIBSSH2_METHOD_MAC_SC, LIBSSH2_METHOD_COMP_CS, +LIBSSH2_METHOD_COMP_SC, LIBSSH2_METHOD_LANG_CS, LIBSSH2_METHOD_LANG_SC, +LIBSSH2_METHOD_SIGN_ALGO. + +Returns the actual method negotiated for a particular transport parameter. + +# RETURN VALUE + +Negotiated method or NULL if the session has not yet been started. + +# ERRORS + +*LIBSSH2_ERROR_INVAL* - The requested method type was invalid. + +*LIBSSH2_ERROR_METHOD_NONE* - no method has been set diff --git a/docs/libssh2_session_set_blocking.3 b/docs/libssh2_session_set_blocking.md similarity index 61% rename from docs/libssh2_session_set_blocking.3 rename to docs/libssh2_session_set_blocking.md index db596481..8a436324 100644 --- a/docs/libssh2_session_set_blocking.3 +++ b/docs/libssh2_session_set_blocking.md @@ -1,20 +1,31 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_set_blocking 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_set_blocking +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_session_set_blocking - set or clear blocking mode on session -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include void libssh2_session_set_blocking(LIBSSH2_SESSION *session, int blocking); -.fi -.SH DESCRIPTION -\fIsession\fP - session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIblocking\fP - Set to a non-zero value to make the channel block, or zero to +# DESCRIPTION + +*session* - session instance as returned by libssh2_session_init_ex(3) + +*blocking* - Set to a non-zero value to make the channel block, or zero to make it non-blocking. Set or clear blocking mode on the selected on the session. This will @@ -25,7 +36,7 @@ session will return immediately with an empty buffer. If a write is performed on a session with no room for more data, a blocking session will wait for room. A non-blocking session will return immediately without writing anything. -.SH RETURN VALUE + +# RETURN VALUE + None -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_set_last_error.3 b/docs/libssh2_session_set_last_error.md similarity index 50% rename from docs/libssh2_session_set_last_error.3 rename to docs/libssh2_session_set_last_error.md index 7a5bdaa9..c6f4c251 100644 --- a/docs/libssh2_session_set_last_error.3 +++ b/docs/libssh2_session_set_last_error.md @@ -1,34 +1,48 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_set_last_error 3 "26 Oct 2015" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_set_last_error +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) + - libssh2_session_last_errno(3) + - libssh2_session_last_error(3) +--- + +# NAME + libssh2_session_set_last_error - sets the internal error state -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_session_set_last_error(LIBSSH2_SESSION *session, int errcode, const char *errmsg) -.fi -.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 +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*errcode* - 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 +*errmsg* - 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 + +# RETURN VALUE + Numeric error code corresponding to the the Error Code constants. -.SH AVAILABILITY + +# AVAILABILITY + Added in 1.6.1 -.SH SEE ALSO -.BR libssh2_session_last_error(3) -.BR libssh2_session_last_errno(3) diff --git a/docs/libssh2_session_set_read_timeout.3 b/docs/libssh2_session_set_read_timeout.md similarity index 50% rename from docs/libssh2_session_set_read_timeout.3 rename to docs/libssh2_session_set_read_timeout.md index 487c2890..365b9e4a 100644 --- a/docs/libssh2_session_set_read_timeout.3 +++ b/docs/libssh2_session_set_read_timeout.md @@ -1,25 +1,39 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_set_read_timeout 3 "13 Jan 2023" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_set_read_timeout +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_get_read_timeout(3) +--- + +# NAME + libssh2_session_set_read_timeout - set timeout for packet read functions -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include void libssh2_session_set_read_timeout(LIBSSH2_SESSION *session, long timeout); -.fi -.SH DESCRIPTION -Set the \fBtimeout\fP in seconds for how long libssh2 packet read +~~~ + +# DESCRIPTION + +Set the **timeout** in seconds for how long libssh2 packet read function calls may wait until they consider the situation an error and return LIBSSH2_ERROR_TIMEOUT. By default or if you set the timeout to zero, the timeout will be set to 60 seconds. -.SH RETURN VALUE + +# RETURN VALUE + Nothing -.SH AVAILABILITY + +# AVAILABILITY + Added in 1.10.1 -.SH SEE ALSO -.BR libssh2_session_get_read_timeout(3) diff --git a/docs/libssh2_session_set_timeout.3 b/docs/libssh2_session_set_timeout.md similarity index 50% rename from docs/libssh2_session_set_timeout.3 rename to docs/libssh2_session_set_timeout.md index 27326851..cf5188ed 100644 --- a/docs/libssh2_session_set_timeout.3 +++ b/docs/libssh2_session_set_timeout.md @@ -1,25 +1,39 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_set_timeout 3 "4 May 2011" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_set_timeout +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_get_timeout(3) +--- + +# NAME + libssh2_session_set_timeout - set timeout for blocking functions -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include void libssh2_session_set_timeout(LIBSSH2_SESSION *session, long timeout); -.fi -.SH DESCRIPTION -Set the \fBtimeout\fP in milliseconds for how long a blocking the libssh2 +~~~ + +# DESCRIPTION + +Set the **timeout** in milliseconds for how long a blocking the libssh2 function calls may wait until they consider the situation an error and return LIBSSH2_ERROR_TIMEOUT. By default or if you set the timeout to zero, libssh2 has no timeout for blocking functions. -.SH RETURN VALUE + +# RETURN VALUE + Nothing -.SH AVAILABILITY + +# AVAILABILITY + Added in 1.2.9 -.SH SEE ALSO -.BR libssh2_session_get_timeout(3) diff --git a/docs/libssh2_session_startup.3 b/docs/libssh2_session_startup.3 deleted file mode 100644 index 53e95266..00000000 --- a/docs/libssh2_session_startup.3 +++ /dev/null @@ -1,45 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_startup 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_session_startup - begin transport layer -.SH SYNOPSIS -.nf -#include - -int -libssh2_session_startup(LIBSSH2_SESSION *session, int socket); -.fi -.SH DESCRIPTION -Starting in libssh2 version 1.2.8 this function is considered deprecated. Use -\fIlibssh2_session_handshake(3)\fP instead. - -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIsocket\fP - Connected socket descriptor. Typically a TCP connection -though the protocol allows for any reliable transport and the library will -attempt to use any berkeley socket. - -Begin transport layer protocol negotiation with the connected host. -.SH RETURN VALUE -Returns 0 on success, negative on failure. -.SH ERRORS -\fILIBSSH2_ERROR_SOCKET_NONE\fP - The socket is invalid. - -\fILIBSSH2_ERROR_BANNER_SEND\fP - Unable to send banner to remote host. - -\fILIBSSH2_ERROR_KEX_FAILURE\fP - Encryption key exchange with the remote -host failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_DISCONNECT\fP - The socket was disconnected. - -\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on -the socket. - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. -.SH SEE ALSO -.BR libssh2_session_free(3) -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_session_startup.md b/docs/libssh2_session_startup.md new file mode 100644 index 00000000..bbd94b01 --- /dev/null +++ b/docs/libssh2_session_startup.md @@ -0,0 +1,58 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_startup +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_free(3) + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_session_startup - begin transport layer + +# SYNOPSIS + +~~~c +#include + +int +libssh2_session_startup(LIBSSH2_SESSION *session, int socket); +~~~ + +# DESCRIPTION + +Starting in libssh2 version 1.2.8 this function is considered deprecated. Use +*libssh2_session_handshake(3)* instead. + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*socket* - Connected socket descriptor. Typically a TCP connection +though the protocol allows for any reliable transport and the library will +attempt to use any berkeley socket. + +Begin transport layer protocol negotiation with the connected host. + +# RETURN VALUE + +Returns 0 on success, negative on failure. + +# ERRORS + +*LIBSSH2_ERROR_SOCKET_NONE* - The socket is invalid. + +*LIBSSH2_ERROR_BANNER_SEND* - Unable to send banner to remote host. + +*LIBSSH2_ERROR_KEX_FAILURE* - Encryption key exchange with the remote +host failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_DISCONNECT* - The socket was disconnected. + +*LIBSSH2_ERROR_PROTO* - An invalid SSH protocol response was received on +the socket. + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would block. diff --git a/docs/libssh2_session_supported_algs.3 b/docs/libssh2_session_supported_algs.md similarity index 58% rename from docs/libssh2_session_supported_algs.3 rename to docs/libssh2_session_supported_algs.md index c17d53d5..f50dfdc1 100644 --- a/docs/libssh2_session_supported_algs.3 +++ b/docs/libssh2_session_supported_algs.md @@ -1,28 +1,42 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_session_supported_algs 3 "23 Oct 2011" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_session_supported_algs +Section: 3 +Source: libssh2 +See-also: + - libssh2_free(3) + - libssh2_session_method_pref(3) + - libssh2_session_methods(3) +--- + +# NAME + libssh2_session_supported_algs - get list of supported algorithms -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_session_supported_algs(LIBSSH2_SESSION* session, int method_type, const char*** algs); -.fi -.SH DESCRIPTION -\fIsession\fP - An instance of initialized LIBSSH2_SESSION (the function will -use its pointer to the memory allocation function). \fImethod_type\fP - -Method type. See \fIlibssh2_session_method_pref(3)\fP. \fIalgs\fP - Address +~~~ + +# DESCRIPTION + +*session* - An instance of initialized LIBSSH2_SESSION (the function will +use its pointer to the memory allocation function). *method_type* - +Method type. See *libssh2_session_method_pref(3)*. *algs* - Address of a pointer that will point to an array of returned algorithms -Get a list of supported algorithms for the given \fImethod_type\fP. The +Get a list of supported algorithms for the given *method_type*. The method_type parameter is equivalent to method_type in -\fIlibssh2_session_method_pref(3)\fP. If successful, the function will +*libssh2_session_method_pref(3)*. If successful, the function will allocate the appropriate amount of memory. When not needed anymore, it must be -deallocated by calling \fIlibssh2_free(3)\fP. When this function is +deallocated by calling *libssh2_free(3)*. When this function is unsuccessful, this must not be done. In order to get a list of all supported compression algorithms, @@ -32,8 +46,10 @@ calling this function, otherwise only "none" will be returned. If successful, the function will allocate and fill the array with supported algorithms (the same names as defined in RFC 4253). The array is not NULL terminated. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include "libssh2.h" const char **algorithms; @@ -48,9 +64,9 @@ rc = libssh2_session_supported_algs(session, if(rc > 0) { /* the call succeeded, do sth. with the list of algorithms (e.g. list them)... */ - printf("Supported symmetric algorithms:\\n"); + printf("Supported symmetric algorithms:\n"); for(i = 0; i < rc; i++) - printf("\\t%s\\n", algorithms[i]); + printf("\t%s\n", algorithms[i]); /* ... and free the allocated memory when not needed anymore */ libssh2_free(session, algorithms); @@ -58,22 +74,24 @@ if(rc > 0) { else { /* call failed, error handling */ } -.fi -.SH RETURN VALUE +~~~ + +# RETURN VALUE + On success, a number of returned algorithms (i.e a positive number will be returned). In case of a failure, an error code (a negative number, see below) is returned. 0 should never be returned. -.SH ERRORS -\fILIBSSH2_ERROR_BAD_USE\fP - Invalid address of algs. -\fILIBSSH2_ERROR_METHOD_NOT_SUPPORTED\fP - Unknown method type. +# ERRORS -\fILIBSSH2_ERROR_INVAL\fP - Internal error (normally should not occur). +*LIBSSH2_ERROR_BAD_USE* - Invalid address of algs. + +*LIBSSH2_ERROR_METHOD_NOT_SUPPORTED* - Unknown method type. + +*LIBSSH2_ERROR_INVAL* - Internal error (normally should not occur). + +*LIBSSH2_ERROR_ALLOC* - Allocation of memory failed. + +# AVAILABILITY -\fILIBSSH2_ERROR_ALLOC\fP - Allocation of memory failed. -.SH AVAILABILITY Added in 1.4.0 -.SH SEE ALSO -.BR libssh2_session_methods(3), -.BR libssh2_session_method_pref(3) -.BR libssh2_free(3) diff --git a/docs/libssh2_sftp_close.3 b/docs/libssh2_sftp_close.3 deleted file mode 100644 index bf9c4c7f..00000000 --- a/docs/libssh2_sftp_close.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_close 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_close - convenience macro for \fIlibssh2_sftp_close_handle(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_close(LIBSSH2_SFTP_HANDLE *handle); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_close_handle(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_close_handle(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_close_handle(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_close_handle(3) diff --git a/docs/libssh2_sftp_close.md b/docs/libssh2_sftp_close.md new file mode 100644 index 00000000..bc01c41d --- /dev/null +++ b/docs/libssh2_sftp_close.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_close +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_close_handle(3) +--- + +# NAME + +libssh2_sftp_close - convenience macro for *libssh2_sftp_close_handle(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_close(LIBSSH2_SFTP_HANDLE *handle); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_close_handle(3)*. + +# RETURN VALUE + +See *libssh2_sftp_close_handle(3)* + +# ERRORS + +See *libssh2_sftp_close_handle(3)* diff --git a/docs/libssh2_sftp_close_handle.3 b/docs/libssh2_sftp_close_handle.3 deleted file mode 100644 index 30794d4d..00000000 --- a/docs/libssh2_sftp_close_handle.3 +++ /dev/null @@ -1,43 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_close_handle 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_close_handle - close filehandle -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle); - -int -libssh2_sftp_close(LIBSSH2_SFTP_HANDLE *handle); - -int -libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle); -.fi -.SH DESCRIPTION -\fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP -or \fBlibssh2_sftp_opendir(3)\fP (which is a macro). - -Close an active LIBSSH2_SFTP_HANDLE. Because files and directories share the -same underlying storage mechanism these methods may be used -interchangeably. \fBlibssh2_sftp_close(3)\fP and \fBlibssh2_sftp_closedir(3)\fP -are macros for \fBlibssh2_sftp_close_handle(3)\fP. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to -be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_close_handle.md b/docs/libssh2_sftp_close_handle.md new file mode 100644 index 00000000..f39cb2e4 --- /dev/null +++ b/docs/libssh2_sftp_close_handle.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_close_handle +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) +--- + +# NAME + +libssh2_sftp_close_handle - close filehandle + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle); + +int +libssh2_sftp_close(LIBSSH2_SFTP_HANDLE *handle); + +int +libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle); +~~~ + +# DESCRIPTION + +*handle* - SFTP File Handle as returned by **libssh2_sftp_open_ex(3)** +or **libssh2_sftp_opendir(3)** (which is a macro). + +Close an active LIBSSH2_SFTP_HANDLE. Because files and directories share the +same underlying storage mechanism these methods may be used +interchangeably. **libssh2_sftp_close(3)** and **libssh2_sftp_closedir(3)** +are macros for **libssh2_sftp_close_handle(3)**. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. diff --git a/docs/libssh2_sftp_closedir.3 b/docs/libssh2_sftp_closedir.3 deleted file mode 100644 index c1913d2d..00000000 --- a/docs/libssh2_sftp_closedir.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_closedir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_closedir - convenience macro for \fIlibssh2_sftp_close_handle(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle) -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_close_handle(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_close_handle(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_close_handle(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_close_handle(3) diff --git a/docs/libssh2_sftp_closedir.md b/docs/libssh2_sftp_closedir.md new file mode 100644 index 00000000..74649098 --- /dev/null +++ b/docs/libssh2_sftp_closedir.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_closedir +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_close_handle(3) +--- + +# NAME + +libssh2_sftp_closedir - convenience macro for *libssh2_sftp_close_handle(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle) +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_close_handle(3)*. + +# RETURN VALUE + +See *libssh2_sftp_close_handle(3)* + +# ERRORS + +See *libssh2_sftp_close_handle(3)* diff --git a/docs/libssh2_sftp_fsetstat.3 b/docs/libssh2_sftp_fsetstat.3 deleted file mode 100644 index c3d8dabc..00000000 --- a/docs/libssh2_sftp_fsetstat.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_fsetstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_fsetstat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, - LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_fstat_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_fstat_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_fstat_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_fstat_ex(3) diff --git a/docs/libssh2_sftp_fsetstat.md b/docs/libssh2_sftp_fsetstat.md new file mode 100644 index 00000000..428290bb --- /dev/null +++ b/docs/libssh2_sftp_fsetstat.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_fsetstat +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_fstat_ex(3) +--- + +# NAME + +libssh2_sftp_fsetstat - convenience macro for *libssh2_sftp_fstat_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_fstat_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_fstat_ex(3)* + +# ERRORS + +See *libssh2_sftp_fstat_ex(3)* diff --git a/docs/libssh2_sftp_fstat.3 b/docs/libssh2_sftp_fstat.3 deleted file mode 100644 index b2dfacd9..00000000 --- a/docs/libssh2_sftp_fstat.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_fstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_fstat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, - LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_fstat_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_fstat_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_fstat_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_fstat_ex(3) diff --git a/docs/libssh2_sftp_fstat.md b/docs/libssh2_sftp_fstat.md new file mode 100644 index 00000000..f4c8b08b --- /dev/null +++ b/docs/libssh2_sftp_fstat.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_fstat +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_fstat_ex(3) +--- + +# NAME + +libssh2_sftp_fstat - convenience macro for *libssh2_sftp_fstat_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_fstat_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_fstat_ex(3)* + +# ERRORS + +See *libssh2_sftp_fstat_ex(3)* diff --git a/docs/libssh2_sftp_fstat_ex.3 b/docs/libssh2_sftp_fstat_ex.md similarity index 54% rename from docs/libssh2_sftp_fstat_ex.3 rename to docs/libssh2_sftp_fstat_ex.md index 65051e58..cb87421d 100644 --- a/docs/libssh2_sftp_fstat_ex.3 +++ b/docs/libssh2_sftp_fstat_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_fstat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_fstat_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) +--- + +# NAME + libssh2_sftp_fstat_ex - get or set attributes on an SFTP file handle -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -12,27 +22,30 @@ int libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat) -#define libssh2_sftp_fstat(handle, attrs) \\ +#define libssh2_sftp_fstat(handle, attrs) \ libssh2_sftp_fstat_ex((handle), (attrs), 0) -#define libssh2_sftp_fsetstat(handle, attrs) \\ +#define libssh2_sftp_fsetstat(handle, attrs) \ libssh2_sftp_fstat_ex((handle), (attrs), 1) -.fi -.SH DESCRIPTION -\fIhandle\fP - SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) +~~~ -\fIattrs\fP - Pointer to an LIBSSH2_SFTP_ATTRIBUTES structure to set file +# DESCRIPTION + +*handle* - SFTP File Handle as returned by libssh2_sftp_open_ex(3) + +*attrs* - Pointer to an LIBSSH2_SFTP_ATTRIBUTES structure to set file metadata from or into depending on the value of setstat. -\fIsetstat\fP - When non-zero, the file's metadata will be updated -with the data found in attrs according to the values of attrs->flags +*setstat* - When non-zero, the file's metadata will be updated +with the data found in attrs according to the values of attrs-\>flags and other relevant member attributes. Get or Set statbuf type data for a given LIBSSH2_SFTP_HANDLE instance. -.SH DATA TYPES + +# DATA TYPES + LIBSSH2_SFTP_ATTRIBUTES is a typedefed struct that is defined as below -.nf +~~~c struct _LIBSSH2_SFTP_ATTRIBUTES { /* If flags & ATTR_* bit is set, then the value in this @@ -54,53 +67,71 @@ struct _LIBSSH2_SFTP_ATTRIBUTES { /* access time and modified time of file */ unsigned long atime, mtime; }; -.fi +~~~ You will find a full set of defines and macros to identify flags and -permissions on the \fBlibssh2_sftp.h\fP header file, but some of the +permissions on the **libssh2_sftp.h** header file, but some of the most common ones are: To check for specific user permissions, the set of defines are in the -pattern LIBSSH2_SFTP_S_I where is R, W or X for -read, write and executable and is USR, GRP and OTH for user, +pattern LIBSSH2_SFTP_S_I\\ where \ is R, W or X for +read, write and executable and \ is USR, GRP and OTH for user, group and other. So, you check for a user readable file, use the bit -\fILIBSSH2_SFTP_S_IRUSR\fP while you want to see if it is executable -for other, you use \fILIBSSH2_SFTP_S_IXOTH\fP and so on. +*LIBSSH2_SFTP_S_IRUSR* while you want to see if it is executable +for other, you use *LIBSSH2_SFTP_S_IXOTH* and so on. To check for specific file types, you would previously (before libssh2 -1.2.5) use the standard posix S_IS***() macros, but since 1.2.5 +1.2.5) use the standard posix S_IS\*() macros, but since 1.2.5 libssh2 offers its own set of macros for this functionality: -.IP LIBSSH2_SFTP_S_ISLNK + +## LIBSSH2_SFTP_S_ISLNK + Test for a symbolic link -.IP LIBSSH2_SFTP_S_ISREG + +## LIBSSH2_SFTP_S_ISREG + Test for a regular file -.IP LIBSSH2_SFTP_S_ISDIR + +## LIBSSH2_SFTP_S_ISDIR + Test for a directory -.IP LIBSSH2_SFTP_S_ISCHR + +## LIBSSH2_SFTP_S_ISCHR + Test for a character special file -.IP LIBSSH2_SFTP_S_ISBLK + +## LIBSSH2_SFTP_S_ISBLK + Test for a block special file -.IP LIBSSH2_SFTP_S_ISFIFO + +## LIBSSH2_SFTP_S_ISFIFO + Test for a pipe or FIFO special file -.IP LIBSSH2_SFTP_S_ISSOCK + +## LIBSSH2_SFTP_S_ISSOCK + Test for a socket -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -.SH AVAILABILITY + +# AVAILABILITY + This function has been around since forever, but most of the -LIBSSH2_SFTP_S_* defines were introduced in libssh2 0.14 and the -LIBSSH2_SFTP_S_IS***() macros were introduced in libssh2 1.2.5. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) +LIBSSH2_SFTP_S_\* defines were introduced in libssh2 0.14 and the +LIBSSH2_SFTP_S_IS\*() macros were introduced in libssh2 1.2.5. diff --git a/docs/libssh2_sftp_fstatvfs.3 b/docs/libssh2_sftp_fstatvfs.3 deleted file mode 100644 index 1546b974..00000000 --- a/docs/libssh2_sftp_fstatvfs.3 +++ /dev/null @@ -1,3 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.so man3/libssh2_sftp_statvfs.3 diff --git a/docs/libssh2_sftp_statvfs.3 b/docs/libssh2_sftp_fstatvfs.md similarity index 61% rename from docs/libssh2_sftp_statvfs.3 rename to docs/libssh2_sftp_fstatvfs.md index 75b23847..e139fe6c 100644 --- a/docs/libssh2_sftp_statvfs.3 +++ b/docs/libssh2_sftp_fstatvfs.md @@ -1,10 +1,22 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_statvfs 3 "22 May 2010" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_statvfs +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) + - libssh2_sftp_open_ex(3) + - libssh2_sftp_open_ex(3) +--- + +# NAME + libssh2_sftp_statvfs, libssh2_sftp_fstatvfs - get file system statistics -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -15,27 +27,29 @@ libssh2_sftp_statvfs(LIBSSH2_SFTP *sftp, const char *path, int libssh2_sftp_fstatvfs(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_STATVFS *st) -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + These functions provide statvfs(2)-like operations and require statvfs@openssh.com and fstatvfs@openssh.com extension support on the server. -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) +*sftp* - SFTP instance as returned by -\fIhandle\fP - SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) +*handle* - SFTP File Handle as returned by -\fIpath\fP - full path of any file within the mounted file system. +*path* - full path of any file within the mounted file system. -\fIpath_len\fP - length of the full path. +*path_len* - length of the full path. -\fIst\fP - Pointer to a LIBSSH2_SFTP_STATVFS structure to place file system +*st* - Pointer to a LIBSSH2_SFTP_STATVFS structure to place file system statistics into. -.SH DATA TYPES + +# DATA TYPES + LIBSSH2_SFTP_STATVFS is a typedefed struct that is defined as below -.nf +~~~c struct _LIBSSH2_SFTP_STATVFS { libssh2_uint64_t f_bsize; /* file system block size */ libssh2_uint64_t f_frsize; /* fragment size */ @@ -49,31 +63,39 @@ struct _LIBSSH2_SFTP_STATVFS { libssh2_uint64_t f_flag; /* mount flags */ libssh2_uint64_t f_namemax; /* maximum filename length */ }; -.fi +~~~ It is unspecified whether all members of the returned struct have meaningful values on all file systems. -The field \fIf_flag\fP is a bit mask. Bits are defined as follows: -.IP LIBSSH2_SFTP_ST_RDONLY +The field *f_flag* is a bit mask. Bits are defined as follows: + +## LIBSSH2_SFTP_ST_RDONLY + Read-only file system. -.IP LIBSSH2_SFTP_ST_NOSUID -Set-user-ID/set-group-ID bits are ignored by \fBexec\fP(3). -.SH RETURN VALUE + +## LIBSSH2_SFTP_ST_NOSUID + +Set-user-ID/set-group-ID bits are ignored by **exec**(3). + +# RETURN VALUE + Returns 0 on success or negative on failure. If used in non-blocking mode, it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.2.6 -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_fsync.3 b/docs/libssh2_sftp_fsync.md similarity index 56% rename from docs/libssh2_sftp_fsync.3 rename to docs/libssh2_sftp_fsync.md index e9cf3f3f..0563ca0c 100644 --- a/docs/libssh2_sftp_fsync.3 +++ b/docs/libssh2_sftp_fsync.md @@ -1,39 +1,55 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_fsync 3 "8 Apr 2013" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_fsync +Section: 3 +Source: libssh2 +See-also: + - fsync(2) + - libssh2_sftp_open_ex(3) +--- + +# NAME + libssh2_sftp_fsync - synchronize file to disk -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include int libssh2_sftp_fsync(LIBSSH2_SFTP_HANDLE *handle) -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This function causes the remote server to synchronize the file data and metadata to disk (like fsync(2)). For this to work requires fsync@openssh.com support on the server. -\fIhandle\fP - SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) -.SH RETURN VALUE +*handle* - SFTP File Handle as returned by libssh2_sftp_open_ex(3) + +# RETURN VALUE + Returns 0 on success or negative on failure. If used in non-blocking mode, it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. In particular, this can be returned if the SSH server does not support the fsync operation: the SFTP subcode -\fILIBSSH2_FX_OP_UNSUPPORTED\fP will be returned in this case. -.SH AVAILABILITY +*LIBSSH2_FX_OP_UNSUPPORTED* will be returned in this case. + +# AVAILABILITY + Added in libssh2 1.4.4 and OpenSSH 6.3. -.SH SEE ALSO -.BR fsync(2) diff --git a/docs/libssh2_sftp_get_channel.3 b/docs/libssh2_sftp_get_channel.3 deleted file mode 100644 index 0da7cdac..00000000 --- a/docs/libssh2_sftp_get_channel.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_get_channel 3 "9 Sep 2011" "libssh2 1.4.0" "libssh2" -.SH NAME -libssh2_sftp_get_channel - return the channel of sftp -.SH SYNOPSIS -.nf -#include -#include - -LIBSSH2_CHANNEL * -libssh2_sftp_get_channel(LIBSSH2_SFTP *sftp); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) - -Return the channel of the given sftp handle. -.SH RETURN VALUE -The channel of the SFTP instance or NULL if something was wrong. -.SH AVAILABILITY -Added in 1.4.0 -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_get_channel.md b/docs/libssh2_sftp_get_channel.md new file mode 100644 index 00000000..0482b368 --- /dev/null +++ b/docs/libssh2_sftp_get_channel.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_get_channel +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + +libssh2_sftp_get_channel - return the channel of sftp + +# SYNOPSIS + +~~~c +#include +#include + +LIBSSH2_CHANNEL * +libssh2_sftp_get_channel(LIBSSH2_SFTP *sftp); +~~~ + +# DESCRIPTION + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +Return the channel of the given sftp handle. + +# RETURN VALUE + +The channel of the SFTP instance or NULL if something was wrong. + +# AVAILABILITY + +Added in 1.4.0 diff --git a/docs/libssh2_sftp_init.3 b/docs/libssh2_sftp_init.3 deleted file mode 100644 index dab613d6..00000000 --- a/docs/libssh2_sftp_init.3 +++ /dev/null @@ -1,42 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_init 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_init - open SFTP channel for the given SSH session. -.SH SYNOPSIS -.nf -#include -#include - -LIBSSH2_SFTP * -libssh2_sftp_init(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -Open a channel and initialize the SFTP subsystem. Although the SFTP subsystem -operates over the same type of channel as those exported by the Channel API, -the protocol itself implements its own unique binary packet protocol which -must be managed with the libssh2_sftp_*() family of functions. When an SFTP -session is complete, it must be destroyed using the -.BR libssh2_sftp_shutdown(3) -function. -.SH RETURN VALUE -A pointer to the newly allocated SFTP instance or NULL on failure. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to be -returned by the server. - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would -block. -.SH SEE ALSO -.BR libssh2_sftp_shutdown(3) -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_init.md b/docs/libssh2_sftp_init.md new file mode 100644 index 00000000..6446c8bb --- /dev/null +++ b/docs/libssh2_sftp_init.md @@ -0,0 +1,55 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_init +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) + - libssh2_sftp_open_ex(3) + - libssh2_sftp_shutdown(3) +--- + +# NAME + +libssh2_sftp_init - open SFTP channel for the given SSH session. + +# SYNOPSIS + +~~~c +#include +#include + +LIBSSH2_SFTP * +libssh2_sftp_init(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +Open a channel and initialize the SFTP subsystem. Although the SFTP subsystem +operates over the same type of channel as those exported by the Channel API, +the protocol itself implements its own unique binary packet protocol which +must be managed with the libssh2_sftp_*() family of functions. When an SFTP +session is complete, it must be destroyed using the libssh2_sftp_shutdown(3) +function. + +# RETURN VALUE + +A pointer to the newly allocated SFTP instance or NULL on failure. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would +block. diff --git a/docs/libssh2_sftp_last_error.3 b/docs/libssh2_sftp_last_error.md similarity index 52% rename from docs/libssh2_sftp_last_error.3 rename to docs/libssh2_sftp_last_error.md index f5993b4d..86ba0dc2 100644 --- a/docs/libssh2_sftp_last_error.3 +++ b/docs/libssh2_sftp_last_error.md @@ -1,25 +1,36 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_last_error 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_last_error +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + libssh2_sftp_last_error - return the last SFTP-specific error code -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include unsigned long libssh2_sftp_last_error(LIBSSH2_SFTP *sftp); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) +~~~ + +# DESCRIPTION + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) Returns the last error code produced by the SFTP layer. Note that this only returns a sensible error code if libssh2 returned LIBSSH2_ERROR_SFTP_PROTOCOL -in a previous call. Using \fBlibssh2_sftp_last_error(3)\fP without a +in a previous call. Using **libssh2_sftp_last_error(3)** without a preceding SFTP protocol error, it will return an unspecified value. -.SH RETURN VALUE + +# RETURN VALUE + Current error code state of the SFTP instance. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_lstat.3 b/docs/libssh2_sftp_lstat.3 deleted file mode 100644 index 8165cdb8..00000000 --- a/docs/libssh2_sftp_lstat.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_lstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_lstat - convenience macro for \fIlibssh2_sftp_stat_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_lstat(LIBSSH2_SFTP *sftp, const char *path, - LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_stat_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_stat_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_stat_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_stat_ex(3) diff --git a/docs/libssh2_sftp_lstat.md b/docs/libssh2_sftp_lstat.md new file mode 100644 index 00000000..34f8088d --- /dev/null +++ b/docs/libssh2_sftp_lstat.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_lstat +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_stat_ex(3) +--- + +# NAME + +libssh2_sftp_lstat - convenience macro for *libssh2_sftp_stat_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_lstat(LIBSSH2_SFTP *sftp, const char *path, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_stat_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_stat_ex(3)* + +# ERRORS + +See *libssh2_sftp_stat_ex(3)* diff --git a/docs/libssh2_sftp_mkdir.3 b/docs/libssh2_sftp_mkdir.3 deleted file mode 100644 index 193ec09e..00000000 --- a/docs/libssh2_sftp_mkdir.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_mkdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_mkdir - convenience macro for \fIlibssh2_sftp_mkdir_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, const char *path, - long mode); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_mkdir_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_mkdir_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_mkdir_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_mkdir_ex(3) diff --git a/docs/libssh2_sftp_mkdir.md b/docs/libssh2_sftp_mkdir.md new file mode 100644 index 00000000..1fe31700 --- /dev/null +++ b/docs/libssh2_sftp_mkdir.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_mkdir +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_mkdir_ex(3) +--- + +# NAME + +libssh2_sftp_mkdir - convenience macro for *libssh2_sftp_mkdir_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, const char *path, + long mode); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_mkdir_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_mkdir_ex(3)* + +# ERRORS + +See *libssh2_sftp_mkdir_ex(3)* diff --git a/docs/libssh2_sftp_mkdir_ex.3 b/docs/libssh2_sftp_mkdir_ex.3 deleted file mode 100644 index 3e5759dc..00000000 --- a/docs/libssh2_sftp_mkdir_ex.3 +++ /dev/null @@ -1,48 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_mkdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_mkdir_ex - create a directory on the remote file system -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp, - const char *path, unsigned int path_len, - long mode); - -int -libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, - const char *path, - long mode); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) - -\fIpath\fP - full path of the new directory to create. Note that the new -directory's parents must all exist prior to making this call. - -\fIpath_len\fP - length of the full path of the new directory to create. - -\fImode\fP - directory creation mode (e.g. 0755). - -Create a directory on the remote file system. -.SH RETURN VALUE -Return 0 on success or negative on failure. -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to be -returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_mkdir_ex.md b/docs/libssh2_sftp_mkdir_ex.md new file mode 100644 index 00000000..d9066c18 --- /dev/null +++ b/docs/libssh2_sftp_mkdir_ex.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_mkdir_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) + - libssh2_sftp_open_ex(3) +--- + +# NAME + +libssh2_sftp_mkdir_ex - create a directory on the remote file system + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp, + const char *path, unsigned int path_len, + long mode); + +int +libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, + const char *path, + long mode); +~~~ + +# DESCRIPTION + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*path* - full path of the new directory to create. Note that the new +directory's parents must all exist prior to making this call. + +*path_len* - length of the full path of the new directory to create. + +*mode* - directory creation mode (e.g. 0755). + +Create a directory on the remote file system. + +# RETURN VALUE + +Return 0 on success or negative on failure. +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. diff --git a/docs/libssh2_sftp_open.3 b/docs/libssh2_sftp_open.3 deleted file mode 100644 index 7918b506..00000000 --- a/docs/libssh2_sftp_open.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_open 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_open - convenience macro for \fIlibssh2_sftp_open_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -LIBSSH2_SFTP_HANDLE * -libssh2_sftp_open(LIBSSH2_SFTP *sftp, const char *filename, - unsigned long flags, - long mode); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_open_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_open_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_open_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_open.md b/docs/libssh2_sftp_open.md new file mode 100644 index 00000000..7cb08f69 --- /dev/null +++ b/docs/libssh2_sftp_open.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_open +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) +--- + +# NAME + +libssh2_sftp_open - convenience macro for *libssh2_sftp_open_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +LIBSSH2_SFTP_HANDLE * +libssh2_sftp_open(LIBSSH2_SFTP *sftp, const char *filename, + unsigned long flags, + long mode); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_open_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_open_ex(3)* + +# ERRORS + +See *libssh2_sftp_open_ex(3)* diff --git a/docs/libssh2_sftp_open_ex.3 b/docs/libssh2_sftp_open_ex.md similarity index 52% rename from docs/libssh2_sftp_open_ex.3 rename to docs/libssh2_sftp_open_ex.md index f0dced8c..a3f7a992 100644 --- a/docs/libssh2_sftp_open_ex.3 +++ b/docs/libssh2_sftp_open_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_open_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_open_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_close_handle(3) +--- + +# NAME + libssh2_sftp_open_ex - open filehandle for file on SFTP. -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -14,56 +24,70 @@ libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned long flags, long mode, int open_type); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by \fIlibssh2_sftp_init(3)\fP +~~~ -\fIfilename\fP - Remote file/directory resource to open +# DESCRIPTION -\fIfilename_len\fP - Length of filename +*sftp* - SFTP instance as returned by *libssh2_sftp_init(3)* + +*filename* - Remote file/directory resource to open + +*filename_len* - Length of filename + +*flags* - Any reasonable combination of the LIBSSH2_FXF_* constants: + +## LIBSSH2_FXF_READ -\fIflags\fP - Any reasonable combination of the LIBSSH2_FXF_* constants: -.RS -.IP LIBSSH2_FXF_READ Open the file for reading. -.IP LIBSSH2_FXF_WRITE + +## LIBSSH2_FXF_WRITE + Open the file for writing. If both this and LIBSSH2_FXF_READ are specified, the file is opened for both reading and writing. -.IP LIBSSH2_FXF_APPEND + +## LIBSSH2_FXF_APPEND + Force all writes to append data at the end of the file. -.IP LIBSSH2_FXF_CREAT, + +## LIBSSH2_FXF_CREAT, + If this flag is specified, then a new file will be created if one does not already exist (if LIBSSH2_FXF_TRUNC is specified, the new file will be truncated to zero length if it previously exists) -.IP LIBSSH2_FXF_TRUNC + +## LIBSSH2_FXF_TRUNC + Forces an existing file with the same name to be truncated to zero length when creating a file by specifying LIBSSH2_FXF_CREAT. LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. -.IP LIBSSH2_FXF_EXCL + +## LIBSSH2_FXF_EXCL + Causes the request to fail if the named file already exists. LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. -.RE -\fImode\fP - POSIX file permissions to assign if the file is being newly -created. See the LIBSSH2_SFTP_S_* convenience defines in +*mode* - POSIX file permissions to assign if the file is being newly +created. See the LIBSSH2_SFTP_S_\* convenience defines in \ -\fIopen_type\fP - Either of LIBSSH2_SFTP_OPENFILE (to open a file) or +*open_type* - Either of LIBSSH2_SFTP_OPENFILE (to open a file) or LIBSSH2_SFTP_OPENDIR (to open a directory). -.SH RETURN VALUE + +# RETURN VALUE + A pointer to the newly created LIBSSH2_SFTP_HANDLE instance or NULL on failure. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would block. -.SH SEE ALSO -.BR libssh2_sftp_close_handle(3) diff --git a/docs/libssh2_sftp_open_ex_r.3 b/docs/libssh2_sftp_open_ex_r.md similarity index 52% rename from docs/libssh2_sftp_open_ex_r.3 rename to docs/libssh2_sftp_open_ex_r.md index 11bb6c17..21bb4c47 100644 --- a/docs/libssh2_sftp_open_ex_r.3 +++ b/docs/libssh2_sftp_open_ex_r.md @@ -1,10 +1,21 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_open_ex_r 3 "10 Apr 2023" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_open_ex_r +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_close_handle(3) + - libssh2_sftp_fstat_ex(3) +--- + +# NAME + libssh2_sftp_open_ex_r - open filehandle for file on SFTP. -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -15,63 +26,77 @@ libssh2_sftp_open_ex_r(LIBSSH2_SFTP *sftp, const char *filename, long mode, int open_type, LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by \fIlibssh2_sftp_init(3)\fP +~~~ -\fIfilename\fP - Remote file/directory resource to open +# DESCRIPTION -\fIfilename_len\fP - Length of filename +*sftp* - SFTP instance as returned by *libssh2_sftp_init(3)* + +*filename* - Remote file/directory resource to open + +*filename_len* - Length of filename + +*flags* - Any reasonable combination of the LIBSSH2_FXF_* constants: + +## LIBSSH2_FXF_READ -\fIflags\fP - Any reasonable combination of the LIBSSH2_FXF_* constants: -.RS -.IP LIBSSH2_FXF_READ Open the file for reading. -.IP LIBSSH2_FXF_WRITE + +## LIBSSH2_FXF_WRITE + Open the file for writing. If both this and LIBSSH2_FXF_READ are specified, the file is opened for both reading and writing. -.IP LIBSSH2_FXF_APPEND + +## LIBSSH2_FXF_APPEND + Force all writes to append data at the end of the file. -.IP LIBSSH2_FXF_CREAT, + +## LIBSSH2_FXF_CREAT, + If this flag is specified, then a new file will be created if one does not already exist (if LIBSSH2_FXF_TRUNC is specified, the new file will be truncated to zero length if it previously exists) -.IP LIBSSH2_FXF_TRUNC + +## LIBSSH2_FXF_TRUNC + Forces an existing file with the same name to be truncated to zero length when creating a file by specifying LIBSSH2_FXF_CREAT. LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. -.IP LIBSSH2_FXF_EXCL + +## LIBSSH2_FXF_EXCL + Causes the request to fail if the named file already exists. LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. -.RE -\fImode\fP - POSIX file permissions to assign if the file is being newly -created. See the LIBSSH2_SFTP_S_* convenience defines in +*mode* - POSIX file permissions to assign if the file is being newly +created. See the LIBSSH2_SFTP_S_\* convenience defines in \ -\fIopen_type\fP - Either of LIBSSH2_SFTP_OPENFILE (to open a file) or +*open_type* - Either of LIBSSH2_SFTP_OPENFILE (to open a file) or LIBSSH2_SFTP_OPENDIR (to open a directory). -\fIattrs\fP - Pointer to LIBSSH2_SFTP_ATTRIBUTES struct. See +*attrs* - Pointer to LIBSSH2_SFTP_ATTRIBUTES struct. See libssh2_sftp_fstat_ex for detailed usage. -.SH RETURN VALUE +# RETURN VALUE + A pointer to the newly created LIBSSH2_SFTP_HANDLE instance or NULL on failure. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call would block. -.SH AVAILABILITY + +# AVAILABILITY + Added in libssh2 1.11.0 -.SH SEE ALSO -.BR libssh2_sftp_close_handle(3) -.BR libssh2_sftp_fstat_ex(3) diff --git a/docs/libssh2_sftp_open_r.3 b/docs/libssh2_sftp_open_r.3 deleted file mode 100644 index 2627c9d7..00000000 --- a/docs/libssh2_sftp_open_r.3 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_open_r 3 "10 Apr 2023" "libssh2 1.11.0" "libssh2" -.SH NAME -libssh2_sftp_open_r - convenience macro for \fIlibssh2_sftp_open_ex_r(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -LIBSSH2_SFTP_HANDLE * -libssh2_sftp_open_r(LIBSSH2_SFTP *sftp, const char *filename, - unsigned long flags, - long mode, - LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_open_ex_r(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_open_ex_r(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_open_ex_r(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_open_ex_r(3) diff --git a/docs/libssh2_sftp_open_r.md b/docs/libssh2_sftp_open_r.md new file mode 100644 index 00000000..b0d1c707 --- /dev/null +++ b/docs/libssh2_sftp_open_r.md @@ -0,0 +1,39 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_open_r +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex_r(3) +--- + +# NAME + +libssh2_sftp_open_r - convenience macro for *libssh2_sftp_open_ex_r(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +LIBSSH2_SFTP_HANDLE * +libssh2_sftp_open_r(LIBSSH2_SFTP *sftp, const char *filename, + unsigned long flags, + long mode, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_open_ex_r(3)*. + +# RETURN VALUE + +See *libssh2_sftp_open_ex_r(3)* + +# ERRORS + +See *libssh2_sftp_open_ex_r(3)* diff --git a/docs/libssh2_sftp_opendir.3 b/docs/libssh2_sftp_opendir.3 deleted file mode 100644 index fbba5948..00000000 --- a/docs/libssh2_sftp_opendir.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_opendir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_opendir - convenience macro for \fIlibssh2_sftp_open_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -LIBSSH2_SFTP_HANDLE * -libssh2_sftp_opendir(LIBSSH2_SFTP *sftp, const char *path); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_open_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_open_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_open_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_opendir.md b/docs/libssh2_sftp_opendir.md new file mode 100644 index 00000000..7798345b --- /dev/null +++ b/docs/libssh2_sftp_opendir.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_opendir +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) +--- + +# NAME + +libssh2_sftp_opendir - convenience macro for *libssh2_sftp_open_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +LIBSSH2_SFTP_HANDLE * +libssh2_sftp_opendir(LIBSSH2_SFTP *sftp, const char *path); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_open_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_open_ex(3)* + +# ERRORS + +See *libssh2_sftp_open_ex(3)* diff --git a/docs/libssh2_sftp_posix_rename.3 b/docs/libssh2_sftp_posix_rename.3 deleted file mode 100644 index 95cbd4de..00000000 --- a/docs/libssh2_sftp_posix_rename.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_posix_rename 3 "9 May 2024" "libssh2 1.11.1" "libssh2" -.SH NAME -libssh2_sftp_rename - convenience macro for \fIlibssh2_sftp_posix_rename_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_posix_rename(LIBSSH2_SFTP *sftp, - const char *source_filename, - const char *destination_filename); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_posix_rename_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_posix_rename_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_posix_rename_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_posix_rename_ex(3) diff --git a/docs/libssh2_sftp_posix_rename.md b/docs/libssh2_sftp_posix_rename.md new file mode 100644 index 00000000..59385e34 --- /dev/null +++ b/docs/libssh2_sftp_posix_rename.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_posix_rename +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_posix_rename_ex(3) +--- + +# NAME + +libssh2_sftp_rename - convenience macro for *libssh2_sftp_posix_rename_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_posix_rename(LIBSSH2_SFTP *sftp, + const char *source_filename, + const char *destination_filename); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_posix_rename_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_posix_rename_ex(3)* + +# ERRORS + +See *libssh2_sftp_posix_rename_ex(3)* diff --git a/docs/libssh2_sftp_posix_rename_ex.3 b/docs/libssh2_sftp_posix_rename_ex.md similarity index 57% rename from docs/libssh2_sftp_posix_rename_ex.3 rename to docs/libssh2_sftp_posix_rename_ex.md index 03b6c39f..9d1acdc5 100644 --- a/docs/libssh2_sftp_posix_rename_ex.3 +++ b/docs/libssh2_sftp_posix_rename_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_posix_rename_ex 3 "9 May 2024" "libssh2 1.11.1" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_posix_rename_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + libssh2_sftp_posix_rename_ex - rename an SFTP file using POSIX semantics -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -14,19 +24,20 @@ libssh2_sftp_posix_rename_ex(LIBSSH2_SFTP *sftp, size_t source_filename_len, const char *dest_filename, size_t dest_filename_len); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) +~~~ -\fIsourcefile\fP - Path and name of the existing filesystem entry +# DESCRIPTION -\fIsourcefile_len\fP - Length of the path and name of the existing +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*sourcefile* - Path and name of the existing filesystem entry + +*sourcefile_len* - Length of the path and name of the existing filesystem entry -\fIdestfile\fP - Path and name of the target filesystem entry +*destfile* - Path and name of the target filesystem entry -\fIdestfile_len\fP - Length of the path and name of the target +*destfile_len* - Length of the path and name of the target filesystem entry This function implements the posix-rename@openssh.com extension, which is @@ -37,22 +48,24 @@ will attempt to user hard links when moving files using SSH_FXP_RENAME. If the server does not support posix-rename@openssh.com, this function will return LIBSSH2_FX_OP_UNSUPPORTED and you can call libssh2_sftp_rename_ex (3) as a backup. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_FX_OP_UNSUPPORTED\fP - Server does not support + +# ERRORS + +*LIBSSH2_FX_OP_UNSUPPORTED* - Server does not support posix-rename@openssh.com -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_read.3 b/docs/libssh2_sftp_read.3 deleted file mode 100644 index 86df3e2b..00000000 --- a/docs/libssh2_sftp_read.3 +++ /dev/null @@ -1,47 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_read 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_read - read data from an SFTP handle -.SH SYNOPSIS -.nf -#include -#include - -ssize_t -libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle, - char *buffer, size_t buffer_maxlen); -.fi -.SH DESCRIPTION -\fIhandle\fP is the SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) - -\fIbuffer\fP is a pointer to a pre-allocated buffer of at least - -\fIbuffer_maxlen\fP bytes to read data into. - -Reads a block of data from an LIBSSH2_SFTP_HANDLE. This method is modelled -after the POSIX -.BR read(2) -function and uses the same calling semantics. -.BR libssh2_sftp_read(3) -will attempt to read as much as possible however it may not fill all of buffer -if the file pointer reaches the end or if further reads would cause the socket -to block. -.SH RETURN VALUE -Number of bytes actually populated into buffer, or negative on failure. -It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to be -returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) -.BR libssh2_sftp_read(3) diff --git a/docs/libssh2_sftp_read.md b/docs/libssh2_sftp_read.md new file mode 100644 index 00000000..4190b26f --- /dev/null +++ b/docs/libssh2_sftp_read.md @@ -0,0 +1,59 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_read +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) + - libssh2_sftp_read(3) + - read(2) +--- + +# NAME + +libssh2_sftp_read - read data from an SFTP handle + +# SYNOPSIS + +~~~c +#include +#include + +ssize_t +libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle, + char *buffer, size_t buffer_maxlen); +~~~ + +# DESCRIPTION + +*handle* is the SFTP File Handle as returned by libssh2_sftp_open_ex(3) + +*buffer* is a pointer to a pre-allocated buffer of at least + +*buffer_maxlen* bytes to read data into. + +Reads a block of data from an LIBSSH2_SFTP_HANDLE. This method is modelled +after the POSIX read(2) +function and uses the same calling semantics. libssh2_sftp_read(3) +will attempt to read as much as possible however it may not fill all of buffer +if the file pointer reaches the end or if further reads would cause the socket +to block. + +# RETURN VALUE + +Number of bytes actually populated into buffer, or negative on failure. +It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. diff --git a/docs/libssh2_sftp_readdir.3 b/docs/libssh2_sftp_readdir.3 deleted file mode 100644 index 9764a8b0..00000000 --- a/docs/libssh2_sftp_readdir.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_readdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_readdir - convenience macro for \fIlibssh2_sftp_readdir_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, - char *buffer, size_t buffer_maxlen, - LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_readdir_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_readdir_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_readdir_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_readdir_ex(3) diff --git a/docs/libssh2_sftp_readdir.md b/docs/libssh2_sftp_readdir.md new file mode 100644 index 00000000..ee962395 --- /dev/null +++ b/docs/libssh2_sftp_readdir.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_readdir +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_readdir_ex(3) +--- + +# NAME + +libssh2_sftp_readdir - convenience macro for *libssh2_sftp_readdir_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, + char *buffer, size_t buffer_maxlen, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_readdir_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_readdir_ex(3)* + +# ERRORS + +See *libssh2_sftp_readdir_ex(3)* diff --git a/docs/libssh2_sftp_readdir_ex.3 b/docs/libssh2_sftp_readdir_ex.md similarity index 57% rename from docs/libssh2_sftp_readdir_ex.3 rename to docs/libssh2_sftp_readdir_ex.md index ef8d7576..23971c57 100644 --- a/docs/libssh2_sftp_readdir_ex.3 +++ b/docs/libssh2_sftp_readdir_ex.md @@ -1,10 +1,21 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_readdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_readdir_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_close_handle(3) + - libssh2_sftp_open_ex(3) +--- + +# NAME + libssh2_sftp_readdir_ex - read directory data from an SFTP handle -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -13,56 +24,60 @@ libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, char *longentry, size_t longentry_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Reads a block of data from a LIBSSH2_SFTP_HANDLE and returns file entry information for the next entry, if any. -\fIhandle\fP - is the SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) +*handle* - is the SFTP File Handle as returned by libssh2_sftp_open_ex(3) -\fIbuffer\fP - is a pointer to a pre-allocated buffer of at least -\fIbuffer_maxlen\fP bytes to read data into. +*buffer* - is a pointer to a pre-allocated buffer of at least +*buffer_maxlen* bytes to read data into. -\fIbuffer_maxlen\fP - is the length of buffer in bytes. If the length of the +*buffer_maxlen* - is the length of buffer in bytes. If the length of the filename is longer than the space provided by buffer_maxlen it will be truncated to fit. -\fIlongentry\fP - is a pointer to a pre-allocated buffer of at least -\fIlongentry_maxlen\fP bytes to read data into. The format of the `longname' +*longentry* - is a pointer to a pre-allocated buffer of at least +*longentry_maxlen* bytes to read data into. The format of the `longname' field is unspecified by SFTP protocol. It MUST be suitable for use in the output of a directory listing command (in fact, the recommended operation for a directory listing command is to display this data). -\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length of +*longentry_maxlen* - is the length of longentry in bytes. If the length of the full directory entry is longer than the space provided by -\fIlongentry_maxlen\fP it will be truncated to fit. +*longentry_maxlen* it will be truncated to fit. -\fIattrs\fP - is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate +*attrs* - is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate statbuf style data into. -.SH RETURN VALUE + +# RETURN VALUE + Number of bytes actually populated into buffer (not counting the terminating zero), or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH BUG + +# BUG + Passing in a too small buffer for 'buffer' or 'longentry' when receiving data only results in libssh2 1.2.7 or earlier to not copy the entire data amount, and it is not possible for the application to tell when it happens! -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if any of the given 'buffer' or 'longentry' buffers are too small to fit the requested object name. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3), -.BR libssh2_sftp_close_handle(3) diff --git a/docs/libssh2_sftp_readlink.3 b/docs/libssh2_sftp_readlink.3 deleted file mode 100644 index f48da0c1..00000000 --- a/docs/libssh2_sftp_readlink.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_readlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_readlink - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP -.SH SYNOPSIS -.nf -#include -#include - -#define libssh2_sftp_readlink(sftp, path, target, maxlen) \\ - libssh2_sftp_symlink_ex((sftp), (path), strlen(path), \\ - (target), (maxlen), \\ - LIBSSH2_SFTP_READLINK) -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_symlink_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_symlink_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_symlink_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_symlink_ex(3) diff --git a/docs/libssh2_sftp_readlink.md b/docs/libssh2_sftp_readlink.md new file mode 100644 index 00000000..ee982b94 --- /dev/null +++ b/docs/libssh2_sftp_readlink.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_readlink +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_symlink_ex(3) +--- + +# NAME + +libssh2_sftp_readlink - convenience macro for *libssh2_sftp_symlink_ex(3)* + +# SYNOPSIS + +~~~c +#include +#include + +#define libssh2_sftp_readlink(sftp, path, target, maxlen) \ + libssh2_sftp_symlink_ex((sftp), (path), strlen(path), \ + (target), (maxlen), \ + LIBSSH2_SFTP_READLINK) +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_symlink_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_symlink_ex(3)* + +# ERRORS + +See *libssh2_sftp_symlink_ex(3)* diff --git a/docs/libssh2_sftp_realpath.3 b/docs/libssh2_sftp_realpath.3 deleted file mode 100644 index 1685622d..00000000 --- a/docs/libssh2_sftp_realpath.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_realpath 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_realpath - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP -.SH SYNOPSIS -.nf -#include -#include - -#define libssh2_sftp_realpath(sftp, path, target, maxlen) \\ - libssh2_sftp_symlink_ex((sftp), (path), strlen(path), \\ - (target), (maxlen), \\ - LIBSSH2_SFTP_REALPATH) -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_symlink_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_symlink_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_symlink_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_symlink_ex(3) diff --git a/docs/libssh2_sftp_realpath.md b/docs/libssh2_sftp_realpath.md new file mode 100644 index 00000000..11d5cfa1 --- /dev/null +++ b/docs/libssh2_sftp_realpath.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_realpath +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_symlink_ex(3) +--- + +# NAME + +libssh2_sftp_realpath - convenience macro for *libssh2_sftp_symlink_ex(3)* + +# SYNOPSIS + +~~~c +#include +#include + +#define libssh2_sftp_realpath(sftp, path, target, maxlen) \ + libssh2_sftp_symlink_ex((sftp), (path), strlen(path), \ + (target), (maxlen), \ + LIBSSH2_SFTP_REALPATH) +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_symlink_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_symlink_ex(3)* + +# ERRORS + +See *libssh2_sftp_symlink_ex(3)* diff --git a/docs/libssh2_sftp_rename.3 b/docs/libssh2_sftp_rename.3 deleted file mode 100644 index 7207780b..00000000 --- a/docs/libssh2_sftp_rename.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_rename 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_rename - convenience macro for \fIlibssh2_sftp_rename_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_rename(LIBSSH2_SFTP *sftp, - const char *source_filename, - const char *destination_filename); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_rename_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_rename_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_rename_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_rename_ex(3) diff --git a/docs/libssh2_sftp_rename.md b/docs/libssh2_sftp_rename.md new file mode 100644 index 00000000..24a2c737 --- /dev/null +++ b/docs/libssh2_sftp_rename.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_rename +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_rename_ex(3) +--- + +# NAME + +libssh2_sftp_rename - convenience macro for *libssh2_sftp_rename_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_rename(LIBSSH2_SFTP *sftp, + const char *source_filename, + const char *destination_filename); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_rename_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_rename_ex(3)* + +# ERRORS + +See *libssh2_sftp_rename_ex(3)* diff --git a/docs/libssh2_sftp_rename_ex.3 b/docs/libssh2_sftp_rename_ex.md similarity index 61% rename from docs/libssh2_sftp_rename_ex.3 rename to docs/libssh2_sftp_rename_ex.md index 8feb4d21..a532e015 100644 --- a/docs/libssh2_sftp_rename_ex.3 +++ b/docs/libssh2_sftp_rename_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_rename_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_rename_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + libssh2_sftp_rename_ex - rename an SFTP file -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -20,22 +30,23 @@ int libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename, const char *dest_filename); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) +~~~ -\fIsourcefile\fP - Path and name of the existing filesystem entry +# DESCRIPTION -\fIsourcefile_len\fP - Length of the path and name of the existing +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*sourcefile* - Path and name of the existing filesystem entry + +*sourcefile_len* - Length of the path and name of the existing filesystem entry -\fIdestfile\fP - Path and name of the target filesystem entry +*destfile* - Path and name of the target filesystem entry -\fIdestfile_len\fP - Length of the path and name of the target +*destfile_len* - Length of the path and name of the target filesystem entry -\fIflags\fP - +*flags* - Bitmask flags made up of LIBSSH2_SFTP_RENAME_* constants. Rename a filesystem object on the remote filesystem. The semantics of @@ -45,19 +56,21 @@ flag is not set and the destfile entry already exists, the operation will fail. Use of the other two flags indicate a preference (but not a requirement) for the remote end to perform an atomic rename operation and/or using native system calls when possible. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_rewind.3 b/docs/libssh2_sftp_rewind.3 deleted file mode 100644 index 5e4ddde4..00000000 --- a/docs/libssh2_sftp_rewind.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_rewind 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_rewind - convenience macro for \fIlibssh2_sftp_seek64(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_rewind(LIBSSH2_SFTP_HANDLE *handle); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_seek64(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_seek64(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_seek64(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_seek64(3) diff --git a/docs/libssh2_sftp_rewind.md b/docs/libssh2_sftp_rewind.md new file mode 100644 index 00000000..83cee66d --- /dev/null +++ b/docs/libssh2_sftp_rewind.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_rewind +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_seek64(3) +--- + +# NAME + +libssh2_sftp_rewind - convenience macro for *libssh2_sftp_seek64(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_rewind(LIBSSH2_SFTP_HANDLE *handle); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_seek64(3)*. + +# RETURN VALUE + +See *libssh2_sftp_seek64(3)* + +# ERRORS + +See *libssh2_sftp_seek64(3)* diff --git a/docs/libssh2_sftp_rmdir.3 b/docs/libssh2_sftp_rmdir.3 deleted file mode 100644 index 523534ac..00000000 --- a/docs/libssh2_sftp_rmdir.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_rmdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_rmdir - convenience macro for \fIlibssh2_sftp_rmdir_ex(3)\fP -.SH SYNOPSIS -.nf -#include -#include - -#define libssh2_sftp_rmdir(sftp, path) \\ - libssh2_sftp_rmdir_ex((sftp), (path), strlen(path)) -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_rmdir_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_rmdir_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_rmdir_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_rmdir_ex(3) diff --git a/docs/libssh2_sftp_rmdir.md b/docs/libssh2_sftp_rmdir.md new file mode 100644 index 00000000..cfbbd757 --- /dev/null +++ b/docs/libssh2_sftp_rmdir.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_rmdir +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_rmdir_ex(3) +--- + +# NAME + +libssh2_sftp_rmdir - convenience macro for *libssh2_sftp_rmdir_ex(3)* + +# SYNOPSIS + +~~~c +#include +#include + +#define libssh2_sftp_rmdir(sftp, path) \ + libssh2_sftp_rmdir_ex((sftp), (path), strlen(path)) +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_rmdir_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_rmdir_ex(3)* + +# ERRORS + +See *libssh2_sftp_rmdir_ex(3)* diff --git a/docs/libssh2_sftp_rmdir_ex.3 b/docs/libssh2_sftp_rmdir_ex.3 deleted file mode 100644 index 79a73bfa..00000000 --- a/docs/libssh2_sftp_rmdir_ex.3 +++ /dev/null @@ -1,40 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_rmdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_rmdir_ex - remove an SFTP directory -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path, - unsigned int path_len); -.fi -.SH DESCRIPTION -Remove a directory from the remote file system. - -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) - -\fIsourcefile\fP - Full path of the existing directory to remove. - -\fIsourcefile_len\fP - Length of the full path of the existing directory to -remove. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to -be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_rmdir_ex.md b/docs/libssh2_sftp_rmdir_ex.md new file mode 100644 index 00000000..bc90c03a --- /dev/null +++ b/docs/libssh2_sftp_rmdir_ex.md @@ -0,0 +1,53 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_rmdir_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + +libssh2_sftp_rmdir_ex - remove an SFTP directory + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path, + unsigned int path_len); +~~~ + +# DESCRIPTION + +Remove a directory from the remote file system. + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*sourcefile* - Full path of the existing directory to remove. + +*sourcefile_len* - Length of the full path of the existing directory to +remove. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. diff --git a/docs/libssh2_sftp_seek.3 b/docs/libssh2_sftp_seek.md similarity index 52% rename from docs/libssh2_sftp_seek.3 rename to docs/libssh2_sftp_seek.md index 87782de1..766ec90c 100644 --- a/docs/libssh2_sftp_seek.3 +++ b/docs/libssh2_sftp_seek.md @@ -1,30 +1,39 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_seek 3 "22 Dec 2008" "libssh2 1.0" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_seek +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) + - libssh2_sftp_seek64(3) +--- + +# NAME + libssh2_sftp_seek - set the read/write position indicator within a file -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset); -.fi -.SH DESCRIPTION -Deprecated function. Use \fIlibssh2_sftp_seek64(3)\fP instead! +~~~ -\fIhandle\fP - SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) +# DESCRIPTION -\fIoffset\fP - Number of bytes from the beginning of file to seek to. +Deprecated function. Use *libssh2_sftp_seek64(3)* instead! + +*handle* - SFTP File Handle as returned by libssh2_sftp_open_ex(3) + +*offset* - Number of bytes from the beginning of file to seek to. Move the file handle's internal pointer to an arbitrary location. Note that libssh2 implements file pointers as a localized concept to make file access appear more POSIX like. No packets are exchanged with the server during a seek operation. The localized file pointer is used as a convenience offset during read/write operations. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3), -.BR libssh2_sftp_seek64(3) diff --git a/docs/libssh2_sftp_seek64.3 b/docs/libssh2_sftp_seek64.md similarity index 63% rename from docs/libssh2_sftp_seek64.3 rename to docs/libssh2_sftp_seek64.md index d40cc84b..0c1232ca 100644 --- a/docs/libssh2_sftp_seek64.3 +++ b/docs/libssh2_sftp_seek64.md @@ -1,22 +1,33 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_seek64 3 "22 Dec 2008" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_seek64 +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) +--- + +# NAME + libssh2_sftp_seek64 - set the read/write position within a file -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle, libssh2_uint64_t offset); -.fi -.SH DESCRIPTION -\fIhandle\fP - SFTP File Handle as returned by -.BR libssh2_sftp_open_ex(3) +~~~ -\fIoffset\fP - Number of bytes from the beginning of file to seek to. +# DESCRIPTION + +*handle* - SFTP File Handle as returned by libssh2_sftp_open_ex(3) + +*offset* - Number of bytes from the beginning of file to seek to. Move the file handle's internal pointer to an arbitrary location. libssh2 implements file pointers as a localized concept to make file access appear @@ -27,7 +38,7 @@ read/write operations. You MUST NOT seek during writing or reading a file with SFTP, as the internals use outstanding packets and changing the "file position" during transit will results in badness. -.SH AVAILABILITY + +# AVAILABILITY + Added in 1.0 -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sftp_setstat.3 b/docs/libssh2_sftp_setstat.3 deleted file mode 100644 index 3bd42f5f..00000000 --- a/docs/libssh2_sftp_setstat.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_setstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_setstat - convenience macro for \fIlibssh2_sftp_stat_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_setstat(LIBSSH2_SFTP *sftp, const char *path, - LIBSSH2_SFTP_ATTRIBUTES *attr); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_stat_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_stat_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_stat_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_stat_ex(3) diff --git a/docs/libssh2_sftp_setstat.md b/docs/libssh2_sftp_setstat.md new file mode 100644 index 00000000..ad87d655 --- /dev/null +++ b/docs/libssh2_sftp_setstat.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_setstat +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_stat_ex(3) +--- + +# NAME + +libssh2_sftp_setstat - convenience macro for *libssh2_sftp_stat_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_setstat(LIBSSH2_SFTP *sftp, const char *path, + LIBSSH2_SFTP_ATTRIBUTES *attr); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_stat_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_stat_ex(3)* + +# ERRORS + +See *libssh2_sftp_stat_ex(3)* diff --git a/docs/libssh2_sftp_shutdown.3 b/docs/libssh2_sftp_shutdown.md similarity index 56% rename from docs/libssh2_sftp_shutdown.3 rename to docs/libssh2_sftp_shutdown.md index d0f097ba..8c0df888 100644 --- a/docs/libssh2_sftp_shutdown.3 +++ b/docs/libssh2_sftp_shutdown.md @@ -1,25 +1,36 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_shutdown 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_shutdown +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + libssh2_sftp_shutdown - shut down an SFTP session -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include int libssh2_sftp_shutdown(LIBSSH2_SFTP *sftp); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) +~~~ + +# DESCRIPTION + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) Destroys a previously initialized SFTP session and frees all resources associated with it. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_stat.3 b/docs/libssh2_sftp_stat.3 deleted file mode 100644 index 30e28a24..00000000 --- a/docs/libssh2_sftp_stat.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_stat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_stat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_stat(LIBSSH2_SFTP *sftp, const char *path, - LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_fstat_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_fstat_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_fstat_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_fstat_ex(3) diff --git a/docs/libssh2_sftp_stat.md b/docs/libssh2_sftp_stat.md new file mode 100644 index 00000000..2252da91 --- /dev/null +++ b/docs/libssh2_sftp_stat.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_stat +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_fstat_ex(3) +--- + +# NAME + +libssh2_sftp_stat - convenience macro for *libssh2_sftp_fstat_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_stat(LIBSSH2_SFTP *sftp, const char *path, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_fstat_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_fstat_ex(3)* + +# ERRORS + +See *libssh2_sftp_fstat_ex(3)* diff --git a/docs/libssh2_sftp_stat_ex.3 b/docs/libssh2_sftp_stat_ex.md similarity index 51% rename from docs/libssh2_sftp_stat_ex.3 rename to docs/libssh2_sftp_stat_ex.md index 3ba536e0..b63dcedc 100644 --- a/docs/libssh2_sftp_stat_ex.3 +++ b/docs/libssh2_sftp_stat_ex.md @@ -1,10 +1,22 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_stat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_stat_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) + - libssh2_sftp_lstat(3) + - libssh2_sftp_stat(3) +--- + +# NAME + libssh2_sftp_stat_ex - get status about an SFTP file -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -12,40 +24,38 @@ int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, int stat_type, LIBSSH2_SFTP_ATTRIBUTES *attrs); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) +~~~ -\fIpath\fP - Remote filesystem object to stat/lstat/setstat. +# DESCRIPTION -\fIpath_len\fP - Length of the name of the remote filesystem object +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*path* - Remote filesystem object to stat/lstat/setstat. + +*path_len* - Length of the name of the remote filesystem object to stat/lstat/setstat. -\fIstat_type\fP - One of the three constants specifying the type of +*stat_type* - One of the three constants specifying the type of stat operation to perform: -.br -\fBLIBSSH2_SFTP_STAT\fP: performs stat(2) operation -.br -\fBLIBSSH2_SFTP_LSTAT\fP: performs lstat(2) operation -.br -\fBLIBSSH2_SFTP_SETSTAT\fP: performs operation to set stat info on file +**LIBSSH2_SFTP_STAT**: performs stat(2) operation -\fIattrs\fP - Pointer to a \fBLIBSSH2_SFTP_ATTRIBUTES\fP structure to set file +**LIBSSH2_SFTP_LSTAT**: performs lstat(2) operation + +**LIBSSH2_SFTP_SETSTAT**: performs operation to set stat info on file + +*attrs* - Pointer to a **LIBSSH2_SFTP_ATTRIBUTES** structure to set file metadata from or into depending on the value of stat_type. Get or Set statbuf type data on a remote filesystem object. When getting -statbuf data, -.BR libssh2_sftp_stat(3) -will follow all symlinks, while -.BR libssh2_sftp_lstat(3) +statbuf data, libssh2_sftp_stat(3) +will follow all symlinks, while libssh2_sftp_lstat(3) will return data about the object encountered, even if that object happens to be a symlink. The LIBSSH2_SFTP_ATTRIBUTES struct looks like this: -.nf +~~~c struct LIBSSH2_SFTP_ATTRIBUTES { /* If flags & ATTR_* bit is set, then the value in this struct will be * meaningful Otherwise it should be ignored @@ -59,20 +69,22 @@ struct LIBSSH2_SFTP_ATTRIBUTES { unsigned long atime; unsigned long mtime; }; -.fi -.SH RETURN VALUE +~~~ + +# RETURN VALUE + Returns 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_statvfs.md b/docs/libssh2_sftp_statvfs.md new file mode 100644 index 00000000..b3a79e6c --- /dev/null +++ b/docs/libssh2_sftp_statvfs.md @@ -0,0 +1,100 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_statvfs +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) + - libssh2_sftp_open_ex(3) +--- + +# NAME + +libssh2_sftp_statvfs, libssh2_sftp_fstatvfs - get file system statistics + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_statvfs(LIBSSH2_SFTP *sftp, const char *path, + size_t path_len, LIBSSH2_SFTP_STATVFS *st); + +int +libssh2_sftp_fstatvfs(LIBSSH2_SFTP_HANDLE *handle, + LIBSSH2_SFTP_STATVFS *st) +~~~ + +# DESCRIPTION + +These functions provide statvfs(2)-like operations and require +statvfs@openssh.com and fstatvfs@openssh.com extension support on the server. + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*handle* - SFTP File Handle as returned by libssh2_sftp_open_ex(3) + +*path* - full path of any file within the mounted file system. + +*path_len* - length of the full path. + +*st* - Pointer to a LIBSSH2_SFTP_STATVFS structure to place file system +statistics into. + +# DATA TYPES + +LIBSSH2_SFTP_STATVFS is a typedefed struct that is defined as below + +~~~c +struct _LIBSSH2_SFTP_STATVFS { + libssh2_uint64_t f_bsize; /* file system block size */ + libssh2_uint64_t f_frsize; /* fragment size */ + libssh2_uint64_t f_blocks; /* size of fs in f_frsize units */ + libssh2_uint64_t f_bfree; /* # free blocks */ + libssh2_uint64_t f_bavail; /* # free blocks for non-root */ + libssh2_uint64_t f_files; /* # inodes */ + libssh2_uint64_t f_ffree; /* # free inodes */ + libssh2_uint64_t f_favail; /* # free inodes for non-root */ + libssh2_uint64_t f_fsid; /* file system ID */ + libssh2_uint64_t f_flag; /* mount flags */ + libssh2_uint64_t f_namemax; /* maximum filename length */ +}; +~~~ + +It is unspecified whether all members of the returned struct have meaningful +values on all file systems. + +The field *f_flag* is a bit mask. Bits are defined as follows: + +## LIBSSH2_SFTP_ST_RDONLY + +Read-only file system. + +## LIBSSH2_SFTP_ST_NOSUID + +Set-user-ID/set-group-ID bits are ignored by **exec**(3). + +# RETURN VALUE + +Returns 0 on success or negative on failure. If used in non-blocking mode, it +returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be returned +by the server. + +# AVAILABILITY + +Added in libssh2 1.2.6 diff --git a/docs/libssh2_sftp_symlink.3 b/docs/libssh2_sftp_symlink.3 deleted file mode 100644 index 8fb70df0..00000000 --- a/docs/libssh2_sftp_symlink.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_symlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_symlink - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP -.SH SYNOPSIS -.nf -#include -#include - -#define libssh2_sftp_symlink(sftp, orig, linkpath) \\ - libssh2_sftp_symlink_ex((sftp), (orig), strlen(orig), (linkpath), \\ - strlen(linkpath), LIBSSH2_SFTP_SYMLINK) -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_symlink_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_symlink_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_symlink_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_symlink_ex(3) diff --git a/docs/libssh2_sftp_symlink.md b/docs/libssh2_sftp_symlink.md new file mode 100644 index 00000000..0ff19b42 --- /dev/null +++ b/docs/libssh2_sftp_symlink.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_symlink +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_symlink_ex(3) +--- + +# NAME + +libssh2_sftp_symlink - convenience macro for *libssh2_sftp_symlink_ex(3)* + +# SYNOPSIS + +~~~c +#include +#include + +#define libssh2_sftp_symlink(sftp, orig, linkpath) \ + libssh2_sftp_symlink_ex((sftp), (orig), strlen(orig), (linkpath), \ + strlen(linkpath), LIBSSH2_SFTP_SYMLINK) +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_symlink_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_symlink_ex(3)* + +# ERRORS + +See *libssh2_sftp_symlink_ex(3)* diff --git a/docs/libssh2_sftp_symlink_ex.3 b/docs/libssh2_sftp_symlink_ex.3 deleted file mode 100644 index e4dad4be..00000000 --- a/docs/libssh2_sftp_symlink_ex.3 +++ /dev/null @@ -1,81 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_symlink_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_symlink_ex - read or set a symbolic link -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path, - unsigned int path_len, char *target, - unsigned int target_len, int link_type); -.fi -.SH DESCRIPTION -Create a symlink or read out symlink information from the remote side. - -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) - -\fIpath\fP - Remote filesystem object to create a symlink from or resolve. - -\fIpath_len\fP - Length of the name of the remote filesystem object to -create a symlink from or resolve. - -\fItarget\fP - a pointer to a buffer. The buffer has different uses depending -what the \fIlink_type\fP argument is set to. -.br -\fBLIBSSH2_SFTP_SYMLINK\fP: Remote filesystem object to link to. -.br -\fBLIBSSH2_SFTP_READLINK\fP: Pre-allocated buffer to resolve symlink target -into. -.br -\fBLIBSSH2_SFTP_REALPATH\fP: Pre-allocated buffer to resolve realpath target -into. - -\fItarget_len\fP - Length of the name of the remote filesystem target object. - -\fIlink_type\fP - One of the three previously mentioned constants which -determines the resulting behavior of this function. - -These are convenience macros: - -.BR libssh2_sftp_symlink(3) -: Create a symbolic link between two filesystem objects. -.br -.BR libssh2_sftp_readlink(3) -: Resolve a symbolic link filesystem object to its next target. -.br -.BR libssh2_sftp_realpath(3) -: Resolve a complex, relative, or symlinked filepath to its effective target. -.SH RETURN VALUE -When using LIBSSH2_SFTP_SYMLINK, this function returns 0 on success or negative -on failure. - -When using LIBSSH2_SFTP_READLINK or LIBSSH2_SFTP_REALPATH, it returns the -number of bytes it copied to the target buffer (not including the terminating -zero) or negative on failure. - -It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. - -From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if the given 'target' -buffer is too small to fit the requested object name. -.SH BUG -Passing in a too small buffer when receiving data only results in libssh2 -1.2.7 or earlier to not copy the entire data amount, and it is not possible -for the application to tell when it happens! -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to -be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_symlink_ex.md b/docs/libssh2_sftp_symlink_ex.md new file mode 100644 index 00000000..6608cd61 --- /dev/null +++ b/docs/libssh2_sftp_symlink_ex.md @@ -0,0 +1,96 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_symlink_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) + - libssh2_sftp_readlink(3) + - libssh2_sftp_realpath(3) + - libssh2_sftp_symlink(3) +--- + +# NAME + +libssh2_sftp_symlink_ex - read or set a symbolic link + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path, + unsigned int path_len, char *target, + unsigned int target_len, int link_type); +~~~ + +# DESCRIPTION + +Create a symlink or read out symlink information from the remote side. + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*path* - Remote filesystem object to create a symlink from or resolve. + +*path_len* - Length of the name of the remote filesystem object to +create a symlink from or resolve. + +*target* - a pointer to a buffer. The buffer has different uses depending +what the *link_type* argument is set to. + +**LIBSSH2_SFTP_SYMLINK**: Remote filesystem object to link to. + +**LIBSSH2_SFTP_READLINK**: Pre-allocated buffer to resolve symlink target +into. + +**LIBSSH2_SFTP_REALPATH**: Pre-allocated buffer to resolve realpath target +into. + +*target_len* - Length of the name of the remote filesystem target object. + +*link_type* - One of the three previously mentioned constants which +determines the resulting behavior of this function. + +These are convenience macros: + +libssh2_sftp_symlink(3): Create a symbolic link between two filesystem objects. + +libssh2_sftp_readlink(3): Resolve a symbolic link filesystem object to its next target. + +libssh2_sftp_realpath(3): Resolve a complex, relative, or symlinked filepath to its effective target. + +# RETURN VALUE + +When using LIBSSH2_SFTP_SYMLINK, this function returns 0 on success or negative +on failure. + +When using LIBSSH2_SFTP_READLINK or LIBSSH2_SFTP_REALPATH, it returns the +number of bytes it copied to the target buffer (not including the terminating +zero) or negative on failure. + +It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if the given 'target' +buffer is too small to fit the requested object name. + +# BUG + +Passing in a too small buffer when receiving data only results in libssh2 +1.2.7 or earlier to not copy the entire data amount, and it is not possible +for the application to tell when it happens! + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. diff --git a/docs/libssh2_sftp_tell.3 b/docs/libssh2_sftp_tell.3 deleted file mode 100644 index 88b65370..00000000 --- a/docs/libssh2_sftp_tell.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_tell 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_tell - get the current read/write position indicator for a file -.SH SYNOPSIS -.nf -#include -#include - -size_t -libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); -.fi -.SH DESCRIPTION -\fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP. - -Returns the current offset of the file handle's internal pointer. Note that -this is now deprecated. Use the newer \fBlibssh2_sftp_tell64(3)\fP instead! -.SH RETURN VALUE -Current offset from beginning of file in bytes. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3), -.BR libssh2_sftp_tell64(3) diff --git a/docs/libssh2_sftp_tell.md b/docs/libssh2_sftp_tell.md new file mode 100644 index 00000000..db658962 --- /dev/null +++ b/docs/libssh2_sftp_tell.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_tell +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) + - libssh2_sftp_tell64(3) +--- + +# NAME + +libssh2_sftp_tell - get the current read/write position indicator for a file + +# SYNOPSIS + +~~~c +#include +#include + +size_t +libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); +~~~ + +# DESCRIPTION + +*handle* - SFTP File Handle as returned by **libssh2_sftp_open_ex(3)**. + +Returns the current offset of the file handle's internal pointer. Note that +this is now deprecated. Use the newer **libssh2_sftp_tell64(3)** instead! + +# RETURN VALUE + +Current offset from beginning of file in bytes. diff --git a/docs/libssh2_sftp_tell64.3 b/docs/libssh2_sftp_tell64.3 deleted file mode 100644 index 013e7dad..00000000 --- a/docs/libssh2_sftp_tell64.3 +++ /dev/null @@ -1,24 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_tell64 3 "22 Dec 2008" "libssh2 1.0" "libssh2" -.SH NAME -libssh2_sftp_tell64 - get the current read/write position indicator for a file -.SH SYNOPSIS -.nf -#include -#include - -libssh2_uint64_t -libssh2_sftp_tell64(LIBSSH2_SFTP_HANDLE *handle); -.fi -.SH DESCRIPTION -\fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP - -Identify the current offset of the file handle's internal pointer. -.SH RETURN VALUE -Current offset from beginning of file in bytes. -.SH AVAILABILITY -Added in libssh2 1.0 -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3), -.BR libssh2_sftp_tell(3) diff --git a/docs/libssh2_sftp_tell64.md b/docs/libssh2_sftp_tell64.md new file mode 100644 index 00000000..0389eea7 --- /dev/null +++ b/docs/libssh2_sftp_tell64.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_tell64 +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) + - libssh2_sftp_tell(3) +--- + +# NAME + +libssh2_sftp_tell64 - get the current read/write position indicator for a file + +# SYNOPSIS + +~~~c +#include +#include + +libssh2_uint64_t +libssh2_sftp_tell64(LIBSSH2_SFTP_HANDLE *handle); +~~~ + +# DESCRIPTION + +*handle* - SFTP File Handle as returned by **libssh2_sftp_open_ex(3)** + +Identify the current offset of the file handle's internal pointer. + +# RETURN VALUE + +Current offset from beginning of file in bytes. + +# AVAILABILITY + +Added in libssh2 1.0 diff --git a/docs/libssh2_sftp_unlink.3 b/docs/libssh2_sftp_unlink.3 deleted file mode 100644 index da4874c1..00000000 --- a/docs/libssh2_sftp_unlink.3 +++ /dev/null @@ -1,22 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_unlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_sftp_unlink - convenience macro for \fIlibssh2_sftp_unlink_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, const char *filename); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_sftp_unlink_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_sftp_unlink_ex(3)\fP -.SH ERRORS -See \fIlibssh2_sftp_unlink_ex(3)\fP -.SH SEE ALSO -.BR libssh2_sftp_unlink_ex(3) diff --git a/docs/libssh2_sftp_unlink.md b/docs/libssh2_sftp_unlink.md new file mode 100644 index 00000000..029aafa9 --- /dev/null +++ b/docs/libssh2_sftp_unlink.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_unlink +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_unlink_ex(3) +--- + +# NAME + +libssh2_sftp_unlink - convenience macro for *libssh2_sftp_unlink_ex(3)* calls + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, const char *filename); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_sftp_unlink_ex(3)*. + +# RETURN VALUE + +See *libssh2_sftp_unlink_ex(3)* + +# ERRORS + +See *libssh2_sftp_unlink_ex(3)* diff --git a/docs/libssh2_sftp_unlink_ex.3 b/docs/libssh2_sftp_unlink_ex.3 deleted file mode 100644 index e92df5f6..00000000 --- a/docs/libssh2_sftp_unlink_ex.3 +++ /dev/null @@ -1,42 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_unlink_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_sftp_unlink_ex - unlink an SFTP file -.SH SYNOPSIS -.nf -#include -#include - -int -libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned int filename_len); - -int -libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, const char *filename); -.fi -.SH DESCRIPTION -\fIsftp\fP - SFTP instance as returned by -.BR libssh2_sftp_init(3) - -\fIfilename\fP - Path and name of the existing filesystem entry - -\fIfilename_len\fP - Length of the path and name of the existing -filesystem entry - -Unlink (delete) a file from the remote filesystem. -.SH RETURN VALUE -Return 0 on success or negative on failure. It returns -LIBSSH2_ERROR_EAGAIN when it would otherwise block. While -LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - - -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was -received on the socket, or an SFTP operation caused an errorcode to -be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_init(3) diff --git a/docs/libssh2_sftp_unlink_ex.md b/docs/libssh2_sftp_unlink_ex.md new file mode 100644 index 00000000..6e32255f --- /dev/null +++ b/docs/libssh2_sftp_unlink_ex.md @@ -0,0 +1,55 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_unlink_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_init(3) +--- + +# NAME + +libssh2_sftp_unlink_ex - unlink an SFTP file + +# SYNOPSIS + +~~~c +#include +#include + +int +libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned int filename_len); + +int +libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, const char *filename); +~~~ + +# DESCRIPTION + +*sftp* - SFTP instance as returned by libssh2_sftp_init(3) + +*filename* - Path and name of the existing filesystem entry + +*filename_len* - Length of the path and name of the existing +filesystem entry + +Unlink (delete) a file from the remote filesystem. + +# RETURN VALUE + +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. diff --git a/docs/libssh2_sftp_write.3 b/docs/libssh2_sftp_write.md similarity index 70% rename from docs/libssh2_sftp_write.3 rename to docs/libssh2_sftp_write.md index 81802216..fc478fb9 100644 --- a/docs/libssh2_sftp_write.3 +++ b/docs/libssh2_sftp_write.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sftp_write 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sftp_write +Section: 3 +Source: libssh2 +See-also: + - libssh2_sftp_open_ex(3) +--- + +# NAME + libssh2_sftp_write - write SFTP data -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include #include @@ -12,24 +22,28 @@ ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, const char *buffer, size_t count); -.fi -.SH DESCRIPTION -\fBlibssh2_sftp_write(3)\fP writes a block of data to the SFTP server. This +~~~ + +# DESCRIPTION + +**libssh2_sftp_write(3)** writes a block of data to the SFTP server. This method is modeled after the POSIX write() function and uses the same calling semantics. -\fIhandle\fP - SFTP file handle as returned by \fIlibssh2_sftp_open_ex(3)\fP. +*handle* - SFTP file handle as returned by *libssh2_sftp_open_ex(3)*. -\fIbuffer\fP - points to the data to send off. +*buffer* - points to the data to send off. -\fIcount\fP - Number of bytes from 'buffer' to write. Note that it may not be +*count* - Number of bytes from 'buffer' to write. Note that it may not be possible to write all bytes as requested. -\fIlibssh2_sftp_handle(3)\fP will use as much as possible of the buffer and +*libssh2_sftp_handle(3)* will use as much as possible of the buffer and put it into a single SFTP protocol packet. This means that to get maximum performance when sending larger files, you should try to always pass in at least 32K of data to this function. -.SH WRITE AHEAD + +# WRITE AHEAD + Starting in libssh2 version 1.2.8, the default behavior of libssh2 is to create several smaller outgoing packets for all data you pass to this function and it will return a positive number as soon as the first packet is @@ -50,7 +64,9 @@ The reason for this funny behavior is that SFTP can only send 32K data in each packet and it gets all packets acked individually. This means we cannot use a simple serial approach if we want to reach high performance even on high latency connections. And we want that. -.SH RETURN VALUE + +# RETURN VALUE + Actual number of bytes written or negative on failure. If used in non-blocking mode, it returns LIBSSH2_ERROR_EAGAIN when it would @@ -59,15 +75,15 @@ really a failure per se. If this function returns 0 (zero) it should not be considered an error, but that there was no error but yet no payload data got sent to the other end. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_SFTP_PROTOCOL* - An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server. -.SH SEE ALSO -.BR libssh2_sftp_open_ex(3) diff --git a/docs/libssh2_sign_sk.3 b/docs/libssh2_sign_sk.md similarity index 51% rename from docs/libssh2_sign_sk.3 rename to docs/libssh2_sign_sk.md index 57b742b1..3a69425a 100644 --- a/docs/libssh2_sign_sk.3 +++ b/docs/libssh2_sign_sk.md @@ -1,10 +1,21 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_sign_sk 3 "1 Jun 2022" "libssh2 1.10.0" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_sign_sk +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) + - libssh2_userauth_publickey_sk(3) +--- + +# NAME + libssh2_sign_sk - Create a signature from a FIDO2 authenticator. -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -24,21 +35,22 @@ typedef struct _LIBSSH2_PRIVKEY_SK { LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback)); void **orig_abstract; } LIBSSH2_PRIVKEY_SK; -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIsig\fP - A pointer to a buffer in which to place the signature. The caller +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*sig* - A pointer to a buffer in which to place the signature. The caller is responsible for freeing the signature with LIBSSH2_FREE. -\fIsig_len\fP - A pointer to the length of the sig parameter. +*sig_len* - A pointer to the length of the sig parameter. -\fIdata\fP - The data to sign. +*data* - The data to sign. -\fIdata_len\fP - The length of the data parameter. +*data_len* - The length of the data parameter. -\fIabstract\fP - A pointer to a pointer to a LIBSSH2_PRIVKEY_SK. See +*abstract* - A pointer to a pointer to a LIBSSH2_PRIVKEY_SK. See description below. Create a signature from a FIDO2 authenticator, using either the @@ -49,39 +61,38 @@ The abstract parameter is a pointer to a pointer due to the internal workings of libssh2. The LIBSSH2_PRIVKEY_SK must be completely filled out, and the caller is responsible for all memory management of its fields. -\fIalgorithm\fP - The signing algorithm to use. Possible values are +*algorithm* - The signing algorithm to use. Possible values are LIBSSH2_HOSTKEY_TYPE_ED25519 and LIBSSH2_HOSTKEY_TYPE_ECDSA_256. -\fIflags\fP - A bitmask specifying options for the authenticator. When +*flags* - A bitmask specifying options for the authenticator. When LIBSSH2_SK_PRESENCE_REQUIRED is set, the authenticator requires a touch. When LIBSSH2_SK_VERIFICATION_REQUIRED is set, the authenticator requires a PIN. Many servers and authenticators do not work properly when LIBSSH2_SK_PRESENCE_REQUIRED is not set. -\fIapplication\fP - A user-defined string to use as the RP name for the +*application* - A user-defined string to use as the RP name for the authenticator. Usually "ssh:". -\fIkey_handle\fP - The key handle to use for the authenticator's allow list. +*key_handle* - The key handle to use for the authenticator's allow list. -\fIhandle_len\fP - The length of the key_handle parameter. +*handle_len* - The length of the key_handle parameter. -\fIabstract\fP - User-defined data. When a PIN is required, use this to pass in +*abstract* - User-defined data. When a PIN is required, use this to pass in the PIN, or a function pointer to retrieve the PIN. -\fIkey_handle\fP The decoded key handle from the private key file. +*key_handle* The decoded key handle from the private key file. -\fIhandle_len\fP The length of the key_handle parameter. +*handle_len* The length of the key_handle parameter. -\fIsign_callback\fP - Responsible for communicating with the hardware +*sign_callback* - Responsible for communicating with the hardware authenticator to generate a signature. On success, the signature information -must be placed in the `\fIsig_info\fP sig_info parameter and the callback must -return 0. On failure, it should return a negative number. See -.BR libssh2_userauth_publickey_sk(3) - for more information. +must be placed in the *sig_info* sig_info parameter and the callback must +return 0. On failure, it should return a negative number. +See libssh2_userauth_publickey_sk(3) for more information. -\fIorig_abstract\fP - User-defined data. When a PIN is required, use this to +*orig_abstract* - User-defined data. When a PIN is required, use this to pass in the PIN, or a function pointer to retrieve the PIN. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. -.SH SEE ALSO -.BR libssh2_userauth_publickey_sk(3) diff --git a/docs/libssh2_trace.3 b/docs/libssh2_trace.md similarity index 55% rename from docs/libssh2_trace.3 rename to docs/libssh2_trace.md index ee42250d..2ed81ac1 100644 --- a/docs/libssh2_trace.3 +++ b/docs/libssh2_trace.md @@ -1,41 +1,70 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_trace 3 "26 Dec 2008" "libssh2 1.0" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_trace +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_trace - enable debug info from inside libssh2 -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int libssh2_trace(LIBSSH2_SESSION *session, int bitmask); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This is a function present in the library that can be used to get debug info from within libssh2 when it is running. Helpful when trying to trace or debug behaviors. Note that this function has no effect unless libssh2 was built to support tracing! It is usually disabled in release builds. -\fBbitmask\fP can be set to the logical OR of none, one or more of these: -.RS -.IP LIBSSH2_TRACE_SOCKET +**bitmask** can be set to the logical OR of none, one or more of these: + +## LIBSSH2_TRACE_SOCKET + Socket low-level debugging -.IP LIBSSH2_TRACE_TRANS + +## LIBSSH2_TRACE_TRANS + Transport layer debugging -.IP LIBSSH2_TRACE_KEX + +## LIBSSH2_TRACE_KEX + Key exchange debugging -.IP LIBSSH2_TRACE_AUTH + +## LIBSSH2_TRACE_AUTH + Authentication debugging -.IP LIBSSH2_TRACE_CONN + +## LIBSSH2_TRACE_CONN + Connection layer debugging -.IP LIBSSH2_TRACE_SCP + +## LIBSSH2_TRACE_SCP + SCP debugging -.IP LIBSSH2_TRACE_SFTP + +## LIBSSH2_TRACE_SFTP + SFTP debugging -.IP LIBSSH2_TRACE_ERROR + +## LIBSSH2_TRACE_ERROR + Error debugging -.IP LIBSSH2_TRACE_PUBLICKEY + +## LIBSSH2_TRACE_PUBLICKEY + Public Key debugging -.RE -.SH RETURN VALUE + +# RETURN VALUE + Currently always 0, no error. diff --git a/docs/libssh2_trace_sethandler.3 b/docs/libssh2_trace_sethandler.md similarity index 76% rename from docs/libssh2_trace_sethandler.3 rename to docs/libssh2_trace_sethandler.md index 453d468a..db8a54f5 100644 --- a/docs/libssh2_trace_sethandler.3 +++ b/docs/libssh2_trace_sethandler.md @@ -1,10 +1,19 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_trace_sethandler 3 "15 Jan 2010" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_trace_sethandler +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_trace_sethandler - set a trace output handler -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include typedef void (*libssh2_trace_handler_func)(LIBSSH2_SESSION *session, @@ -16,8 +25,10 @@ int libssh2_trace_sethandler(LIBSSH2_SESSION *session, void *context, libssh2_trace_handler_func callback); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + libssh2_trace_sethandler installs a trace output handler for your application. By default, when tracing has been switched on via a call to libssh2_trace(), all output is written to stderr. By calling this method and passing a @@ -27,6 +38,8 @@ capture the trace output and put it into a log file or diagnostic window. This function has no effect unless libssh2 was built to support this option, and a typical "release build" might not. -\fBcontext\fP can be used to pass arbitrary user defined data back into the callback when invoked. -.SH AVAILABILITY +**context** can be used to pass arbitrary user defined data back into the callback when invoked. + +# AVAILABILITY + Added in libssh2 version 1.2.3 diff --git a/docs/libssh2_userauth_authenticated.3 b/docs/libssh2_userauth_authenticated.3 deleted file mode 100644 index 11568c46..00000000 --- a/docs/libssh2_userauth_authenticated.3 +++ /dev/null @@ -1,21 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_authenticated 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_userauth_authenticated - return authentication status -.SH SYNOPSIS -.nf -#include - -int -libssh2_userauth_authenticated(LIBSSH2_SESSION *session); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -Indicates whether or not the named session has been successfully authenticated. -.SH RETURN VALUE -Returns 1 if authenticated and 0 if not. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_userauth_authenticated.md b/docs/libssh2_userauth_authenticated.md new file mode 100644 index 00000000..0092e631 --- /dev/null +++ b/docs/libssh2_userauth_authenticated.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_authenticated +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_userauth_authenticated - return authentication status + +# SYNOPSIS + +~~~c +#include + +int +libssh2_userauth_authenticated(LIBSSH2_SESSION *session); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +Indicates whether or not the named session has been successfully authenticated. + +# RETURN VALUE + +Returns 1 if authenticated and 0 if not. diff --git a/docs/libssh2_userauth_banner.3 b/docs/libssh2_userauth_banner.3 deleted file mode 100644 index 1369fa5f..00000000 --- a/docs/libssh2_userauth_banner.3 +++ /dev/null @@ -1,33 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_banner 3 "1 Jun 2021" "libssh2 1.9.0" "libssh2" -.SH NAME -libssh2_userauth_banner - get the server's userauth banner message -.SH SYNOPSIS -.nf -#include - -int -libssh2_userauth_banner(LIBSSH2_SESSION *session, char **banner); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIbanner\fP - Should point to a pointer that gets filled with banner message. - -After an authentication has been attempted, such as a -\fBSSH_USERAUTH_NONE\fP request sent by -.BR libssh2_userauth_list(3) , -this function can be called to retrieve the userauth banner sent by -the server. If no such banner is sent, or if an authentication has not -yet been attempted, returns LIBSSH2_ERROR_MISSING_USERAUTH_BANNER. -.SH RETURN VALUE -On success returns 0 and an UTF-8 NUL-terminated string is stored in the -\fIbanner\fP. This string is internally managed by libssh2 and will be -deallocated upon session termination. -On failure returns -LIBSSH2_ERROR_MISSING_USERAUTH_BANNER. -.SH SEE ALSO -.BR libssh2_session_init_ex(3), -.BR libssh2_userauth_list(3) diff --git a/docs/libssh2_userauth_banner.md b/docs/libssh2_userauth_banner.md new file mode 100644 index 00000000..3ec6d94c --- /dev/null +++ b/docs/libssh2_userauth_banner.md @@ -0,0 +1,42 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_banner +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) + - libssh2_userauth_list(3) +--- + +# NAME + +libssh2_userauth_banner - get the server's userauth banner message + +# SYNOPSIS + +~~~c +#include + +int +libssh2_userauth_banner(LIBSSH2_SESSION *session, char **banner); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*banner* - Should point to a pointer that gets filled with banner message. + +After an authentication has been attempted, such as a +**SSH_USERAUTH_NONE** request sent by *libssh2_userauth_list(3)* +this function can be called to retrieve the userauth banner sent by +the server. If no such banner is sent, or if an authentication has not +yet been attempted, returns **LIBSSH2_ERROR_MISSING_USERAUTH_BANNER**. + +# RETURN VALUE + +On success returns 0 and an UTF-8 NUL-terminated string is stored in the +*banner*. This string is internally managed by libssh2 and will be +deallocated upon session termination. +On failure returns **LIBSSH2_ERROR_MISSING_USERAUTH_BANNER**. diff --git a/docs/libssh2_userauth_hostbased_fromfile.3 b/docs/libssh2_userauth_hostbased_fromfile.3 deleted file mode 100644 index e29880f0..00000000 --- a/docs/libssh2_userauth_hostbased_fromfile.3 +++ /dev/null @@ -1,26 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_hostbased_fromfile 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_userauth_hostbased_fromfile - convenience macro for \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_userauth_hostbased_fromfile(LIBSSH2_SESSION *session, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase, - const char *hostname); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP -.SH ERRORS -See \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP -.SH SEE ALSO -.BR libssh2_userauth_hostbased_fromfile_ex(3) diff --git a/docs/libssh2_userauth_hostbased_fromfile.md b/docs/libssh2_userauth_hostbased_fromfile.md new file mode 100644 index 00000000..9121c9ce --- /dev/null +++ b/docs/libssh2_userauth_hostbased_fromfile.md @@ -0,0 +1,40 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_hostbased_fromfile +Section: 3 +Source: libssh2 +See-also: + - libssh2_userauth_hostbased_fromfile_ex(3) +--- + +# NAME + +libssh2_userauth_hostbased_fromfile - convenience macro for *libssh2_userauth_hostbased_fromfile_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_userauth_hostbased_fromfile(LIBSSH2_SESSION *session, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase, + const char *hostname); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_userauth_hostbased_fromfile_ex(3)*. + +# RETURN VALUE + +See *libssh2_userauth_hostbased_fromfile_ex(3)* + +# ERRORS + +See *libssh2_userauth_hostbased_fromfile_ex(3)* diff --git a/docs/libssh2_userauth_hostbased_fromfile_ex.3 b/docs/libssh2_userauth_hostbased_fromfile_ex.3 deleted file mode 100644 index c37f5561..00000000 --- a/docs/libssh2_userauth_hostbased_fromfile_ex.3 +++ /dev/null @@ -1,12 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_hostbased_fromfile_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_userauth_hostbased_fromfile_ex - TODO -.SH SYNOPSIS -.nf -.fi -.SH DESCRIPTION -.SH RETURN VALUE -.SH ERRORS -.SH SEE ALSO diff --git a/docs/libssh2_userauth_hostbased_fromfile_ex.md b/docs/libssh2_userauth_hostbased_fromfile_ex.md new file mode 100644 index 00000000..e9579dea --- /dev/null +++ b/docs/libssh2_userauth_hostbased_fromfile_ex.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_hostbased_fromfile_ex +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_userauth_hostbased_fromfile_ex - TODO + +# SYNOPSIS + +~~~c +~~~ + +# DESCRIPTION + +# RETURN VALUE + +# ERRORS diff --git a/docs/libssh2_userauth_keyboard_interactive.3 b/docs/libssh2_userauth_keyboard_interactive.3 deleted file mode 100644 index 902cc5d2..00000000 --- a/docs/libssh2_userauth_keyboard_interactive.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_keyboard_interactive 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_userauth_keyboard_interactive - convenience macro for \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_userauth_keyboard_interactive(LIBSSH2_SESSION* session, - const char *username, - LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC((*response_callback))); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP -.SH ERRORS -See \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP -.SH SEE ALSO -.BR libssh2_userauth_keyboard_interactive_ex(3) diff --git a/docs/libssh2_userauth_keyboard_interactive.md b/docs/libssh2_userauth_keyboard_interactive.md new file mode 100644 index 00000000..a8a4b3a1 --- /dev/null +++ b/docs/libssh2_userauth_keyboard_interactive.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_keyboard_interactive +Section: 3 +Source: libssh2 +See-also: + - libssh2_userauth_keyboard_interactive_ex(3) +--- + +# NAME + +libssh2_userauth_keyboard_interactive - convenience macro for *libssh2_userauth_keyboard_interactive_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_userauth_keyboard_interactive(LIBSSH2_SESSION* session, + const char *username, + LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC((*response_callback))); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_userauth_keyboard_interactive_ex(3)*. + +# RETURN VALUE + +See *libssh2_userauth_keyboard_interactive_ex(3)* + +# ERRORS + +See *libssh2_userauth_keyboard_interactive_ex(3)* diff --git a/docs/libssh2_userauth_keyboard_interactive_ex.3 b/docs/libssh2_userauth_keyboard_interactive_ex.md similarity index 66% rename from docs/libssh2_userauth_keyboard_interactive_ex.3 rename to docs/libssh2_userauth_keyboard_interactive_ex.md index 91b0e72e..6d4d37f3 100644 --- a/docs/libssh2_userauth_keyboard_interactive_ex.3 +++ b/docs/libssh2_userauth_keyboard_interactive_ex.md @@ -1,11 +1,21 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_keyboard_interactive_ex 3 "8 Mar 2008" "libssh2 0.19" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_keyboard_interactive_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_userauth_keyboard_interactive_ex - authenticate a session using keyboard-interactive authentication -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -13,24 +23,26 @@ libssh2_userauth_keyboard_interactive_ex(LIBSSH2_SESSION *session, const char *username, unsigned int username_len, LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC(*response_callback)); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -\fIlibssh2_session_init_ex(3)\fP. +~~~ -\fIusername\fP - Name of user to attempt keyboard-interactive authentication +# DESCRIPTION + +*session* - Session instance as returned by +*libssh2_session_init_ex(3)*. + +*username* - Name of user to attempt keyboard-interactive authentication for. -\fIusername_len\fP - Length of username parameter. +*username_len* - Length of username parameter. -\fIresponse_callback\fP - As authentication proceeds, the host issues several +*response_callback* - As authentication proceeds, the host issues several (1 or more) challenges and requires responses. This callback will be called at this moment. The callback is responsible to obtain responses for the challenges, fill the provided data structure and then return control. Responses will be sent to the host. String values will be free(3)ed by the library. The callback prototype must match this: -.nf +~~~c void response(const char *name, int name_len, const char *instruction, int instruction_len, @@ -38,7 +50,7 @@ void response(const char *name, const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, void **abstract); -.fi +~~~ Attempts keyboard-interactive (challenge/response) authentication. @@ -46,16 +58,18 @@ Note that many SSH servers will always issue a single "password" challenge, requesting actual password as response, but it is not required by the protocol, and various authentication schemes, such as smartcard authentication may use keyboard-interactive authentication type too. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/password +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_AUTHENTICATION_FAILED* - failed, invalid username/password or public/private key. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_userauth_list.3 b/docs/libssh2_userauth_list.3 deleted file mode 100644 index e4d23f8a..00000000 --- a/docs/libssh2_userauth_list.3 +++ /dev/null @@ -1,43 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_list 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME -libssh2_userauth_list - list supported authentication methods -.SH SYNOPSIS -.nf -#include - -char * -libssh2_userauth_list(LIBSSH2_SESSION *session, - const char *username, - unsigned int username_len); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) - -\fIusername\fP - Username which will be used while authenticating. Note that -most server implementations do not permit attempting authentication with -different usernames between requests. Therefore this must be the same username -you will use on later userauth calls. - -\fIusername_len\fP - Length of username parameter. - -Send a \fBSSH_USERAUTH_NONE\fP request to the remote host. Unless the remote -host is configured to accept none as a viable authentication scheme -(unlikely), it will return \fBSSH_USERAUTH_FAILURE\fP along with a listing of -what authentication schemes it does support. In the unlikely event that none -authentication succeeds, this method with return NULL. This case may be -distinguished from a failing case by examining -\fIlibssh2_userauth_authenticated(3)\fP. -.SH RETURN VALUE -On success a comma delimited list of supported authentication schemes. This -list is internally managed by libssh2. On failure returns NULL. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. - -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. - -\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_userauth_list.md b/docs/libssh2_userauth_list.md new file mode 100644 index 00000000..4f6b59f7 --- /dev/null +++ b/docs/libssh2_userauth_list.md @@ -0,0 +1,56 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_list +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + +libssh2_userauth_list - list supported authentication methods + +# SYNOPSIS + +~~~c +#include + +char * +libssh2_userauth_list(LIBSSH2_SESSION *session, + const char *username, + unsigned int username_len); +~~~ + +# DESCRIPTION + +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*username* - Username which will be used while authenticating. Note that +most server implementations do not permit attempting authentication with +different usernames between requests. Therefore this must be the same username +you will use on later userauth calls. + +*username_len* - Length of username parameter. + +Send a **SSH_USERAUTH_NONE** request to the remote host. Unless the remote +host is configured to accept none as a viable authentication scheme +(unlikely), it will return **SSH_USERAUTH_FAILURE** along with a listing of +what authentication schemes it does support. In the unlikely event that none +authentication succeeds, this method with return NULL. This case may be +distinguished from a failing case by examining +*libssh2_userauth_authenticated(3)*. + +# RETURN VALUE + +On success a comma delimited list of supported authentication schemes. This +list is internally managed by libssh2. On failure returns NULL. + +# ERRORS + +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. + +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_EAGAIN* - Marked for non-blocking I/O but the call diff --git a/docs/libssh2_userauth_password.3 b/docs/libssh2_userauth_password.3 deleted file mode 100644 index 61fcdbb1..00000000 --- a/docs/libssh2_userauth_password.3 +++ /dev/null @@ -1,23 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_password 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_userauth_password - convenience macro for \fIlibssh2_userauth_password_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_userauth_password(LIBSSH2_SESSION *session, - const char *username, - const char *password); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_userauth_password_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_userauth_password_ex(3)\fP -.SH ERRORS -See \fIlibssh2_userauth_password_ex(3)\fP -.SH SEE ALSO -.BR libssh2_userauth_password_ex(3) diff --git a/docs/libssh2_userauth_password.md b/docs/libssh2_userauth_password.md new file mode 100644 index 00000000..7c9a232b --- /dev/null +++ b/docs/libssh2_userauth_password.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_password +Section: 3 +Source: libssh2 +See-also: + - libssh2_userauth_password_ex(3) +--- + +# NAME + +libssh2_userauth_password - convenience macro for *libssh2_userauth_password_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_userauth_password(LIBSSH2_SESSION *session, + const char *username, + const char *password); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_userauth_password_ex(3)*. + +# RETURN VALUE + +See *libssh2_userauth_password_ex(3)* + +# ERRORS + +See *libssh2_userauth_password_ex(3)* diff --git a/docs/libssh2_userauth_password_ex.3 b/docs/libssh2_userauth_password_ex.md similarity index 55% rename from docs/libssh2_userauth_password_ex.3 rename to docs/libssh2_userauth_password_ex.md index e2bd20f2..36fffb61 100644 --- a/docs/libssh2_userauth_password_ex.3 +++ b/docs/libssh2_userauth_password_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_password_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_password_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_userauth_password_ex - authenticate a session with username and password -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -15,24 +25,25 @@ libssh2_userauth_password_ex(LIBSSH2_SESSION *session, unsigned int password_len, LIBSSH2_PASSWD_CHANGEREQ_FUNC((*passwd_change_cb))); -#define libssh2_userauth_password(session, username, password) \\ - libssh2_userauth_password_ex((session), (username), \\ - strlen(username), \\ +#define libssh2_userauth_password(session, username, password) \ + libssh2_userauth_password_ex((session), (username), \ + strlen(username), \ (password), strlen(password), NULL) -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIusername\fP - Name of user to attempt plain password authentication for. +# DESCRIPTION -\fIusername_len\fP - Length of username parameter. +*session* - Session instance as returned by libssh2_session_init_ex(3) -\fIpassword\fP - Password to use for authenticating username. +*username* - Name of user to attempt plain password authentication for. -\fIpassword_len\fP - Length of password parameter. +*username_len* - Length of username parameter. -\fIpasswd_change_cb\fP - If the host accepts authentication but +*password* - Password to use for authenticating username. + +*password_len* - Length of password parameter. + +*passwd_change_cb* - If the host accepts authentication but requests that the password be changed, this callback will be issued. If no callback is defined, but server required password change, authentication will fail. @@ -41,20 +52,22 @@ Attempt basic password authentication. Note that many SSH servers which appear to support ordinary password authentication actually have it disabled and use Keyboard Interactive authentication (routed via PAM or another authentication backed) instead. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS + +# ERRORS + Some of the errors this function may return include: -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. -\fILIBSSH2_ERROR_PASSWORD_EXPIRED\fP - +*LIBSSH2_ERROR_PASSWORD_EXPIRED* - -\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/password +*LIBSSH2_ERROR_AUTHENTICATION_FAILED* - failed, invalid username/password or public/private key. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_userauth_publickey.3 b/docs/libssh2_userauth_publickey.md similarity index 60% rename from docs/libssh2_userauth_publickey.3 rename to docs/libssh2_userauth_publickey.md index ea282b19..81b604c6 100644 --- a/docs/libssh2_userauth_publickey.3 +++ b/docs/libssh2_userauth_publickey.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_publickey 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_publickey +Section: 3 +Source: libssh2 +See-also: + - libssh2_userauth_publickey_fromfile_ex(3) +--- + +# NAME + libssh2_userauth_publickey - authenticate using a callback function -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -14,18 +24,22 @@ libssh2_userauth_publickey(LIBSSH2_SESSION *session, size_t pubkeydata_len, sign_callback, void **abstract); -.fi -.SH DESCRIPTION -Authenticate with the \fIsign_callback\fP callback that matches the prototype +~~~ + +# DESCRIPTION + +Authenticate with the *sign_callback* callback that matches the prototype below -.SH CALLBACK -.nf + +# CALLBACK + +~~~c int name(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, const unsigned char *data, size_t data_len, void **abstract); -.fi +~~~ This function gets called... -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. -.SH SEE ALSO -.BR libssh2_userauth_publickey_fromfile_ex(3) diff --git a/docs/libssh2_userauth_publickey_fromfile.3 b/docs/libssh2_userauth_publickey_fromfile.3 deleted file mode 100644 index 7614c9e6..00000000 --- a/docs/libssh2_userauth_publickey_fromfile.3 +++ /dev/null @@ -1,25 +0,0 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_publickey_fromfile 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2" -.SH NAME -libssh2_userauth_publickey_fromfile - convenience macro for \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP calls -.SH SYNOPSIS -.nf -#include - -int -libssh2_userauth_publickey_fromfile(LIBSSH2_SESSION *session, - const char *username, - const char *publickey, - const char *privatekey, - const char *passphrase); -.fi -.SH DESCRIPTION -This is a macro defined in a public libssh2 header file that is using the -underlying function \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP. -.SH RETURN VALUE -See \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP -.SH ERRORS -See \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP -.SH SEE ALSO -.BR libssh2_userauth_publickey_fromfile_ex(3) diff --git a/docs/libssh2_userauth_publickey_fromfile.md b/docs/libssh2_userauth_publickey_fromfile.md new file mode 100644 index 00000000..ed27873e --- /dev/null +++ b/docs/libssh2_userauth_publickey_fromfile.md @@ -0,0 +1,39 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_publickey_fromfile +Section: 3 +Source: libssh2 +See-also: + - libssh2_userauth_publickey_fromfile_ex(3) +--- + +# NAME + +libssh2_userauth_publickey_fromfile - convenience macro for *libssh2_userauth_publickey_fromfile_ex(3)* calls + +# SYNOPSIS + +~~~c +#include + +int +libssh2_userauth_publickey_fromfile(LIBSSH2_SESSION *session, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); +~~~ + +# DESCRIPTION + +This is a macro defined in a public libssh2 header file that is using the +underlying function *libssh2_userauth_publickey_fromfile_ex(3)*. + +# RETURN VALUE + +See *libssh2_userauth_publickey_fromfile_ex(3)* + +# ERRORS + +See *libssh2_userauth_publickey_fromfile_ex(3)* diff --git a/docs/libssh2_userauth_publickey_fromfile_ex.3 b/docs/libssh2_userauth_publickey_fromfile_ex.md similarity index 50% rename from docs/libssh2_userauth_publickey_fromfile_ex.3 rename to docs/libssh2_userauth_publickey_fromfile_ex.md index dcd5db36..f7da16a8 100644 --- a/docs/libssh2_userauth_publickey_fromfile_ex.3 +++ b/docs/libssh2_userauth_publickey_fromfile_ex.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_publickey_fromfile_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_publickey_fromfile_ex +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_userauth_publickey_fromfile_ex - authenticate a session with a public key, read from a file -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -14,44 +24,48 @@ libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session, const char *publickey, const char *privatekey, const char *passphrase); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -\fBlibssh2_session_init_ex(3)\fP +~~~ -\fIusername\fP - Pointer to user name to authenticate as. +# DESCRIPTION -\fIusername_len\fP - Length of \fIusername\fP. +*session* - Session instance as returned by +**libssh2_session_init_ex(3)** -\fIpublickey\fP - Path name of the public key file. +*username* - Pointer to user name to authenticate as. + +*username_len* - Length of *username*. + +*publickey* - Path name of the public key file. (e.g. /etc/ssh/hostkey.pub). If libssh2 is built against OpenSSL, this option can be set to NULL. -\fIprivatekey\fP - Path name of the private key file. (e.g. /etc/ssh/hostkey) +*privatekey* - Path name of the private key file. (e.g. /etc/ssh/hostkey) -\fIpassphrase\fP - Passphrase to use when decoding \fIprivatekey\fP. +*passphrase* - Passphrase to use when decoding *privatekey*. Attempt public key authentication using either a public key file or a PEM encoded private key file stored on disk. When providing a private key, the public key is automatically extracted from it. When providing both, the passed public key takes precedence. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_FILE\fP - An issue opening, reading or parsing the disk file. -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +*LIBSSH2_ERROR_FILE* - An issue opening, reading or parsing the disk file. -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_PUBLICKEY_UNVERIFIED\fP - The username/public key +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_PUBLICKEY_UNVERIFIED* - The username/public key combination was invalid. -\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - Authentication using the supplied +*LIBSSH2_ERROR_AUTHENTICATION_FAILED* - Authentication using the supplied public key was not accepted. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_userauth_publickey_frommemory.3 b/docs/libssh2_userauth_publickey_frommemory.md similarity index 52% rename from docs/libssh2_userauth_publickey_frommemory.3 rename to docs/libssh2_userauth_publickey_frommemory.md index e6ced003..dd113f42 100644 --- a/docs/libssh2_userauth_publickey_frommemory.3 +++ b/docs/libssh2_userauth_publickey_frommemory.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_publickey_frommemory 3 "1 Sep 2014" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_publickey_frommemory +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_userauth_publickey_frommemory - authenticate a session with a public key, read from memory -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -16,47 +26,52 @@ libssh2_userauth_publickey_frommemory(LIBSSH2_SESSION *session, const char *privatekeydata, size_t privatekeydata_len, const char *passphrase); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIusername\fP - Remote user name to authenticate as. +# DESCRIPTION -\fIusername_len\fP - Length of username. +*session* - Session instance as returned by libssh2_session_init_ex(3) -\fIpublickeydata\fP - Buffer containing the contents of a public key file. +*username* - Remote user name to authenticate as. -\fIpublickeydata_len\fP - Length of public key data. +*username_len* - Length of username. -\fIprivatekeydata\fP - Buffer containing the contents of a private key file. +*publickeydata* - Buffer containing the contents of a public key file. -\fIprivatekeydata_len\fP - Length of private key data. +*publickeydata_len* - Length of public key data. -\fIpassphrase\fP - Passphrase to use when decoding private key file. +*privatekeydata* - Buffer containing the contents of a private key file. + +*privatekeydata_len* - Length of private key data. + +*passphrase* - Passphrase to use when decoding private key file. Attempt public key authentication using either a public key file or a PEM encoded private key file stored in memory. When providing a private key, the public key is automatically extracted from it. When providing both, the passed public key takes precedence. -.SH RETURN VALUE + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +# ERRORS -\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_PUBLICKEY_UNVERIFIED\fP - The username/public key +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_SOCKET_TIMEOUT* - + +*LIBSSH2_ERROR_PUBLICKEY_UNVERIFIED* - The username/public key combination was invalid. -\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - Authentication using the supplied +*LIBSSH2_ERROR_AUTHENTICATION_FAILED* - Authentication using the supplied public key was not accepted. -.SH AVAILABILITY + +# AVAILABILITY + libssh2_userauth_publickey_frommemory was added in libssh2 1.6.0 Supported with OpenSSL, WinCNG, mbedTLS, OS/400 crypto backends. -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_userauth_publickey_sk.3 b/docs/libssh2_userauth_publickey_sk.md similarity index 55% rename from docs/libssh2_userauth_publickey_sk.3 rename to docs/libssh2_userauth_publickey_sk.md index e2eff8f2..fa37887c 100644 --- a/docs/libssh2_userauth_publickey_sk.3 +++ b/docs/libssh2_userauth_publickey_sk.md @@ -1,10 +1,20 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_userauth_publickey_sk 3 "1 Jun 2022" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_userauth_publickey_sk +Section: 3 +Source: libssh2 +See-also: + - libssh2_session_init_ex(3) +--- + +# NAME + libssh2_userauth_publickey_sk - authenticate a session with a FIDO2 authenticator -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int @@ -18,9 +28,11 @@ libssh2_userauth_publickey_sk(LIBSSH2_SESSION *session, const char *passphrase, LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback)), void **abstract); -.fi -.SH CALLBACK -.nf +~~~ + +# CALLBACK + +~~~c #define LIBSSH2_SK_PRESENCE_REQUIRED 0x01 #define LIBSSH2_SK_VERIFICATION_REQUIRED 0x04 @@ -38,107 +50,112 @@ int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info, uint8_t flags, const char *application, const unsigned char *key_handle, size_t handle_len, void **abstract); -.fi -.SH DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +~~~ -\fIusername\fP - Name of user to attempt authentication for. +# DESCRIPTION -\fIusername_len\fP - Length of username parameter. +*session* - Session instance as returned by libssh2_session_init_ex(3) -\fIpublickeydata\fP - Buffer containing the contents of a public key file. If +*username* - Name of user to attempt authentication for. + +*username_len* - Length of username parameter. + +*publickeydata* - Buffer containing the contents of a public key file. If NULL, the public key will be extracted from the privatekeydata. When using certificate authentication, this buffer should contain the public certificate data. -\fIpublickeydata_len\fP - Length of public key data. +*publickeydata_len* - Length of public key data. -\fIprivatekeydata\fP - Buffer containing the contents of a private key file. +*privatekeydata* - Buffer containing the contents of a private key file. -\fIprivatekeydata_len\fP - Length of private key data. +*privatekeydata_len* - Length of private key data. -\fIpassphrase\fP - Passphrase to use when decoding private key file. +*passphrase* - Passphrase to use when decoding private key file. -\fIsign_callback\fP - Callback to communicate with FIDO2 authenticator. +*sign_callback* - Callback to communicate with FIDO2 authenticator. -\fIabstract\fP - User-provided data to pass to callback. +*abstract* - User-provided data to pass to callback. Attempt FIDO2 authentication. using either the sk-ssh-ed25519@openssh.com or sk-ecdsa-sha2-nistp256@openssh.com key exchange algorithms. This function is only supported when libssh2 is backed by OpenSSL. -.SH CALLBACK DESCRIPTION -\fIsession\fP - Session instance as returned by -.BR libssh2_session_init_ex(3) +# CALLBACK DESCRIPTION -\fIsig_info\fP - Filled in by the callback with the signature and accompanying +*session* - Session instance as returned by libssh2_session_init_ex(3) + +*sig_info* - Filled in by the callback with the signature and accompanying information from the authenticator. -\fIdata\fP - The data to sign. +*data* - The data to sign. -\fIdata_len\fP - The length of the data parameter. +*data_len* - The length of the data parameter. -\fIalgorithm\fP - The signing algorithm to use. Possible values are +*algorithm* - The signing algorithm to use. Possible values are LIBSSH2_HOSTKEY_TYPE_ED25519 and LIBSSH2_HOSTKEY_TYPE_ECDSA_256. -\fIflags\fP - A bitmask specifying options for the authenticator. When +*flags* - A bitmask specifying options for the authenticator. When LIBSSH2_SK_PRESENCE_REQUIRED is set, the authenticator requires a touch. When LIBSSH2_SK_VERIFICATION_REQUIRED is set, the authenticator requires a PIN. Many servers and authenticators do not work properly when LIBSSH2_SK_PRESENCE_REQUIRED is not set. -\fIapplication\fP - A user-defined string to use as the RP name for the +*application* - A user-defined string to use as the RP name for the authenticator. Usually "ssh:". -\fIkey_handle\fP - The key handle to use for the authenticator's allow list. +*key_handle* - The key handle to use for the authenticator's allow list. -\fIhandle_len\fP - The length of the key_handle parameter. +*handle_len* - The length of the key_handle parameter. -\fIabstract\fP - User-defined data. When a PIN is required, use this to pass in +*abstract* - User-defined data. When a PIN is required, use this to pass in the PIN, or a function pointer to retrieve the PIN. -The \fIsign_callback\fP is responsible for communicating with the hardware +The *sign_callback* is responsible for communicating with the hardware authenticator to generate a signature. On success, the signature information -must be placed in the `\fIsig_info\fP sig_info parameter and the callback must +must be placed in the *sig_info* sig_info parameter and the callback must return 0. On failure, it should return a negative number. The fields of the LIBSSH2_SK_SIG_INFO are as follows. -\fIflags\fP - A bitmask specifying options for the authenticator. This should +*flags* - A bitmask specifying options for the authenticator. This should be read from the authenticator and not merely copied from the flags parameter to the callback. -\fIcounter\fP - A value returned from the authenticator. +*counter* - A value returned from the authenticator. -\fIsig_r\fP - For Ed25519 signatures, this contains the entire signature, as +*sig_r* - For Ed25519 signatures, this contains the entire signature, as returned directly from the authenticator. For ECDSA signatures, this contains the r component of the signature in a big-endian binary representation. For both algorithms, use LIBSSH2_ALLOC to allocate memory. It will be freed by the caller. -\fIsig_r_len\fP - The length of the sig_r parameter. +*sig_r_len* - The length of the sig_r parameter. -\fIsig_s\fP - For ECDSA signatures, this contains the s component of the +*sig_s* - For ECDSA signatures, this contains the s component of the signature in a big-endian binary representation. Use LIBSSH2_ALLOC to allocate memory. It will be freed by the caller. For Ed25519 signatures, set this to NULL. -\fIsig_s_len\fP - The length of the sig_s parameter. -.SH RETURN VALUE +*sig_s_len* - The length of the sig_s parameter. + +# RETURN VALUE + Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. -.SH ERRORS + +# ERRORS + Some of the errors this function may return include: -\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +*LIBSSH2_ERROR_ALLOC* - An internal memory allocation call failed. -\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. +*LIBSSH2_ERROR_SOCKET_SEND* - Unable to send data on socket. + +*LIBSSH2_ERROR_AUTHENTICATION_FAILED* - failed, invalid username/key. + +# AVAILABILITY -\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/key. -.SH AVAILABILITY Added in libssh2 1.10.0 -.SH SEE ALSO -.BR libssh2_session_init_ex(3) diff --git a/docs/libssh2_version.3 b/docs/libssh2_version.md similarity index 64% rename from docs/libssh2_version.3 rename to docs/libssh2_version.md index 1cdf0e1f..7f5d01b7 100644 --- a/docs/libssh2_version.3 +++ b/docs/libssh2_version.md @@ -1,42 +1,59 @@ -.\" Copyright (C) The libssh2 project and its contributors. -.\" SPDX-License-Identifier: BSD-3-Clause -.TH libssh2_version 3 "23 Feb 2009" "libssh2" "libssh2" -.SH NAME +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_version +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + libssh2_version - return the libssh2 version number -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include const char * libssh2_version(int required_version); -.fi -.SH DESCRIPTION -If \fIrequired_version\fP is lower than or equal to the version number of the +~~~ + +# DESCRIPTION + +If *required_version* is lower than or equal to the version number of the libssh2 in use, the version number of libssh2 is returned as a pointer to a zero terminated string. -The \fIrequired_version\fP should be the version number as constructed by the +The *required_version* should be the version number as constructed by the LIBSSH2_VERSION_NUM define in the libssh2.h public header file, which is a 24 bit number in the 0xMMmmpp format. MM for major, mm for minor and pp for patch number. -.SH RETURN VALUE + +# RETURN VALUE + The version number of libssh2 is returned as a pointer to a zero terminated -string or NULL if the \fIrequired_version\fP is not fulfilled. -.SH EXAMPLE +string or NULL if the *required_version* is not fulfilled. + +# EXAMPLE + To make sure you run with the correct libssh2 version: -.nf +~~~c if(!libssh2_version(LIBSSH2_VERSION_NUM)) { fprintf(stderr, \&"Runtime libssh2 version too old.\&"); return -1; /* return error */ } -.fi +~~~ Unconditionally get the version number: -.nf +~~~c printf(\&"libssh2 version: %s\&", libssh2_version(0)); -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + This function was added in libssh2 1.1, in previous versions there way no way to extract this info in run-time. diff --git a/docs/template.3 b/docs/template.3 deleted file mode 100644 index 473e0bd3..00000000 --- a/docs/template.3 +++ /dev/null @@ -1,20 +0,0 @@ -.TH libssh2_template 3 "1 Jun 2022" "libssh2" "libssh2" -.SH NAME -libssh2_template - short function description -.SH SYNOPSIS -.nf -#include - -void -libssh2_template(void); -.fi -.SH DESCRIPTION -Long text describing the function and its input arguments. -.SH RETURN VALUE -Describe what the function returns. -.SH ERRORS -Add error codes -.SH AVAILABILITY -Added in libssh2 ?.?.? -.SH SEE ALSO -Add related functions diff --git a/docs/template.md b/docs/template.md new file mode 100644 index 00000000..c5f693c4 --- /dev/null +++ b/docs/template.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) The libssh2 project and its contributors. +SPDX-License-Identifier: BSD-3-Clause +Title: libssh2_template +Section: 3 +Source: libssh2 +See-also: +--- + +# NAME + +libssh2_template - short function description + +# SYNOPSIS + +~~~c +#include + +void +libssh2_template(void); +~~~ + +# DESCRIPTION + +Long text describing the function and its input arguments. + +# RETURN VALUE + +Describe what the function returns. + +# ERRORS + +Add error codes + +# AVAILABILITY + +Added in libssh2 ?.?.? +Add related functions diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index a6c19129..8bf544b7 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -66,8 +66,6 @@ if(SH_EXECUTABLE) find_program(SSHD_EXECUTABLE "sshd") mark_as_advanced(SSHD_EXECUTABLE) endif() - - add_test(NAME mansyntax COMMAND ${SH_EXECUTABLE} -c "${CMAKE_CURRENT_SOURCE_DIR}/mansyntax.sh") endif() add_library(runner STATIC ${librunner_la_SOURCES}) diff --git a/tests/Makefile.am b/tests/Makefile.am index a38a7561..a8e12068 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -20,7 +20,7 @@ endif TESTS_ENVIRONMENT = # Tests to run -TESTS = mansyntax.sh +TESTS = if RUN_DOCKER_TESTS TESTS += $(DOCKER_TESTS) diff --git a/tests/Makefile.inc b/tests/Makefile.inc index f3a6fd83..c930213b 100644 --- a/tests/Makefile.inc +++ b/tests/Makefile.inc @@ -87,7 +87,6 @@ EXTRA_DIST = \ key_rsa_sha2_256_signed \ key_rsa_sha2_256_signed-cert.pub \ key_rsa_sha2_256_signed.pub \ - mansyntax.sh \ openssh_server/Dockerfile \ openssh_server/authorized_keys \ openssh_server/ca_ecdsa \ diff --git a/tests/mansyntax.sh b/tests/mansyntax.sh deleted file mode 100755 index 4a2fceb3..00000000 --- a/tests/mansyntax.sh +++ /dev/null @@ -1,48 +0,0 @@ -#!/bin/sh -# Copyright (C) The libssh2 project and its contributors. -# SPDX-License-Identifier: BSD-3-Clause - -set -eu - -# Written by Mikhail Gusarov -# -# Run syntax checks for all manpages in the documentation tree. -# -# Requirement on macOS: brew install man-db -# - -command -v gman >/dev/null 2>&1 && man() { gman "$@"; } - -dstdir="${builddir:-$PWD}" -mandir="$(dirname "$0")/../docs" - -ec=0 - -# -# Only test if suitable man is available -# -if command -v grep >/dev/null 2>&1 && \ - man --help 2>/dev/null | grep -q warnings; then - - trap 'rm -f "$dstdir/man3"' EXIT HUP INT TERM - - # Tell 'man' to not pipe the output through 'col'. - # 'col' is missing from Cygwin since util-linux 2.40.2-1 (2024-12-24). - export MAN_KEEP_FORMATTING=1 - - ln -sf "$mandir" "$dstdir/man3" - - for manpage in "$mandir"/libssh2_*.*; do - echo "$manpage" - warnings=$(LANG=en_US.UTF-8 MANWIDTH=80 man -M "$dstdir" --warnings \ - -E UTF-8 -l "$manpage" 2>&1 >/dev/null) - if [ -n "$warnings" ]; then - echo "$warnings" - ec=1 - fi - done -else - echo 'mansyntax: Required tool not found, skipping tests.' -fi - -exit "$ec"