Add man pages for ssh-agent API.

docs/Makefile.am

@@ -3,6 +3,13 @@
 EXTRA_DIST = template.3
 
 dist_man_MANS = \
+	libssh2_agent_connect.3 \
+	libssh2_agent_disconnect.3 \
+	libssh2_agent_free.3 \
+	libssh2_agent_get_identity.3 \
+	libssh2_agent_init.3 \
+	libssh2_agent_list_identities.3 \
+	libssh2_agent_userauth.3 \
 	libssh2_banner_set.3 \
 	libssh2_base64_decode.3 \
 	libssh2_channel_close.3 \

docs/libssh2_agent_connect.3

@@ -0,0 +1,23 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_connect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_connect - connect to an ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_connect(LIBSSH2_AGENT *agent);
+.SH DESCRIPTION
+Connect to an ssh-agent running on the system.
+
+Call \fBlibssh2_agent_disconnect(3)\fP to close the connection after
+you're 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)
+

docs/libssh2_agent_disconnect.3

@@ -0,0 +1,20 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_disconnect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_disconnect - close a connection to an ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_disconnect(LIBSSH2_AGENT *agent);
+.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)

docs/libssh2_agent_free.3

@@ -0,0 +1,20 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_free 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_free - free an ssh-agent handle
+.SH SYNOPSIS
+#include <libssh2.h>
+
+void libssh2_agent_free(LIBSSH2_AGENT *agent);
+.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)

docs/libssh2_agent_get_identity.3

@@ -0,0 +1,34 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_get_identity 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_get_identity - get a public key off the collection of public keys managed by ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_get_identity(LIBSSH2_AGENT *agent,
+                               struct libssh2_agent_publickey **store,
+                               struct libssh2_agent_publickey *prev);
+.SH DESCRIPTION
+\fIlibssh2_agent_get_identity(3)\fP 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
+public key data.
+
+\fIprev\fP 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
+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 public keys.
+
+Returns negative values for error
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_list_identities(3)
+.BR libssh2_agent_userauth(3)

docs/libssh2_agent_init.3

@@ -0,0 +1,26 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_init 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_init - init an ssh-agent handle
+.SH SYNOPSIS
+#include <libssh2.h>
+
+LIBSSH2_AGENT *libssh2_agent_init(LIBSSH2_SESSION *session);
+.SH 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
+to connect to a running ssh-agent.
+
+Call \fBlibssh2_agent_free(3)\fP to free the handle again after you're
+doing using it.
+.SH 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
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_connect(3)
+.BR libssh2_agent_free(3)

docs/libssh2_agent_list_identities.3

@@ -0,0 +1,24 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_list_identities 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_list_identities - request an ssh-agent to list of public keys.
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_list_identities(LIBSSH2_AGENT *agent);
+.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)
+

docs/libssh2_agent_userauth.3

@@ -0,0 +1,29 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_userauth 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_userauth - authenticate a session with a public key, with the help of ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_userauth(LIBSSH2_AGENT *agent,
+                           const char *username,
+                           struct libssh2_agent_publickey *identity);
+.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)