libssh2_scp_send, libssh2_scp_send_ex: add deprecation warning

Also:
- switch to non-deprecated alternative in examples.
- add pointers and deprecation warning to libssh2_scp_send man page.

Cherry-picked from #1484

docs/TODO

@@ -46,6 +46,8 @@ At next SONAME bump
   libssh2_channel_receive_window_adjust()
   libssh2_poll()
   libssh2_poll_channel_read()
+  libssh2_scp_send()
+  libssh2_scp_send_ex()
   libssh2_session_startup() (libssh2_session_handshake() is the replacement)
   libssh2_banner_set() (libssh2_session_banner_set() is the replacement)
 

docs/libssh2_scp_send.3

@@ -14,9 +14,13 @@ libssh2_scp_send(LIBSSH2_SESSION *session, const char *path,
 .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_send_ex(3),
+.BR libssh2_scp_send64(3)

docs/libssh2_scp_send_ex.3

@@ -46,6 +46,6 @@ Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors.
 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.
+\fIlibssh2_scp_send64(3)\fP has been introduced to replace this function.
 .SH SEE ALSO
 .BR libssh2_channel_open_ex(3)

example/scp_write.c

@@ -152,8 +152,8 @@ int main(int argc, char *argv[])
     }
 
     /* Send a file via scp. The mode parameter must only have permissions! */
-    channel = libssh2_scp_send(session, scppath, fileinfo.st_mode & 0777,
+    channel = libssh2_scp_send64(session, scppath, fileinfo.st_mode & 0777,
-                               (size_t)fileinfo.st_size);
+                                 fileinfo.st_size, 0, 0);
 
     if(!channel) {
         char *errmsg;

example/scp_write_nonblock.c

@@ -206,8 +206,8 @@ int main(int argc, char *argv[])
 
     /* Send a file via scp. The mode parameter must only have permissions! */
     do {
-        channel = libssh2_scp_send(session, scppath, fileinfo.st_mode & 0777,
+        channel = libssh2_scp_send64(session, scppath, fileinfo.st_mode & 0777,
-                                   (size_t)fileinfo.st_size);
+                                     fileinfo.st_size, 0, 0);
 
         if(!channel &&
            libssh2_session_last_errno(session) != LIBSSH2_ERROR_EAGAIN) {

example/ssh2.c

@@ -335,7 +335,7 @@ int main(int argc, char *argv[])
     }
 
     /* Other channel types are supported via:
-     * libssh2_scp_send()
+     * libssh2_scp_send64()
      * libssh2_scp_recv2()
      * libssh2_channel_direct_tcpip()
      */

example/ssh2_agent.c

@@ -219,7 +219,7 @@ skip_shell:
     }
 
     /* Other channel types are supported via:
-     * libssh2_scp_send()
+     * libssh2_scp_send64()
      * libssh2_scp_recv2()
      * libssh2_channel_direct_tcpip()
      */

include/libssh2.h

@@ -1058,17 +1058,19 @@ LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_recv(LIBSSH2_SESSION *session,
 LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_recv2(LIBSSH2_SESSION *session,
                                                const char *path,
                                                libssh2_struct_stat *sb);
+#ifndef LIBSSH2_NO_DEPRECATED
+LIBSSH2_DEPRECATED(1.2.6, "Use libssh2_scp_send64()")
 LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_send_ex(LIBSSH2_SESSION *session,
                                                  const char *path, int mode,
                                                  size_t size, long mtime,
                                                  long atime);
+#define libssh2_scp_send(session, path, mode, size) \
+    libssh2_scp_send_ex((session), (path), (mode), (size), 0, 0)
+#endif
 LIBSSH2_API LIBSSH2_CHANNEL *
 libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode,
                    libssh2_int64_t size, time_t mtime, time_t atime);
 
-#define libssh2_scp_send(session, path, mode, size) \
-    libssh2_scp_send_ex((session), (path), (mode), (size), 0, 0)
-
 /* DEPRECATED */
 LIBSSH2_API int libssh2_base64_decode(LIBSSH2_SESSION *session, char **dest,
                                       unsigned int *dest_len,

os400/libssh2rpg/libssh2.rpgle.in

@@ -1401,6 +1401,7 @@
      d  path                           *   value options(*string)               const char *
      d  sb                                 likeds(libssh2_struct_stat)
 
+      /if not defined(LIBSSH2_NO_DEPRECATED)
      d libssh2_scp_send_ex...
      d                 pr              *   extproc('libssh2_scp_send_ex')       LIBSSH2_CHANNEL *
      d  session                        *   value                                LIBSSH2_SESSION *
@@ -1409,6 +1410,7 @@
      d  size                               value like(libssh2_Csize_t)
      d  mtime                              value like(libssh2_Clong)
      d  atime                              value like(libssh2_Clong)
+      /endif
 
      d libssh2_scp_send64...
      d                 pr              *   extproc('libssh2_scp_send64')        LIBSSH2_CHANNEL *

src/scp.c

@@ -794,9 +794,7 @@ scp_recv_error:
 
 #ifndef LIBSSH2_NO_DEPRECATED
 /*
- * libssh2_scp_recv
+ * libssh2_scp_recv (DEPRECATED, DO NOT USE!)
- *
- * DEPRECATED
  *
  * Open a channel and request a remote file via SCP.  This receives files
  * larger than 2 GB, but is unable to report the proper size on platforms
@@ -1153,8 +1151,9 @@ scp_send_error:
     return NULL;
 }
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /*
- * libssh2_scp_send_ex
+ * libssh2_scp_send_ex (DEPRECATED, DO NOT USE!)
  *
  * Send a file using SCP. Old API.
  */
@@ -1168,6 +1167,7 @@ libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode,
                                 (time_t)mtime, (time_t)atime));
     return ptr;
 }
+#endif
 
 /*
  * libssh2_scp_send64