Add krb5_cc_start_seq_get and an example.

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@16182 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/krb5/krb5_ccache.3

@@ -64,7 +64,8 @@
 .Nm krb5_cc_retrieve_cred ,
 .Nm krb5_cc_set_default_name ,
 .Nm krb5_cc_set_flags ,
-.Nm krb5_cc_store_cred ,
+.Nm krb5_cc_start_seq_get ,
+.Nm krb5_cc_store_cred
 .Nd mange credential cache
 .Sh LIBRARY
 Kerberos 5 Library (libkrb5, -lkrb5)
@@ -192,6 +193,12 @@ Kerberos 5 Library (libkrb5, -lkrb5)
 .Fa "const char *name"
 .Fc
 .Ft krb5_error_code
+.Fo krb5_cc_start_seq_get
+.Fa "krb5_context context"
+.Fa "const krb5_ccache id"
+.Fa "krb5_cc_cursor *cursor"
+.Fc
+.Ft krb5_error_code
 .Fo krb5_cc_store_cred
 .Fa "krb5_context *context"
 .Fa "krb5_ccache id"
@@ -408,6 +415,11 @@ in
 .Fa creds .
 Return 0 or an error code.
 .Pp
+.Fn krb5_cc_start_seq_get
+initiates the
+.Li krb5_cc_cursor
+structure to be used for iteration over the credential cache.
+.Pp
 .Fn krb5_cc_next_cred
 retrieves the next cred pointed to by
 .Fa ( id ,
@@ -431,6 +443,51 @@ and
 .Fn krb5_cc_end_seq_get
 Destroys the cursor
 .Fa cursor .
+.Sh EXAMPLE
+This is a minimalistic version of
+.Nm klist .
+.Pp
+.Bd -literal
+#include <krb5.h>
+
+int
+main (int argc, char **argv)
+{
+    krb5_context context;
+    krb5_cc_cursor cursor;
+    krb5_error_code ret;
+    krb5_ccache id;
+    krb5_creds creds;
+
+    if (krb5_init_context (&context) != 0)
+	errx(1, "krb5_context");
+
+    ret = krb5_cc_default (context, &id);
+    if (ret)
+	krb5_err(context, 1, ret, "krb5_cc_default");
+
+    ret = krb5_cc_start_seq_get(context, id, &cursor);
+    if (ret)
+	krb5_err(context, 1, ret, "krb5_cc_start_seq_get");
+
+    while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){
+        char *principal;
+
+	krb5_unparse_name_short(context, creds.server, &principal);
+	printf("principal: %s\\n", principal);
+	free(principal);
+	krb5_free_cred_contents (context, &creds);
+    }
+    ret = krb5_cc_end_seq_get(context, id, &cursor);
+    if (ret)
+	krb5_err(context, 1, ret, "krb5_cc_end_seq_get");
+
+    krb5_cc_close(context, id);
+
+    krb5_free_context(context);
+    return 0;
+}
+.Ed
 .Sh SEE ALSO
 .Xr krb5 3 ,
 .Xr krb5.conf 5 ,