Adding upstream version 2:4.20.0+dfsg.upstream/2%4.20.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 3270 insertions, 0 deletions

diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
new file mode 100644
index 0000000..619feab
--- /dev/null
+++ b/source3/include/libsmbclient.h
@@ -0,0 +1,3270 @@
+/*=====================================================================
+  Unix SMB/Netbios implementation.
+  SMB client library API definitions
+  Copyright (C) Andrew Tridgell 1998
+  Copyright (C) Richard Sharpe 2000
+  Copyright (C) John Terpsra 2000
+  Copyright (C) Tom Jansen (Ninja ISD) 2002
+  Copyright (C) Derrell Lipman 2003-2008
+
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, see <http://www.gnu.org/licenses/>.
+  =====================================================================*/
+
+#ifndef SMBCLIENT_H_INCLUDED
+#define SMBCLIENT_H_INCLUDED
+
+#undef DEPRECATED_SMBC_INTERFACE
+#if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
+# define DEPRECATED_SMBC_INTERFACE      __attribute__ ((deprecated))
+#else
+# define DEPRECATED_SMBC_INTERFACE
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*-------------------------------------------------------------------*/
+/* The following are special comments to instruct DOXYGEN (automated
+ * documentation tool:
+*/
+/** \defgroup libsmbclient
+*/
+/** \defgroup structure Data Structures Type and Constants
+*   \ingroup libsmbclient
+*   Data structures, types, and constants
+*/
+/** \defgroup callback Callback function types
+*   \ingroup libsmbclient
+*   Callback functions
+*/
+/** \defgroup file File Functions
+*   \ingroup libsmbclient
+*   Functions used to access individual file contents
+*/
+/** \defgroup directory Directory Functions
+*   \ingroup libsmbclient
+*   Functions used to access directory entries
+*/
+/** \defgroup attribute Attributes Functions
+*   \ingroup libsmbclient
+*   Functions used to view or change file and directory attributes
+*/
+/** \defgroup print Print Functions
+*   \ingroup libsmbclient
+*   Functions used to access printing functionality
+*/
+/** \defgroup misc Miscellaneous Functions
+*   \ingroup libsmbclient
+*   Functions that don't fit in to other categories
+*/
+/*-------------------------------------------------------------------*/
+
+/* Make sure we have the following includes for now ... */
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/statvfs.h>
+#include <stdint.h>
+#include <fcntl.h>
+#include <time.h>
+#include <utime.h>
+
+#define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
+
+#define SMBC_WORKGROUP      1
+#define SMBC_SERVER         2
+#define SMBC_FILE_SHARE     3
+#define SMBC_PRINTER_SHARE  4
+#define SMBC_COMMS_SHARE    5
+#define SMBC_IPC_SHARE      6
+#define SMBC_DIR            7
+#define SMBC_FILE           8
+#define SMBC_LINK           9
+
+/**@ingroup structure
+ * Structure that represents a directory entry.
+ *
+ */
+struct smbc_dirent
+{
+	/** Type of entity.
+	    SMBC_WORKGROUP=1,
+	    SMBC_SERVER=2,
+	    SMBC_FILE_SHARE=3,
+	    SMBC_PRINTER_SHARE=4,
+	    SMBC_COMMS_SHARE=5,
+	    SMBC_IPC_SHARE=6,
+	    SMBC_DIR=7,
+	    SMBC_FILE=8,
+	    SMBC_LINK=9,*/
+	unsigned int smbc_type;
+
+	/** Length of this smbc_dirent in bytes
+	 */
+	unsigned int dirlen;
+	/** The length of the comment string in bytes (does not include
+	 *  null terminator)
+	 */
+	unsigned int commentlen;
+	/** Points to the null terminated comment string
+	 */
+	char *comment;
+	/** The length of the name string in bytes (does not include
+	 *  null terminator)
+	 */
+	unsigned int namelen;
+	/** Points to the null terminated name string
+	 */
+	char name[1];
+};
+
+/**@ingroup structure
+ * Structure that represents all attributes of a directory entry.
+ *
+ */
+struct libsmb_file_info
+{
+	/**
+	 * Size of file
+	 */
+	uint64_t size;
+	/**
+	 * DOS attributes of file
+	 */
+	uint16_t attrs;
+	/**
+	 * User ID of file
+	 */
+	uid_t uid;
+	/**
+	 * Group ID of file
+	 */
+	gid_t gid;
+	/**
+	 * Birth/Create time of file (if supported by system)
+	 * Otherwise the value will be 0
+	 */
+	struct timespec btime_ts;
+	/**
+	 * Modified time for the file
+	 */
+	struct timespec mtime_ts;
+	/**
+	 * Access time for the file
+	 */
+	struct timespec atime_ts;
+	/**
+	 * Change time for the file
+	 */
+	struct timespec ctime_ts;
+	/**
+	 * Name of file
+	 */
+	char *name;
+	/**
+	 * Short name of file
+	 */
+	char *short_name;
+};
+
+/*
+ * Logging callback function
+ */
+typedef void (*smbc_debug_callback_fn)(void *private_ptr, int level, const char *msg);
+
+/*
+ * Flags for smbc_setxattr()
+ *   Specify a bitwise OR of these, or 0 to add or replace as necessary
+ */
+#define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
+#define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
+
+
+/*
+ * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
+ * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
+ * "system.*") is specified.
+ */
+#define SMBC_DOS_MODE_READONLY       0x01
+#define SMBC_DOS_MODE_HIDDEN         0x02
+#define SMBC_DOS_MODE_SYSTEM         0x04
+#define SMBC_DOS_MODE_VOLUME_ID      0x08
+#define SMBC_DOS_MODE_DIRECTORY      0x10
+#define SMBC_DOS_MODE_ARCHIVE        0x20
+
+/*
+ * Valid values for the option "open_share_mode", when calling
+ * smbc_setOptionOpenShareMode()
+ */
+typedef enum smbc_share_mode
+{
+    SMBC_SHAREMODE_DENY_DOS     = 0,
+    SMBC_SHAREMODE_DENY_ALL     = 1,
+    SMBC_SHAREMODE_DENY_WRITE   = 2,
+    SMBC_SHAREMODE_DENY_READ    = 3,
+    SMBC_SHAREMODE_DENY_NONE    = 4,
+    SMBC_SHAREMODE_DENY_FCB     = 7
+} smbc_share_mode;
+
+
+/**
+ * Values for option SMB Encryption Level, as set and retrieved with
+ * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
+ */
+typedef enum smbc_smb_encrypt_level
+{
+    SMBC_ENCRYPTLEVEL_DEFAULT   = -1,
+    SMBC_ENCRYPTLEVEL_NONE      = 0,
+    SMBC_ENCRYPTLEVEL_REQUEST   = 1,
+    SMBC_ENCRYPTLEVEL_REQUIRE   = 2
+} smbc_smb_encrypt_level;
+
+
+/**
+ * Capabilities set in the f_flag field of struct statvfs, from
+ * smbc_statvfs(). These may be OR-ed together to reflect a full set of
+ * available capabilities.
+ */
+typedef enum smbc_vfs_feature
+{
+    /* Defined by POSIX or in Linux include files (low-order bits) */
+    SMBC_VFS_FEATURE_RDONLY         = (1 << 0),
+
+    /* Specific to libsmbclient (high-order bits) */
+    SMBC_VFS_FEATURE_DFS              = (1 << 28),
+    SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 29),
+    SMBC_VFS_FEATURE_NO_UNIXCIFS      = (1 << 30)
+} smbc_vfs_feature;
+
+typedef int smbc_bool;
+
+
+#ifndef ENOATTR
+# define ENOATTR ENOENT        /* No such attribute */
+#endif
+
+
+
+
+/**@ingroup structure
+ * Structure that represents a print job.
+ *
+ */
+#ifndef _CLIENT_H
+struct print_job_info
+{
+	/** numeric ID of the print job
+	 */
+	unsigned short id;
+
+	/** represents print job priority (lower numbers mean higher priority)
+	 */
+	unsigned short priority;
+
+	/** Size of the print job
+	 */
+	size_t size;
+
+	/** Name of the user that owns the print job
+	 */
+	char user[128];
+
+	/** Name of the print job. This will have no name if an anonymous print
+	 *  file was opened. Ie smb://server/printer
+	 */
+	char name[128];
+
+	/** Time the print job was spooled
+	 */
+	time_t t;
+};
+#endif /* _CLIENT_H */
+
+
+/**@ingroup structure
+ * Server handle
+ */
+typedef struct _SMBCSRV  SMBCSRV;
+
+/**@ingroup structure
+ * File or directory handle
+ */
+typedef struct _SMBCFILE SMBCFILE;
+
+/**@ingroup structure
+ * File or directory handle
+ */
+typedef struct _SMBCCTX SMBCCTX;
+
+
+/*
+ * Flags for SMBCCTX->flags
+ *
+ * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
+ * Instead, use:
+ *   smbc_setOptionUseKerberos()
+ *   smbc_getOptionUseKerberos()
+ *   smbc_setOptionFallbackAfterKerberos()
+ *   smbc_getOptionFallbackAFterKerberos()
+ *   smbc_setOptionNoAutoAnonymousLogin()
+ *   smbc_getOptionNoAutoAnonymousLogin()
+ *   smbc_setOptionUseCCache()
+ *   smbc_getOptionUseCCache()
+ */
+# define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
+# define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
+# define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
+# define SMB_CTX_FLAG_USE_CCACHE (1 << 3)
+
+
+
+/**@ingroup callback
+ * Authentication callback function type (traditional method)
+ *
+ * Type for the the authentication function called by the library to
+ * obtain authentication credentials
+ *
+ * For kerberos support the function should just be called without
+ * prompting the user for credentials. Which means a simple 'return'
+ * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
+ * and examples/libsmbclient/testbrowse.c.
+ *
+ * @param srv       Server being authenticated to
+ *
+ * @param shr       Share being authenticated to
+ *
+ * @param wg        Pointer to buffer containing a "hint" for the
+ *                  workgroup to be authenticated.  Should be filled in
+ *                  with the correct workgroup if the hint is wrong.
+ *
+ * @param wglen     The size of the workgroup buffer in bytes
+ *
+ * @param un        Pointer to buffer containing a "hint" for the
+ *                  user name to be use for authentication. Should be
+ *                  filled in with the correct workgroup if the hint is
+ *                  wrong.
+ *
+ * @param unlen     The size of the username buffer in bytes
+ *
+ * @param pw        Pointer to buffer containing to which password
+ *                  copied
+ *
+ * @param pwlen     The size of the password buffer in bytes
+ *
+ */
+typedef void (*smbc_get_auth_data_fn)(const char *srv,
+                                      const char *shr,
+                                      char *wg, int wglen,
+                                      char *un, int unlen,
+                                      char *pw, int pwlen);
+/**@ingroup callback
+ * Authentication callback function type (method that includes context)
+ *
+ * Type for the the authentication function called by the library to
+ * obtain authentication credentials
+ *
+ * For kerberos support the function should just be called without
+ * prompting the user for credentials. Which means a simple 'return'
+ * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
+ * and examples/libsmbclient/testbrowse.c.
+ *
+ * @param c         Pointer to the smb context
+ *
+ * @param srv       Server being authenticated to
+ *
+ * @param shr       Share being authenticated to
+ *
+ * @param wg        Pointer to buffer containing a "hint" for the
+ *                  workgroup to be authenticated.  Should be filled in
+ *                  with the correct workgroup if the hint is wrong.
+ *
+ * @param wglen     The size of the workgroup buffer in bytes
+ *
+ * @param un        Pointer to buffer containing a "hint" for the
+ *                  user name to be use for authentication. Should be
+ *                  filled in with the correct workgroup if the hint is
+ *                  wrong.
+ *
+ * @param unlen     The size of the username buffer in bytes
+ *
+ * @param pw        Pointer to buffer containing to which password
+ *                  copied
+ *
+ * @param pwlen     The size of the password buffer in bytes
+ *
+ */
+typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
+                                                   const char *srv,
+                                                   const char *shr,
+                                                   char *wg, int wglen,
+                                                   char *un, int unlen,
+                                                   char *pw, int pwlen);
+
+
+/**@ingroup callback
+ * Print job info callback function type.
+ *
+ * @param i         pointer to print job information structure
+ *
+ */
+typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
+
+
+/**@ingroup callback
+ * Check if a server is still good
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to check
+ *
+ * @return          0 when connection is good. 1 on error.
+ *
+ */
+typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
+
+/**@ingroup callback
+ * Remove a server if unused
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to remove
+ *
+ * @return          0 on success. 1 on failure.
+ *
+ */
+typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
+
+
+/**@ingroup callback
+ * Add a server to the cache system
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to add
+ *
+ * @param server    server name
+ *
+ * @param share     share name
+ *
+ * @param workgroup workgroup used to connect
+ *
+ * @param username  username used to connect
+ *
+ * @return          0 on success. 1 on failure.
+ *
+ */
+typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv,
+				    const char * server, const char * share,
+				    const char * workgroup, const char * username);
+
+/**@ingroup callback
+ * Look up a server in the cache system
+ *
+ * @param c         pointer to smb context
+ *
+ * @param server    server name to match
+ *
+ * @param share     share name to match
+ *
+ * @param workgroup workgroup to match
+ *
+ * @param username  username to match
+ *
+ * @return          pointer to SMBCSRV on success. NULL on failure.
+ *
+ */
+typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
+					       const char * share, const char * workgroup,
+                                               const char * username);
+
+/**@ingroup callback
+ * Remove a cached server
+ *
+ * @param c         pointer to smb context
+ *
+ * @param srv       pointer to server to remove
+ *
+ * @return          0 when found and removed. 1 on failure.
+ *
+ */
+typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
+
+
+/**@ingroup callback
+ * Try to remove all servers from the cache system and disconnect
+ *
+ * @param c         pointer to smb context
+ *
+ * @return          0 when found and removed. 1 on failure.
+ *
+ */
+typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
+
+
+
+/*****************************************
+ * Getters and setters for CONFIGURATION *
+ *****************************************/
+
+/** Get the debug level */
+int
+smbc_getDebug(SMBCCTX *c);
+
+/** Set the debug level */
+void
+smbc_setDebug(SMBCCTX *c, int debug);
+
+/**
+ * set log callback function to capture logs from libsmbclient, this
+ * is applied at global level
+ */
+void
+smbc_setLogCallback(SMBCCTX *c, void *private_ptr,
+		    smbc_debug_callback_fn fn);
+
+/** set configuration file, this is applied at global level */
+int
+smbc_setConfiguration(SMBCCTX *c, const char *file);
+
+/** Get the netbios name used for making connections */
+const char *
+smbc_getNetbiosName(SMBCCTX *c);
+
+/** Set the netbios name used for making connections */
+void
+smbc_setNetbiosName(SMBCCTX *c, const char *netbios_name);
+
+/** Get the workgroup used for making connections */
+const char *
+smbc_getWorkgroup(SMBCCTX *c);
+
+/** Set the workgroup used for making connections */
+void smbc_setWorkgroup(SMBCCTX *c, const char *workgroup);
+
+/** Get the username used for making connections */
+const char *
+smbc_getUser(SMBCCTX *c);
+
+/** Set the username used for making connections */
+void
+smbc_setUser(SMBCCTX *c, const char *user);
+
+/**
+ * Get the timeout used for waiting on connections and response data
+ * (in milliseconds)
+ */
+int
+smbc_getTimeout(SMBCCTX *c);
+
+/**
+ * Set the timeout used for waiting on connections and response data
+ * (in milliseconds)
+ */
+void
+smbc_setTimeout(SMBCCTX *c, int timeout);
+
+
+/**
+ * Get the TCP port used to connect (0 means default).
+ */
+uint16_t
+smbc_getPort(SMBCCTX *c);
+
+/**
+ * Set the TCP port used to connect (0 means default).
+ */
+void
+smbc_setPort(SMBCCTX *c, uint16_t port);
+
+/** Get whether to enable POSIX extensions if available */
+smbc_bool
+smbc_getOptionPosixExtensions(SMBCCTX *c);
+
+/** Set whether to enable POSIX extensions if available */
+void
+smbc_setOptionPosixExtensions(SMBCCTX *c, smbc_bool b);
+
+/***********************************
+ * Getters and setters for OPTIONS *
+ ***********************************/
+
+/** Get whether to log to standard error instead of standard output */
+smbc_bool
+smbc_getOptionDebugToStderr(SMBCCTX *c);
+
+/** Set whether to log to standard error instead of standard output */
+void
+smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
+
+/**
+ * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
+ * than the old-style names such as M_TIME.  This allows also setting/getting
+ * CREATE_TIME which was previously unimplemented.  (Note that the old C_TIME
+ * was supposed to be CHANGE_TIME but was confused and sometimes referred to
+ * CREATE_TIME.)
+ */
+smbc_bool
+smbc_getOptionFullTimeNames(SMBCCTX *c);
+
+/**
+ * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
+ * than the old-style names such as M_TIME.  This allows also setting/getting
+ * CREATE_TIME which was previously unimplemented.  (Note that the old C_TIME
+ * was supposed to be CHANGE_TIME but was confused and sometimes referred to
+ * CREATE_TIME.)
+ */
+void
+smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
+
+/**
+ * Get the share mode to use for files opened with SMBC_open_ctx().  The
+ * default is SMBC_SHAREMODE_DENY_NONE.
+ */
+smbc_share_mode
+smbc_getOptionOpenShareMode(SMBCCTX *c);
+
+/**
+ * Set the share mode to use for files opened with SMBC_open_ctx().  The
+ * default is SMBC_SHAREMODE_DENY_NONE.
+ */
+void
+smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
+
+/** Retrieve a previously saved user data handle */
+void *
+smbc_getOptionUserData(SMBCCTX *c);
+
+/** Save a user data handle */
+void
+smbc_setOptionUserData(SMBCCTX *c, void *user_data);
+
+/** Get the encoded value for encryption level. */
+smbc_smb_encrypt_level
+smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
+
+/** Set the encoded value for encryption level. */
+void
+smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
+
+/**
+ * Get whether to treat file names as case-sensitive if we can't determine
+ * when connecting to the remote share whether the file system is case
+ * sensitive. This defaults to FALSE since it's most likely that if we can't
+ * retrieve the file system attributes, it's a very old file system that does
+ * not support case sensitivity.
+ */
+smbc_bool
+smbc_getOptionCaseSensitive(SMBCCTX *c);
+
+/**
+ * Set whether to treat file names as case-sensitive if we can't determine
+ * when connecting to the remote share whether the file system is case
+ * sensitive. This defaults to FALSE since it's most likely that if we can't
+ * retrieve the file system attributes, it's a very old file system that does
+ * not support case sensitivity.
+ */
+void
+smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
+
+
+/**
+ * Get from how many local master browsers should the list of workgroups be
+ * retrieved.  It can take up to 12 minutes or longer after a server becomes a
+ * local master browser, for it to have the entire browse list (the list of
+ * workgroups/domains) from an entire network.  Since a client never knows
+ * which local master browser will be found first, the one which is found
+ * first and used to retrieve a browse list may have an incomplete or empty
+ * browse list.  By requesting the browse list from multiple local master
+ * browsers, a more complete list can be generated.  For small networks (few
+ * workgroups), it is recommended that this value be set to 0, causing the
+ * browse lists from all found local master browsers to be retrieved and
+ * merged.  For networks with many workgroups, a suitable value for this
+ * variable is probably somewhere around 3. (Default: 3).
+ */
+int
+smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
+
+/**
+ * Set from how many local master browsers should the list of workgroups be
+ * retrieved.  It can take up to 12 minutes or longer after a server becomes a
+ * local master browser, for it to have the entire browse list (the list of
+ * workgroups/domains) from an entire network.  Since a client never knows
+ * which local master browser will be found first, the one which is found
+ * first and used to retrieve a browse list may have an incomplete or empty
+ * browse list.  By requesting the browse list from multiple local master
+ * browsers, a more complete list can be generated.  For small networks (few
+ * workgroups), it is recommended that this value be set to 0, causing the
+ * browse lists from all found local master browsers to be retrieved and
+ * merged.  For networks with many workgroups, a suitable value for this
+ * variable is probably somewhere around 3. (Default: 3).
+ */
+void
+smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
+
+/**
+ * Get whether to url-encode readdir entries.
+ *
+ * There is a difference in the desired return strings from
+ * smbc_readdir() depending upon whether the filenames are to
+ * be displayed to the user, or whether they are to be
+ * appended to the path name passed to smbc_opendir() to call
+ * a further smbc_ function (e.g. open the file with
+ * smbc_open()).  In the former case, the filename should be
+ * in "human readable" form.  In the latter case, the smbc_
+ * functions expect a URL which must be url-encoded.  Those
+ * functions decode the URL.  If, for example, smbc_readdir()
+ * returned a file name of "abc%20def.txt", passing a path
+ * with this file name attached to smbc_open() would cause
+ * smbc_open to attempt to open the file "abc def.txt" since
+ * the %20 is decoded into a space.
+ *
+ * Set this option to True if the names returned by
+ * smbc_readdir() should be url-encoded such that they can be
+ * passed back to another smbc_ call.  Set it to False if the
+ * names returned by smbc_readdir() are to be presented to the
+ * user.
+ *
+ * For backwards compatibility, this option defaults to False.
+ */
+smbc_bool
+smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
+
+/**
+ * Set whether to url-encode readdir entries.
+ *
+ * There is a difference in the desired return strings from
+ * smbc_readdir() depending upon whether the filenames are to
+ * be displayed to the user, or whether they are to be
+ * appended to the path name passed to smbc_opendir() to call
+ * a further smbc_ function (e.g. open the file with
+ * smbc_open()).  In the former case, the filename should be
+ * in "human readable" form.  In the latter case, the smbc_
+ * functions expect a URL which must be url-encoded.  Those
+ * functions decode the URL.  If, for example, smbc_readdir()
+ * returned a file name of "abc%20def.txt", passing a path
+ * with this file name attached to smbc_open() would cause
+ * smbc_open to attempt to open the file "abc def.txt" since
+ * the %20 is decoded into a space.
+ *
+ * Set this option to True if the names returned by
+ * smbc_readdir() should be url-encoded such that they can be
+ * passed back to another smbc_ call.  Set it to False if the
+ * names returned by smbc_readdir() are to be presented to the
+ * user.
+ *
+ * For backwards compatibility, this option defaults to False.
+ */
+void
+smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
+
+/**
+ * Get whether to use the same connection for all shares on a server.
+ *
+ * Some Windows versions appear to have a limit to the number
+ * of concurrent SESSIONs and/or TREE CONNECTions.  In
+ * one-shot programs (i.e. the program runs and then quickly
+ * ends, thereby shutting down all connections), it is
+ * probably reasonable to establish a new connection for each
+ * share.  In long-running applications, the limitation can be
+ * avoided by using only a single connection to each server,
+ * and issuing a new TREE CONNECT when the share is accessed.
+ */
+smbc_bool
+smbc_getOptionOneSharePerServer(SMBCCTX *c);
+
+/**
+ * Set whether to use the same connection for all shares on a server.
+ *
+ * Some Windows versions appear to have a limit to the number
+ * of concurrent SESSIONs and/or TREE CONNECTions.  In
+ * one-shot programs (i.e. the program runs and then quickly
+ * ends, thereby shutting down all connections), it is
+ * probably reasonable to establish a new connection for each
+ * share.  In long-running applications, the limitation can be
+ * avoided by using only a single connection to each server,
+ * and issuing a new TREE CONNECT when the share is accessed.
+ */
+void
+smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to enable use of kerberos */
+smbc_bool
+smbc_getOptionUseKerberos(SMBCCTX *c);
+
+/** Set whether to enable use of kerberos */
+void
+smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to fallback after kerberos */
+smbc_bool
+smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
+
+/** Set whether to fallback after kerberos */
+void
+smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to automatically select anonymous login */
+smbc_bool
+smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
+
+/** Set whether to automatically select anonymous login */
+void
+smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
+
+/** Get whether to enable use of the winbind ccache */
+smbc_bool
+smbc_getOptionUseCCache(SMBCCTX *c);
+
+/** Set whether to enable use of the winbind ccache */
+void
+smbc_setOptionUseCCache(SMBCCTX *c, smbc_bool b);
+
+/** Get indication that the password supplied is the NT hash */
+smbc_bool
+smbc_getOptionUseNTHash(SMBCCTX *c);
+
+/** Set indication that the password supplied is the NT hash */
+void
+smbc_setOptionUseNTHash(SMBCCTX *c, smbc_bool b);
+
+/**
+ * @brief Set the 'client min protocol' and the 'client max protocol'.
+ *
+ * IMPORTANT: This overrides the values 'client min protocol' and 'client max
+ * protocol' set in the smb.conf file!
+ *
+ * @param[in]  c  The smbc context to use.
+ *
+ * @param[in]  min_proto  The minimal protocol to use or NULL for leaving it
+ *                        untouched.
+ *
+ * @param[in]  max_proto  The maximum protocol to use or NULL for leaving it
+ *                        untouched.
+ *
+ * @returns true for success, false otherwise
+ */
+smbc_bool
+smbc_setOptionProtocols(SMBCCTX *c, const char *min_proto, const char *max_proto);
+
+/*************************************
+ * Getters and setters for FUNCTIONS *
+ *************************************/
+
+/** Get the function for obtaining authentication data */
+smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
+
+/** Set the function for obtaining authentication data */
+void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
+
+/** Get the new-style authentication function which includes the context. */
+smbc_get_auth_data_with_context_fn
+smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
+
+/** Set the new-style authentication function which includes the context. */
+void
+smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
+                                    smbc_get_auth_data_with_context_fn fn);
+
+/** Get the function for checking if a server is still good */
+smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
+
+/** Set the function for checking if a server is still good */
+void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
+
+/** Get the function for removing a server if unused */
+smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
+
+/** Set the function for removing a server if unused */
+void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
+                                        smbc_remove_unused_server_fn fn);
+
+/** Get the function for adding a cached server */
+smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
+
+/** Set the function for adding a cached server */
+void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
+
+/** Get the function for server cache lookup */
+smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
+
+/** Set the function for server cache lookup */
+void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
+
+/** Get the function for server cache removal */
+smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
+
+/** Set the function for server cache removal */
+void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
+                                        smbc_remove_cached_srv_fn fn);
+
+/**
+ * Get the function for server cache purging.  This function tries to
+ * remove all cached servers (e.g. on disconnect)
+ */
+smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
+
+/**
+ * Set the function for server cache purging.  This function tries to
+ * remove all cached servers (e.g. on disconnect)
+ */
+void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
+                                        smbc_purge_cached_fn fn);
+
+/** Get the function to store private data of the server cache */
+struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
+
+/** Set the function to store private data of the server cache */
+void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
+
+
+
+/*****************************************************************
+ * Callable functions for files.                                 *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter.             *
+ *****************************************************************/
+
+typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
+                                   const char *fname,
+                                   int flags,
+                                   mode_t mode);
+smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
+void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
+
+typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
+                                    const char *path,
+                                    mode_t mode);
+smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
+void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
+
+typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
+                                SMBCFILE *file,
+                                void *buf,
+                                size_t count);
+smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
+void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
+
+typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
+                                 SMBCFILE *file,
+                                 const void *buf,
+                                 size_t count);
+smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
+void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
+
+typedef off_t (*smbc_splice_fn)(SMBCCTX *c,
+                                SMBCFILE *srcfile,
+                                SMBCFILE *dstfile,
+                                off_t count,
+                                int (*splice_cb)(off_t n, void *priv),
+                                void *priv);
+smbc_splice_fn smbc_getFunctionSplice(SMBCCTX *c);
+void smbc_setFunctionSplice(SMBCCTX *c, smbc_splice_fn fn);
+
+typedef int (*smbc_unlink_fn)(SMBCCTX *c,
+                              const char *fname);
+smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
+void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
+
+typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
+                              const char *oname,
+                              SMBCCTX *ncontext,
+                              const char *nname);
+smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
+void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
+
+typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
+                               SMBCFILE * file,
+                               off_t offset,
+                               int whence);
+smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
+void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
+
+typedef int (*smbc_stat_fn)(SMBCCTX *c,
+                            const char *fname,
+                            struct stat *st);
+smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
+void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
+
+typedef int (*smbc_fstat_fn)(SMBCCTX *c,
+                             SMBCFILE *file,
+                             struct stat *st);
+smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
+void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
+
+typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
+                               char *path,
+                               struct statvfs *st);
+smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
+void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
+
+typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
+                                SMBCFILE *file,
+                                struct statvfs *st);
+smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
+void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
+
+typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
+                                 SMBCFILE *f,
+                                 off_t size);
+smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
+void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
+
+typedef int (*smbc_close_fn)(SMBCCTX *c,
+                             SMBCFILE *file);
+smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
+void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
+
+
+
+/*****************************************************************
+ * Callable functions for directories.                           *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter.             *
+ *****************************************************************/
+
+typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
+                                      const char *fname);
+smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
+void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
+
+typedef int (*smbc_closedir_fn)(SMBCCTX *c,
+                                SMBCFILE *dir);
+smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
+void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
+
+typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
+                                                SMBCFILE *dir);
+smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
+void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
+
+typedef const struct libsmb_file_info * (*smbc_readdirplus_fn)(SMBCCTX *c,
+                                                               SMBCFILE *dir);
+smbc_readdirplus_fn smbc_getFunctionReaddirPlus(SMBCCTX *c);
+void smbc_setFunctionReaddirPlus(SMBCCTX *c, smbc_readdirplus_fn fn);
+
+typedef const struct libsmb_file_info * (*smbc_readdirplus2_fn)(SMBCCTX *c,
+					SMBCFILE *dir,
+					struct stat *st);
+smbc_readdirplus2_fn smbc_getFunctionReaddirPlus2(SMBCCTX *c);
+void smbc_setFunctionReaddirPlus2(SMBCCTX *c, smbc_readdirplus2_fn fn);
+
+typedef int (*smbc_getdents_fn)(SMBCCTX *c,
+                                SMBCFILE *dir,
+                                struct smbc_dirent *dirp,
+                                int count);
+smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
+void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
+
+typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
+                             const char *fname,
+                             mode_t mode);
+smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
+void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
+
+typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
+                             const char *fname);
+smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
+void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
+
+typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
+                                 SMBCFILE *dir);
+smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
+void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
+
+typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
+                                SMBCFILE *dir,
+                                off_t offset);
+smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
+void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
+
+typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
+                                SMBCFILE *dir,
+                                struct stat *st);
+smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
+void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
+
+#define SMBC_NOTIFY_ACTION_ADDED		1
+#define SMBC_NOTIFY_ACTION_REMOVED		2
+#define SMBC_NOTIFY_ACTION_MODIFIED		3
+#define SMBC_NOTIFY_ACTION_OLD_NAME		4
+#define SMBC_NOTIFY_ACTION_NEW_NAME		5
+#define SMBC_NOTIFY_ACTION_ADDED_STREAM	6
+#define SMBC_NOTIFY_ACTION_REMOVED_STREAM	7
+#define SMBC_NOTIFY_ACTION_MODIFIED_STREAM	8
+
+struct smbc_notify_callback_action {
+	uint32_t action;
+	const char *filename;
+};
+
+typedef int (*smbc_notify_callback_fn)(
+	const struct smbc_notify_callback_action *actions,
+	size_t num_actions, void *private_data);
+
+typedef int (*smbc_notify_fn)(SMBCCTX *c, SMBCFILE *dir, smbc_bool recursive,
+			      uint32_t completion_filter,
+			      unsigned callback_timeout_ms,
+			      smbc_notify_callback_fn cb, void *private_data);
+smbc_notify_fn smbc_getFunctionNotify(SMBCCTX *c);
+void smbc_setFunctionNotify(SMBCCTX *c, smbc_notify_fn fn);
+
+
+/*****************************************************************
+ * Callable functions applicable to both files and directories.  *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter.             *
+ *****************************************************************/
+
+typedef int (*smbc_chmod_fn)(SMBCCTX *c,
+                             const char *fname,
+                             mode_t mode);
+smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
+void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
+
+typedef int (*smbc_utimes_fn)(SMBCCTX *c,
+                              const char *fname,
+                              struct timeval *tbuf);
+smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
+void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
+
+typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
+                                const char *fname,
+                                const char *name,
+                                const void *value,
+                                size_t size,
+                                int flags);
+smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
+void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
+
+typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
+                                const char *fname,
+                                const char *name,
+                                const void *value,
+                                size_t size);
+smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
+void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
+
+typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
+                                   const char *fname,
+                                   const char *name);
+smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
+void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
+
+typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
+                                 const char *fname,
+                                 char *list,
+                                 size_t size);
+smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
+void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
+
+
+
+/*****************************************************************
+ * Callable functions for printing.                              *
+ * Each callable has a function signature typedef, a declaration *
+ * for the getter, and a declaration for the setter.             *
+ *****************************************************************/
+
+typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
+                                  const char *fname,
+                                  SMBCCTX *c_print,
+                                  const char *printq);
+smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
+void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
+
+typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
+                                             const char *fname);
+smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
+void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
+                                  smbc_open_print_job_fn fn);
+
+typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
+                                       const char *fname,
+                                       smbc_list_print_job_fn fn);
+smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
+void smbc_setFunctionListPrintJobs(SMBCCTX *c,
+                                   smbc_list_print_jobs_fn fn);
+
+typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
+                                        const char *fname,
+                                        int id);
+smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
+void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
+                                    smbc_unlink_print_job_fn fn);
+
+
+/**@ingroup misc
+ * Create a new SBMCCTX (a context).
+ *
+ * Must be called before the context is passed to smbc_context_init()
+ *
+ * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
+ *                  - ENOMEM Out of memory
+ *
+ * @see             smbc_free_context(), smbc_init_context()
+ *
+ * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
+ */
+SMBCCTX * smbc_new_context(void);
+
+/**@ingroup misc
+ * Delete a SBMCCTX (a context) acquired from smbc_new_context().
+ *
+ * The context will be deleted if possible.
+ *
+ * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
+ *
+ * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
+ *
+ *
+ * @return          Returns 0 on success. Returns 1 on failure with errno set:
+ *                  - EBUSY Server connections are still used, Files are open or cache
+ *                          could not be purged
+ *                  - EBADF context == NULL
+ *
+ * @see             smbc_new_context()
+ *
+ * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
+ *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
+ *                  use in periodical cleanup functions for example.
+ */
+int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
+
+
+/**@ingroup misc
+ *
+ * @deprecated.  Use smbc_setOption*() functions instead.
+ */
+void
+smbc_option_set(SMBCCTX *context,
+                char *option_name,
+                ... /* option_value */);
+
+/*
+ * @deprecated.  Use smbc_getOption*() functions instead.
+ */
+void *
+smbc_option_get(SMBCCTX *context,
+                char *option_name);
+
+/**@ingroup misc
+ * Initialize a SBMCCTX (a context).
+ *
+ * Must be called before using any SMBCCTX API function
+ *
+ * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
+ *
+ * @return          A pointer to the given SMBCCTX on success,
+ *                  NULL on error with errno set:
+ *                  - EBADF  NULL context given
+ *                  - ENOMEM Out of memory
+ *                  - ENOENT The smb.conf file would not load
+ *
+ * @see             smbc_new_context()
+ *
+ * @note            my_context = smbc_init_context(smbc_new_context())
+ *                  is perfectly safe, but it might leak memory on
+ *                  smbc_context_init() failure. Avoid this.
+ *                  You'll have to call smbc_free_context() yourself
+ *                  on failure.
+ */
+
+SMBCCTX * smbc_init_context(SMBCCTX * context);
+
+/**@ingroup misc
+ * Initialize the samba client library.
+ *
+ * @deprecated use smbc_init_context()
+ * @see smbc_init_context()
+ */
+DEPRECATED_SMBC_INTERFACE
+int smbc_init(smbc_get_auth_data_fn fn, int debug);
+
+/**@ingroup misc
+ * Set or retrieve the compatibility library's context pointer
+ *
+ * @param context   New context to use, or NULL.  If a new context is provided,
+ *                  it must have allocated with smbc_new_context() and
+ *                  initialized with smbc_init_context(), followed, optionally,
+ *                  by some manual changes to some of the non-internal fields.
+ *
+ * @return          The old context.
+ *
+ * @see             smbc_new_context(), smbc_init_context(), smbc_init()
+ *
+ * @note            This function may be called prior to smbc_init() to force
+ *                  use of the next context without any internal calls to
+ *                  smbc_new_context() or smbc_init_context().  It may also
+ *                  be called after smbc_init() has already called those two
+ *                  functions, to replace the existing context with a new one.
+ *                  Care should be taken, in this latter case, to ensure that
+ *                  the server cache and any data allocated by the
+ *                  authentication functions have been freed, if necessary.
+ */
+
+SMBCCTX * smbc_set_context(SMBCCTX * new_context);
+
+/**@ingroup file
+ * Open a file on an SMB server.
+ *
+ * @param furl      The smb url of the file to be opened.
+ *
+ * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
+ *                  request opening  the  file  read-only,write-only
+ *                  or read/write. flags may also be bitwise-or'd with
+ *                  one or  more of  the following:
+ *                  O_CREAT - If the file does not exist it will be
+ *                  created.
+ *                  O_EXCL - When  used with O_CREAT, if the file
+ *                  already exists it is an error and the open will
+ *                  fail.
+ *                  O_TRUNC - If the file already exists it will be
+ *                  truncated.
+ *                  O_APPEND The  file  is  opened  in  append mode
+ *
+ * @param mode      mode specifies the permissions to use if a new
+ *                  file is created.  It  is  modified  by  the
+ *                  process's umask in the usual way: the permissions
+ *                  of the created file are (mode & ~umask)
+ *
+ *                  Not currently use, but there for future use.
+ *                  We will map this to SYSTEM, HIDDEN, etc bits
+ *                  that reverses the mapping that smbc_fstat does.
+ *
+ * @return          Valid file handle, < 0 on error with errno set:
+ *                  - ENOMEM  Out of memory
+ *                  - EINVAL if an invalid parameter passed, like no
+ *                  file, or smbc_init not called.
+ *                  - EEXIST  pathname already exists and O_CREAT and
+ *                  O_EXCL were used.
+ *                  - EISDIR  pathname  refers  to  a  directory  and
+ *                  the access requested involved writing.
+ *                  - EACCES  The requested access to the file is not
+ *                  allowed
+ *                  - ENODEV The requested share does not exist
+ *                  - ENOTDIR A file on the path is not a directory
+ *                  - ENOENT  A directory component in pathname does
+ *                  not exist.
+ *
+ * @see             smbc_creat()
+ *
+ * @note            This call uses an underlying routine that may create
+ *                  a new connection to the server specified in the URL.
+ *                  If the credentials supplied in the URL, or via the
+ *                  auth_fn in the smbc_init call, fail, this call will
+ *                  try again with an empty username and password. This
+ *                  often gets mapped to the guest account on some machines.
+ */
+
+int smbc_open(const char *furl, int flags, mode_t mode);
+
+/**@ingroup file
+ * Create a file on an SMB server.
+ *
+ * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
+ *
+ * @param furl      The smb url of the file to be created
+ *
+ * @param mode      mode specifies the permissions to use if  a  new
+ *                  file is created.  It  is  modified  by  the
+ *                  process's umask in the usual way: the permissions
+ *                  of the created file are (mode & ~umask)
+ *
+ *                  NOTE, the above is not true. We are dealing with
+ *                  an SMB server, which has no concept of a umask!
+ *
+ * @return          Valid file handle, < 0 on error with errno set:
+ *                  - ENOMEM  Out of memory
+ *                  - EINVAL if an invalid parameter passed, like no
+ *                  file, or smbc_init not called.
+ *                  - EEXIST  pathname already exists and O_CREAT and
+ *                  O_EXCL were used.
+ *                  - EISDIR  pathname  refers  to  a  directory  and
+ *                  the access requested involved writing.
+ *                  - EACCES  The requested access to the file is not
+ *                  allowed
+ *                  - ENOENT  A directory component in pathname does
+ *                  not exist.
+ *                  - ENODEV The requested share does not exist.
+ * @see             smbc_open()
+ *
+ */
+
+int smbc_creat(const char *furl, mode_t mode);
+
+/**@ingroup file
+ * Read from a file using an opened file handle.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param buf       Pointer to buffer to receive read data
+ *
+ * @param bufsize   Size of buf in bytes
+ *
+ * @return          Number of bytes read;
+ *                  0 upon EOF;
+ *                  < 0 on error, with errno set:
+ *                  - EISDIR fd refers to a directory
+ *                  - EBADF  fd  is  not  a valid file descriptor or
+ *                    is not open for reading.
+ *                  - EINVAL fd is attached to an object which is
+ *                    unsuitable for reading, or no buffer passed or
+ *		      smbc_init not called.
+ *
+ * @see             smbc_open(), smbc_write()
+ *
+ */
+ssize_t smbc_read(int fd, void *buf, size_t bufsize);
+
+
+/**@ingroup file
+ * Write to a file using an opened file handle.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param buf       Pointer to buffer to receive read data
+ *
+ * @param bufsize   Size of buf in bytes
+ *
+ * @return          Number of bytes written, < 0 on error with errno set:
+ *                  - EISDIR fd refers to a directory.
+ *                  - EBADF  fd  is  not  a valid file descriptor or
+ *                  is not open for reading.
+ *                  - EINVAL fd is attached to an object which is
+ *                  unsuitable for reading, or no buffer passed or
+ *		    smbc_init not called.
+ *
+ * @see             smbc_open(), smbc_read()
+ *
+ */
+ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
+
+
+/**@ingroup file
+ * Seek to a specific location in a file.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param offset    Offset in bytes from whence
+ *
+ * @param whence    A location in the file:
+ *                  - SEEK_SET The offset is set to offset bytes from
+ *                  the beginning of the file
+ *                  - SEEK_CUR The offset is set to current location
+ *                  plus offset bytes.
+ *                  - SEEK_END The offset is set to the size of the
+ *                  file plus offset bytes.
+ *
+ * @return          Upon successful completion, lseek returns the
+ *                  resulting offset location as measured in bytes
+ *                  from the beginning  of the file. Otherwise, a value
+ *                  of (off_t)-1 is returned and errno is set to
+ *                  indicate the error:
+ *                  - EBADF  Fildes is not an open file descriptor.
+ *                  - EINVAL Whence is not a proper value or smbc_init
+ *		      not called.
+ *
+ * @todo Are all the whence values really supported?
+ *
+ * @todo Are errno values complete and correct?
+ */
+off_t smbc_lseek(int fd, off_t offset, int whence);
+
+
+/**@ingroup file
+ * Close an open file handle.
+ *
+ * @param fd        The file handle to close
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF  fd isn't a valid open file descriptor
+ *                  - EINVAL smbc_init() failed or has not been called
+ *
+ * @see             smbc_open(), smbc_creat()
+ */
+int smbc_close(int fd);
+
+
+/**@ingroup directory
+ * Unlink (delete) a file or directory.
+ *
+ * @param furl      The smb url of the file to delete
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EACCES or EPERM Write  access  to the directory
+ *                  containing pathname is not allowed or one
+ *                  of  the  directories in pathname did not allow
+ *                  search (execute) permission
+ *                  - ENOENT A directory component in pathname does
+ *                  not exist
+ *                  - EINVAL NULL was passed in the file param or
+ *		      smbc_init not called.
+ *                  - EACCES You do not have access to the file
+ *                  - ENOMEM Insufficient kernel memory was available
+ *
+ * @see             smbc_rmdir()s
+ *
+ * @todo Are errno values complete and correct?
+ */
+int smbc_unlink(const char *furl);
+
+
+/**@ingroup directory
+ * Rename or move a file or directory.
+ *
+ * @param ourl      The original smb url (source url) of file or
+ *                  directory to be moved
+ *
+ * @param nurl      The new smb url (destination url) of the file
+ *                  or directory after the move.  Currently nurl must
+ *                  be on the same share as ourl.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EISDIR nurl is an existing directory, but ourl is
+ *                  not a directory.
+ *                  - EEXIST nurl is  a  non-empty directory,
+ *                  i.e., contains entries other than "." and ".."
+ *                  - EINVAL The  new  url  contained  a path prefix
+ *                  of the old, or, more generally, an  attempt was
+ *                  made  to make a directory a subdirectory of itself
+ *		    or smbc_init not called.
+ *                  - ENOTDIR A component used as a directory in ourl
+ *                  or nurl path is not, in fact, a directory.  Or,
+ *                  ourl  is a directory, and newpath exists but is not
+ *                  a directory.
+ *                  - EACCES or EPERM Write access to the directory
+ *                  containing ourl or nurl is not allowed for the
+ *                  process's effective uid,  or  one of the
+ *                  directories in ourl or nurl did not allow search
+ *                  (execute) permission,  or ourl  was  a  directory
+ *                  and did not allow write permission.
+ *                  - ENOENT A  directory component in ourl or nurl
+ *                  does not exist.
+ *                  - EXDEV Rename across shares not supported.
+ *                  - ENOMEM Insufficient kernel memory was available.
+ *                  - EEXIST The target file, nurl, already exists.
+ *
+ *
+ * @todo Are we going to support copying when urls are not on the same
+ *       share?  I say no... NOTE. I agree for the moment.
+ *
+ */
+int smbc_rename(const char *ourl, const char *nurl);
+
+
+/**@ingroup directory
+ * Open a directory used to obtain directory entries.
+ *
+ * @param durl      The smb url of the directory to open
+ *
+ * @return          Valid directory handle. < 0 on error with errno set:
+ *                  - EACCES Permission denied.
+ *                  - EINVAL A NULL file/URL was passed, or the URL would
+ *                  not parse, or was of incorrect form or smbc_init not
+ *                  called.
+ *                  - ENOENT durl does not exist, or name is an
+ *                  - ENOMEM Insufficient memory to complete the
+ *                  operation.
+ *                  - ENOTDIR name is not a directory.
+ *                  - EPERM the workgroup could not be found.
+ *                  - ENODEV the workgroup or server could not be found.
+ *
+ * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
+ *
+ */
+int smbc_opendir(const char *durl);
+
+
+/**@ingroup directory
+ * Close a directory handle opened by smbc_opendir().
+ *
+ * @param dh        Directory handle to close
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF dh is an invalid directory handle
+ *
+ * @see             smbc_opendir()
+ */
+int smbc_closedir(int dh);
+
+
+/**@ingroup directory
+ * Get multiple directory entries.
+ *
+ * smbc_getdents() reads as many dirent structures from the an open
+ * directory handle into a specified memory area as will fit.
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @param dirp      pointer to buffer that will receive the directory
+ *                  entries.
+ *
+ * @param count     The size of the dirp buffer in bytes
+ *
+ * @returns         If any dirents returned, return will indicate the
+ *                  total size. If there were no more dirents available,
+ *                  0 is returned. < 0 indicates an error.
+ *                  - EBADF  Invalid directory handle
+ *                  - EINVAL Result buffer is too small or smbc_init
+ *		    not called.
+ *                  - ENOENT No such directory.
+ * @see             , smbc_dirent, smbc_readdir(), smbc_open()
+ *
+ * @todo Are errno values complete and correct?
+ *
+ * @todo Add example code so people know how to parse buffers.
+ */
+int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
+
+
+/**@ingroup directory
+ * Get a single directory entry.
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @return          A pointer to a smbc_dirent structure, or NULL if an
+ *                  error occurs or end-of-directory is reached:
+ *                  - EBADF Invalid directory handle
+ *                  - EINVAL smbc_init() failed or has not been called
+ *
+ * @see             smbc_dirent, smbc_getdents(), smbc_open()
+ */
+struct smbc_dirent* smbc_readdir(unsigned int dh);
+
+/**@ingroup directory
+ * Works similar as smbc_readdir() but returns more information about file.
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @return          A const pointer to a libsmb_file_info structure,
+ *                  or NULL if an error occurs or end-of-directory is reached:
+ *                  - EBADF Invalid directory handle
+ *                  - EINVAL smbc_init() failed or has not been called
+ *
+ * @see             smbc_open(), smbc_readdir()
+ */
+const struct libsmb_file_info *smbc_readdirplus(unsigned int dh);
+
+/**@ingroup directory
+ * Works similar as smbc_readdirplus() as well as fills up stat structure if
+ * provided.
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @param stat      Pointer to stat structure which will receive the
+ *                  information. If this pointer is null the call
+ *                  is identical to smbc_readdirplus.
+ *
+ * @return          A const pointer to a libsmb_file_info structure,
+ *                  or NULL if an error occurs or end-of-directory is reached:
+ *                  - EBADF Invalid directory handle
+ *                  - EINVAL smbc_init() failed or has not been called
+ *
+ * @see             smbc_open(), smbc_readdir(), smbc_readdirplus2()
+ */
+const struct libsmb_file_info *smbc_readdirplus2(unsigned int dh,
+					struct stat *st);
+
+/**@ingroup directory
+ * Get the current directory offset.
+ *
+ * smbc_telldir() may be used in conjunction with smbc_readdir() and
+ * smbc_lseekdir().
+ *
+ * @param dh        Valid directory as returned by smbc_opendir()
+ *
+ * @return          The current location in the directory stream or -1
+ *                  if an error occur.  The current location is not
+ *                  an offset. Because of the implementation, it is a
+ *                  handle that allows the library to find the entry
+ *                  later.
+ *                  - EBADF dh is not a valid directory handle
+ *                  - EINVAL smbc_init() failed or has not been called
+ *                  - ENOTDIR if dh is not a directory
+ *
+ * @see             smbc_readdir()
+ *
+ */
+off_t smbc_telldir(int dh);
+
+
+/**@ingroup directory
+ * lseek on directories.
+ *
+ * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
+ * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
+ *
+ * @param fd        Valid directory as returned by smbc_opendir()
+ *
+ * @param offset    The offset (as returned by smbc_telldir). Can be
+ *                  NULL, in which case we will rewind
+ *
+ * @return          0 on success, -1 on failure
+ *                  - EBADF dh is not a valid directory handle
+ *                  - ENOTDIR if dh is not a directory
+ *                  - EINVAL offset did not refer to a valid dirent or
+ *		      smbc_init not called.
+ *
+ * @see             smbc_telldir()
+ *
+ *
+ * @todo In what does the return and errno values mean?
+ */
+int smbc_lseekdir(int fd, off_t offset);
+
+/**@ingroup directory
+ * Create a directory.
+ *
+ * @param durl      The url of the directory to create
+ *
+ * @param mode      Specifies  the  permissions to use. It is modified
+ *                  by the process's umask in the usual way: the
+ *                  permissions of the created file are (mode & ~umask).
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EEXIST directory url already exists
+ *                  - EACCES The parent directory does not allow write
+ *                  permission to the process, or one of the directories
+ *                  - ENOENT A directory component in pathname does not
+ *                  exist.
+ *                  - EINVAL NULL durl passed or smbc_init not called.
+ *                  - ENOMEM Insufficient memory was available.
+ *
+ * @see             smbc_rmdir()
+ *
+ */
+int smbc_mkdir(const char *durl, mode_t mode);
+
+
+/**@ingroup directory
+ * Remove a directory.
+ *
+ * @param durl      The smb url of the directory to remove
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EACCES or EPERM Write access to the directory
+ *                  containing pathname was not allowed.
+ *                  - EINVAL durl is NULL or smbc_init not called.
+ *                  - ENOENT A directory component in pathname does not
+ *                  exist.
+ *                  - ENOTEMPTY directory contains entries.
+ *                  - ENOMEM Insufficient kernel memory was available.
+ *
+ * @see             smbc_mkdir(), smbc_unlink()
+ *
+ * @todo Are errno values complete and correct?
+ */
+int smbc_rmdir(const char *durl);
+
+/**@ingroup directory
+ * Request directory notifications
+ *
+ * @param dh                    Valid directory as returned by smbc_opendir()
+ *
+ * @param recursive     	Are changes in subdirectories wanted?
+ *
+ * @param completion_filter	Bitwise-or of the SMBC_NOTIFY_CHANGE_*
+ *                              events that are interesting
+ *
+ * @param callback_timeout_ms   If set to non-zero, interval in milliseconds
+ *                              that "cb" will be called with 0 actions.
+ *                              This gives "cb" the chance to cancel the
+ *                              smbc_notify call.
+ *
+ * @param cb                    Callback functions taking events. If "cb"
+ *                              returns nonzero, smbc_notify will return.
+ *
+ * @param private_data          Pointer given to "cb"
+ *
+ * @return                      0 on success, -1 on error with errno set
+ *
+ * @see                         smbc_opendir(), smbc_closedir()
+ */
+
+#define SMBC_NOTIFY_CHANGE_FILE_NAME		0x001
+#define SMBC_NOTIFY_CHANGE_DIR_NAME		0x002
+#define SMBC_NOTIFY_CHANGE_ATTRIBUTES		0x004
+#define SMBC_NOTIFY_CHANGE_SIZE		0x008
+#define SMBC_NOTIFY_CHANGE_LAST_WRITE		0x010
+#define SMBC_NOTIFY_CHANGE_LAST_ACCESS		0x020
+#define SMBC_NOTIFY_CHANGE_CREATION		0x040
+#define SMBC_NOTIFY_CHANGE_EA			0x080
+#define SMBC_NOTIFY_CHANGE_SECURITY		0x100
+#define SMBC_NOTIFY_CHANGE_STREAM_NAME		0x200
+#define SMBC_NOTIFY_CHANGE_STREAM_SIZE		0x400
+#define SMBC_NOTIFY_CHANGE_STREAM_WRITE	0x800
+
+int smbc_notify(int dh, smbc_bool recursive, uint32_t completion_filter,
+		unsigned callback_timeout_ms,
+		smbc_notify_callback_fn cb, void *private_data);
+
+/**@ingroup attribute
+ * Get information about a file or directory.
+ *
+ * @param url       The smb url to get information for
+ *
+ * @param st        pointer to a buffer that will be filled with
+ *                  standard Unix struct stat information.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - ENOENT A component of the path file_name does not
+ *                  exist.
+ *                  - EINVAL a NULL url was passed or smbc_init not called.
+ *                  - EACCES Permission denied.
+ *                  - ENOMEM Out of memory
+ *                  - ENOTDIR The target dir, url, is not a directory.
+ *
+ * @see             Unix stat()
+ *
+ */
+int smbc_stat(const char *url, struct stat *st);
+
+
+/**@ingroup attribute
+ * Get file information via an file descriptor.
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param st        pointer to a buffer that will be filled with
+ *                  standard Unix struct stat information.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF  filedes is bad.
+ *                  - EACCES Permission denied.
+ *                  - EBADF fd is not a valid file descriptor
+ *                  - EINVAL Problems occurred in the underlying routines
+ *		      or smbc_init not called.
+ *                  - ENOMEM Out of memory
+ *
+ * @see             smbc_stat(), Unix stat()
+ *
+ */
+int smbc_fstat(int fd, struct stat *st);
+
+
+/**@ingroup attribute
+ * Get file system information for a specified path.
+ *
+ * @param url       The smb url to get information for
+ *
+ * @param st        pointer to a buffer that will be filled with
+ *                  standard Unix struct statvfs information.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF  filedes is bad.
+ *                  - EACCES Permission denied.
+ *                  - EBADF fd is not a valid file descriptor
+ *                  - EINVAL Problems occurred in the underlying routines
+ *		      or smbc_init not called.
+ *                  - ENOMEM Out of memory
+ *
+ * @see             Unix fstatvfs()
+ *
+ */
+int
+smbc_statvfs(char *url,
+             struct statvfs *st);
+
+/**@ingroup attribute
+ * Get file system information via an file descriptor.
+ *
+ * @param fd        Open file handle from smbc_open(), smbc_creat(),
+ *                  or smbc_opendir()
+ *
+ * @param st        pointer to a buffer that will be filled with
+ *                  standard Unix struct statvfs information.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF  filedes is bad.
+ *                  - EACCES Permission denied.
+ *                  - EBADF fd is not a valid file descriptor
+ *                  - EINVAL Problems occurred in the underlying routines
+ *		      or smbc_init not called.
+ *                  - ENOMEM Out of memory
+ *
+ * @see             Unix fstatvfs()
+ *
+ */
+int
+smbc_fstatvfs(int fd,
+              struct statvfs *st);
+
+
+/**@ingroup attribute
+ * Truncate a file given a file descriptor
+ *
+ * @param fd        Open file handle from smbc_open() or smbc_creat()
+ *
+ * @param size      size to truncate the file to
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EBADF  filedes is bad.
+ *                  - EACCES Permission denied.
+ *                  - EBADF fd is not a valid file descriptor
+ *                  - EINVAL Problems occurred in the underlying routines
+ *		      or smbc_init not called.
+ *                  - ENOMEM Out of memory
+ *
+ * @see             , Unix ftruncate()
+ *
+ */
+int smbc_ftruncate(int fd, off_t size);
+
+
+/**@ingroup attribute
+ * Change the permissions of a file.
+ *
+ * @param url       The smb url of the file or directory to change
+ *                  permissions of
+ *
+ * @param mode      The permissions to set:
+ *                  - Put good explanation of permissions here!
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EPERM  The effective UID does not match the owner
+ *                  of the file, and is not zero
+ *                  - ENOENT The file does not exist.
+ *                  - ENOMEM Insufficient was available.
+ *                  - ENOENT file or directory does not exist
+ *
+ * @todo Actually implement this function?
+ *
+ * @todo Are errno values complete and correct?
+ */
+int smbc_chmod(const char *url, mode_t mode);
+
+/**
+ * @ingroup attribute
+ * Change the last modification time on a file
+ *
+ * @param url       The smb url of the file or directory to change
+ *                  the modification time of
+ *
+ * @param tbuf      An array of two timeval structures which contains,
+ *                  respectively, the desired access and modification times.
+ *                  NOTE: Only the tv_sec field off each timeval structure is
+ *                  used.  The tv_usec (microseconds) portion is ignored.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - EPERM  Permission was denied.
+ *
+ */
+int smbc_utimes(const char *url, struct timeval *tbuf);
+
+#ifdef HAVE_UTIME_H
+/**
+ * @ingroup attribute
+ * Change the last modification time on a file
+ *
+ * @param url       The smb url of the file or directory to change
+ *                  the modification time of
+ *
+ * @param utbuf     A pointer to a utimebuf structure which contains the
+ *                  desired access and modification times.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *
+ */
+int smbc_utime(const char *fname, struct utimbuf *utbuf);
+#endif
+
+/**@ingroup attribute
+ * Set extended attributes for a file.  This is used for modifying a file's
+ * security descriptor (i.e. owner, group, and access control list)
+ *
+ * @param url       The smb url of the file or directory to set extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be changed.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter should contain a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @param value     The value to be assigned to the specified attribute name.
+ *                  This buffer should contain only the attribute value if the
+ *                  name was of the "system.nt_sec_desc.<attribute_name>"
+ *                  form.  If the name was of the "system.nt_sec_desc.*" form
+ *                  then a complete security descriptor, with name:value pairs
+ *                  separated by tabs, commas, or newlines (not spaces!),
+ *                  should be provided in this value buffer.  A complete
+ *                  security descriptor will contain one or more entries
+ *                  selected from the following:
+ *
+ *                    REVISION:<revision number>
+ *                    OWNER:<sid or name>
+ *                    GROUP:<sid or name>
+ *                    ACL:<sid or name>:<type>/<flags>/<mask>
+ *
+ *                  The  revision of the ACL specifies the internal Windows NT
+ *                  ACL revision for the security descriptor. If not specified
+ *                  it defaults to  1.  Using values other than 1 may cause
+ *                  strange behaviour.
+ *
+ *                  The owner and group specify the owner and group sids for
+ *                  the object. If the attribute name (either '*+' with a
+ *                  complete security descriptor, or individual 'owner+' or
+ *                  'group+' attribute names) ended with a plus sign, the
+ *                  specified name is resolved to a SID value, using the
+ *                  server on which the file or directory resides.  Otherwise,
+ *                  the value should be provided in SID-printable format as
+ *                  S-1-x-y-z, and is used directly.  The <sid or name>
+ *                  associated with the ACL: attribute should be provided
+ *                  similarly.
+ *
+ * @param size      The number of the bytes of data in the value buffer
+ *
+ * @param flags     A bit-wise OR of zero or more of the following:
+ *                    SMBC_XATTR_FLAG_CREATE -
+ *                      fail if the named attribute already exists
+ *                    SMBC_XATTR_FLAG_REPLACE -
+ *                      fail if the attribute does not already exist
+ *
+ *                  If neither flag is specified, the specified attributes
+ *                  will be added or replace existing attributes of the same
+ *                  name, as necessary.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL  The client library is not properly initialized
+ *                            or one of the parameters is not of a correct
+ *                            form
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EEXIST  If the attribute already exists and the flag
+ *                            SMBC_XATTR_FLAG_CREAT was specified
+ *                  - ENOATTR If the attribute does not exist and the flag
+ *                            SMBC_XATTR_FLAG_REPLACE was specified
+ *                  - EPERM   Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ * @note            Attribute names are compared in a case-insensitive
+ *                  fashion.  All of the following are equivalent, although
+ *                  the all-lower-case name is the preferred format:
+ *                    system.nt_sec_desc.owner
+ *                    SYSTEM.NT_SEC_DESC.OWNER
+ *                    sYsTeM.nt_sEc_desc.owNER
+ *
+ */
+int smbc_setxattr(const char *url,
+                  const char *name,
+                  const void *value,
+                  size_t size,
+                  int flags);
+
+
+/**@ingroup attribute
+ * Set extended attributes for a file.  This is used for modifying a file's
+ * security descriptor (i.e. owner, group, and access control list).  The
+ * POSIX function which this maps to would act on a symbolic link rather than
+ * acting on what the symbolic link points to, but with no symbolic links in
+ * SMB file systems, this function is functionally identical to
+ * smbc_setxattr().
+ *
+ * @param url       The smb url of the file or directory to set extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be changed.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter should contain a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @param value     The value to be assigned to the specified attribute name.
+ *                  This buffer should contain only the attribute value if the
+ *                  name was of the "system.nt_sec_desc.<attribute_name>"
+ *                  form.  If the name was of the "system.nt_sec_desc.*" form
+ *                  then a complete security descriptor, with name:value pairs
+ *                  separated by tabs, commas, or newlines (not spaces!),
+ *                  should be provided in this value buffer.  A complete
+ *                  security descriptor will contain one or more entries
+ *                  selected from the following:
+ *
+ *                    REVISION:<revision number>
+ *                    OWNER:<sid or name>
+ *                    GROUP:<sid or name>
+ *                    ACL:<sid or name>:<type>/<flags>/<mask>
+ *
+ *                  The  revision of the ACL specifies the internal Windows NT
+ *                  ACL revision for the security descriptor. If not specified
+ *                  it defaults to  1.  Using values other than 1 may cause
+ *                  strange behaviour.
+ *
+ *                  The owner and group specify the owner and group sids for
+ *                  the object. If the attribute name (either '*+' with a
+ *                  complete security descriptor, or individual 'owner+' or
+ *                  'group+' attribute names) ended with a plus sign, the
+ *                  specified name is resolved to a SID value, using the
+ *                  server on which the file or directory resides.  Otherwise,
+ *                  the value should be provided in SID-printable format as
+ *                  S-1-x-y-z, and is used directly.  The <sid or name>
+ *                  associated with the ACL: attribute should be provided
+ *                  similarly.
+ *
+ * @param size      The number of the bytes of data in the value buffer
+ *
+ * @param flags     A bit-wise OR of zero or more of the following:
+ *                    SMBC_XATTR_FLAG_CREATE -
+ *                      fail if the named attribute already exists
+ *                    SMBC_XATTR_FLAG_REPLACE -
+ *                      fail if the attribute does not already exist
+ *
+ *                  If neither flag is specified, the specified attributes
+ *                  will be added or replace existing attributes of the same
+ *                  name, as necessary.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL  The client library is not properly initialized
+ *                            or one of the parameters is not of a correct
+ *                            form
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EEXIST  If the attribute already exists and the flag
+ *                            SMBC_XATTR_FLAG_CREAT was specified
+ *                  - ENOATTR If the attribute does not exist and the flag
+ *                            SMBC_XATTR_FLAG_REPLACE was specified
+ *                  - EPERM   Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ * @note            Attribute names are compared in a case-insensitive
+ *                  fashion.  All of the following are equivalent, although
+ *                  the all-lower-case name is the preferred format:
+ *                    system.nt_sec_desc.owner
+ *                    SYSTEM.NT_SEC_DESC.OWNER
+ *                    sYsTeM.nt_sEc_desc.owNER
+ *
+ */
+int smbc_lsetxattr(const char *url,
+                   const char *name,
+                   const void *value,
+                   size_t size,
+                   int flags);
+
+
+/**@ingroup attribute
+ * Set extended attributes for a file.  This is used for modifying a file's
+ * security descriptor (i.e. owner, group, and access control list)
+ *
+ * @param fd        A file descriptor associated with an open file (as
+ *                  previously returned by smbc_open(), to get extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be changed.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter should contain a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @param value     The value to be assigned to the specified attribute name.
+ *                  This buffer should contain only the attribute value if the
+ *                  name was of the "system.nt_sec_desc.<attribute_name>"
+ *                  form.  If the name was of the "system.nt_sec_desc.*" form
+ *                  then a complete security descriptor, with name:value pairs
+ *                  separated by tabs, commas, or newlines (not spaces!),
+ *                  should be provided in this value buffer.  A complete
+ *                  security descriptor will contain one or more entries
+ *                  selected from the following:
+ *
+ *                    REVISION:<revision number>
+ *                    OWNER:<sid or name>
+ *                    GROUP:<sid or name>
+ *                    ACL:<sid or name>:<type>/<flags>/<mask>
+ *
+ *                  The  revision of the ACL specifies the internal Windows NT
+ *                  ACL revision for the security descriptor. If not specified
+ *                  it defaults to  1.  Using values other than 1 may cause
+ *                  strange behaviour.
+ *
+ *                  The owner and group specify the owner and group sids for
+ *                  the object. If the attribute name (either '*+' with a
+ *                  complete security descriptor, or individual 'owner+' or
+ *                  'group+' attribute names) ended with a plus sign, the
+ *                  specified name is resolved to a SID value, using the
+ *                  server on which the file or directory resides.  Otherwise,
+ *                  the value should be provided in SID-printable format as
+ *                  S-1-x-y-z, and is used directly.  The <sid or name>
+ *                  associated with the ACL: attribute should be provided
+ *                  similarly.
+ *
+ * @param size      The number of the bytes of data in the value buffer
+ *
+ * @param flags     A bit-wise OR of zero or more of the following:
+ *                    SMBC_XATTR_FLAG_CREATE -
+ *                      fail if the named attribute already exists
+ *                    SMBC_XATTR_FLAG_REPLACE -
+ *                      fail if the attribute does not already exist
+ *
+ *                  If neither flag is specified, the specified attributes
+ *                  will be added or replace existing attributes of the same
+ *                  name, as necessary.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL  The client library is not properly initialized
+ *                            or one of the parameters is not of a correct
+ *                            form
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EEXIST  If the attribute already exists and the flag
+ *                            SMBC_XATTR_FLAG_CREAT was specified
+ *                  - ENOATTR If the attribute does not exist and the flag
+ *                            SMBC_XATTR_FLAG_REPLACE was specified
+ *                  - EPERM   Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ * @note            Attribute names are compared in a case-insensitive
+ *                  fashion.  All of the following are equivalent, although
+ *                  the all-lower-case name is the preferred format:
+ *                    system.nt_sec_desc.owner
+ *                    SYSTEM.NT_SEC_DESC.OWNER
+ *                    sYsTeM.nt_sEc_desc.owNER
+ *
+ */
+int smbc_fsetxattr(int fd,
+                   const char *name,
+                   const void *value,
+                   size_t size,
+                   int flags);
+
+
+/**@ingroup attribute
+ * Get extended attributes for a file.
+ *
+ * @param url       The smb url of the file or directory to get extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be retrieved.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter will return a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @param value     A pointer to a buffer in which the value of the specified
+ *                  attribute will be placed (unless size is zero).
+ *
+ * @param size      The size of the buffer pointed to by value.  This parameter
+ *                  may also be zero, in which case the size of the buffer
+ *                  required to hold the attribute value will be returned,
+ *                  but nothing will be placed into the value buffer.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL  The client library is not properly initialized
+ *                            or one of the parameters is not of a correct
+ *                            form
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EEXIST  If the attribute already exists and the flag
+ *                            SMBC_XATTR_FLAG_CREAT was specified
+ *                  - ENOATTR If the attribute does not exist and the flag
+ *                            SMBC_XATTR_FLAG_REPLACE was specified
+ *                  - EPERM   Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ */
+int smbc_getxattr(const char *url,
+                  const char *name,
+                  const void *value,
+                  size_t size);
+
+
+/**@ingroup attribute
+ * Get extended attributes for a file.  The POSIX function which this maps to
+ * would act on a symbolic link rather than acting on what the symbolic link
+ * points to, but with no symbolic links in SMB file systems, this function
+ * is functionally identical to smbc_getxattr().
+ *
+ * @param url       The smb url of the file or directory to get extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be retrieved.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter will return a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @param value     A pointer to a buffer in which the value of the specified
+ *                  attribute will be placed (unless size is zero).
+ *
+ * @param size      The size of the buffer pointed to by value.  This parameter
+ *                  may also be zero, in which case the size of the buffer
+ *                  required to hold the attribute value will be returned,
+ *                  but nothing will be placed into the value buffer.
+ *
+ * @return          size on success, < 0 on error with errno set:
+ *                  - EINVAL  The client library is not properly initialized
+ *                            or one of the parameters is not of a correct
+ *                            form
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EEXIST  If the attribute already exists and the flag
+ *                            SMBC_XATTR_FLAG_CREAT was specified
+ *                  - ENOATTR If the attribute does not exist and the flag
+ *                            SMBC_XATTR_FLAG_REPLACE was specified
+ *                  - EPERM   Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ */
+int smbc_lgetxattr(const char *url,
+                   const char *name,
+                   const void *value,
+                   size_t size);
+
+
+/**@ingroup attribute
+ * Get extended attributes for a file.
+ *
+ * @param fd        A file descriptor associated with an open file (as
+ *                  previously returned by smbc_open(), to get extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be retrieved.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter will return a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @param value     A pointer to a buffer in which the value of the specified
+ *                  attribute will be placed (unless size is zero).
+ *
+ * @param size      The size of the buffer pointed to by value.  This parameter
+ *                  may also be zero, in which case the size of the buffer
+ *                  required to hold the attribute value will be returned,
+ *                  but nothing will be placed into the value buffer.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL  The client library is not properly initialized
+ *                            or one of the parameters is not of a correct
+ *                            form
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EEXIST  If the attribute already exists and the flag
+ *                            SMBC_XATTR_FLAG_CREAT was specified
+ *                  - ENOATTR If the attribute does not exist and the flag
+ *                            SMBC_XATTR_FLAG_REPLACE was specified
+ *                  - EPERM   Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ */
+int smbc_fgetxattr(int fd,
+                   const char *name,
+                   const void *value,
+                   size_t size);
+
+
+/**@ingroup attribute
+ * Remove extended attributes for a file.  This is used for modifying a file's
+ * security descriptor (i.e. owner, group, and access control list)
+ *
+ * @param url       The smb url of the file or directory to remove the extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be removed.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter will return a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ */
+int smbc_removexattr(const char *url,
+                     const char *name);
+
+
+/**@ingroup attribute
+ * Remove extended attributes for a file.  This is used for modifying a file's
+ * security descriptor (i.e. owner, group, and access control list) The POSIX
+ * function which this maps to would act on a symbolic link rather than acting
+ * on what the symbolic link points to, but with no symbolic links in SMB file
+ * systems, this function is functionally identical to smbc_removexattr().
+ *
+ * @param url       The smb url of the file or directory to remove the extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be removed.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter will return a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ */
+int smbc_lremovexattr(const char *url,
+                      const char *name);
+
+
+/**@ingroup attribute
+ * Remove extended attributes for a file.  This is used for modifying a file's
+ * security descriptor (i.e. owner, group, and access control list)
+ *
+ * @param fd        A file descriptor associated with an open file (as
+ *                  previously returned by smbc_open(), to get extended
+ *                  attributes for.
+ *
+ * @param name      The name of an attribute to be removed.  Names are of
+ *                  one of the following forms:
+ *
+ *                     system.nt_sec_desc.<attribute name>
+ *                     system.nt_sec_desc.*
+ *                     system.nt_sec_desc.*+
+ *
+ *                  where <attribute name> is one of:
+ *
+ *                     revision
+ *                     owner
+ *                     owner+
+ *                     group
+ *                     group+
+ *                     acl:<name or sid>
+ *                     acl+:<name or sid>
+ *
+ *                  In the forms "system.nt_sec_desc.*" and
+ *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
+ *                  literal, i.e. the string is provided exactly as shown, and
+ *                  the value parameter will return a complete security
+ *                  descriptor with name:value pairs separated by tabs,
+ *                  commas, or newlines (not spaces!).
+ *
+ *                  The plus sign ('+') indicates that SIDs should be mapped
+ *                  to names.  Without the plus sign, SIDs are not mapped;
+ *                  rather they are simply converted to a string format.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ */
+int smbc_fremovexattr(int fd,
+                      const char *name);
+
+
+/**@ingroup attribute
+ * List the supported extended attribute names associated with a file
+ *
+ * @param url       The smb url of the file or directory to list the extended
+ *                  attributes for.
+ *
+ * @param list      A pointer to a buffer in which the list of attributes for
+ *                  the specified file or directory will be placed (unless
+ *                  size is zero).
+ *
+ * @param size      The size of the buffer pointed to by list.  This parameter
+ *                  may also be zero, in which case the size of the buffer
+ *                  required to hold all of the attribute names will be
+ *                  returned, but nothing will be placed into the list buffer.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ * @note            This function always returns all attribute names supported
+ *                  by NT file systems, regardless of whether the referenced
+ *                  file system supports extended attributes (e.g. a Windows
+ *                  2000 machine supports extended attributes if NTFS is used,
+ *                  but not if FAT is used, and Windows 98 doesn't support
+ *                  extended attributes at all.  Whether this is a feature or
+ *                  a bug is yet to be decided.
+ */
+int smbc_listxattr(const char *url,
+                   char *list,
+                   size_t size);
+
+/**@ingroup attribute
+ * List the supported extended attribute names associated with a file The
+ * POSIX function which this maps to would act on a symbolic link rather than
+ * acting on what the symbolic link points to, but with no symbolic links in
+ * SMB file systems, this function is functionally identical to
+ * smbc_listxattr().
+ *
+ * @param url       The smb url of the file or directory to list the extended
+ *                  attributes for.
+ *
+ * @param list      A pointer to a buffer in which the list of attributes for
+ *                  the specified file or directory will be placed (unless
+ *                  size is zero).
+ *
+ * @param size      The size of the buffer pointed to by list.  This parameter
+ *                  may also be zero, in which case the size of the buffer
+ *                  required to hold all of the attribute names will be
+ *                  returned, but nothing will be placed into the list buffer.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ * @note            This function always returns all attribute names supported
+ *                  by NT file systems, regardless of whether the referenced
+ *                  file system supports extended attributes (e.g. a Windows
+ *                  2000 machine supports extended attributes if NTFS is used,
+ *                  but not if FAT is used, and Windows 98 doesn't support
+ *                  extended attributes at all.  Whether this is a feature or
+ *                  a bug is yet to be decided.
+ */
+int smbc_llistxattr(const char *url,
+                    char *list,
+                    size_t size);
+
+/**@ingroup attribute
+ * List the supported extended attribute names associated with a file
+ *
+ * @param fd        A file descriptor associated with an open file (as
+ *                  previously returned by smbc_open(), to get extended
+ *                  attributes for.
+ *
+ * @param list      A pointer to a buffer in which the list of attributes for
+ *                  the specified file or directory will be placed (unless
+ *                  size is zero).
+ *
+ * @param size      The size of the buffer pointed to by list.  This parameter
+ *                  may also be zero, in which case the size of the buffer
+ *                  required to hold all of the attribute names will be
+ *                  returned, but nothing will be placed into the list buffer.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL The client library is not properly initialized
+ *                  - ENOMEM No memory was available for internal needs
+ *                  - EPERM  Permission was denied.
+ *                  - ENOTSUP The referenced file system does not support
+ *                            extended attributes
+ *
+ * @note            This function always returns all attribute names supported
+ *                  by NT file systems, regardless of whether the referenced
+ *                  file system supports extended attributes (e.g. a Windows
+ *                  2000 machine supports extended attributes if NTFS is used,
+ *                  but not if FAT is used, and Windows 98 doesn't support
+ *                  extended attributes at all.  Whether this is a feature or
+ *                  a bug is yet to be decided.
+ */
+int smbc_flistxattr(int fd,
+                    char *list,
+                    size_t size);
+
+/**@ingroup print
+ * Print a file given the name in fname. It would be a URL ...
+ *
+ * @param fname     The URL of a file on a remote SMB server that the
+ *                  caller wants printed
+ *
+ * @param printq    The URL of the print share to print the file to.
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *
+ *                  - EINVAL fname or printq was NULL or smbc_init not
+ * 		      not called.
+ *                  and errors returned by smbc_open
+ *
+ */
+int smbc_print_file(const char *fname, const char *printq);
+
+/**@ingroup print
+ * Open a print file that can be written to by other calls. This simply
+ * does an smbc_open call after checking if there is a file name on the
+ * URI. If not, a temporary name is added ...
+ *
+ * @param fname     The URL of the print share to print to?
+ *
+ * @returns         A file handle for the print file if successful.
+ *                  Returns -1 if an error occurred and errno has the values
+ *                  - EINVAL fname was NULL or smbc_init not called.
+ *                  - all errors returned by smbc_open
+ *
+ */
+int smbc_open_print_job(const char *fname);
+
+/**@ingroup print
+ * List the print jobs on a print share, for the moment, pass a callback
+ *
+ * @param purl      The url of the print share to list the jobs of
+ *
+ * @param fn        Callback function the receives printjob info
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL fname was NULL or smbc_init not called
+ *                  - EACCES ???
+ */
+int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
+
+/**@ingroup print
+ * Delete a print job
+ *
+ * @param purl      Url of the print share
+ *
+ * @param id        The id of the job to delete
+ *
+ * @return          0 on success, < 0 on error with errno set:
+ *                  - EINVAL fname was NULL or smbc_init not called
+ *
+ * @todo    what errno values are possible here?
+ */
+int smbc_unlink_print_job(const char *purl, int id);
+
+/**@ingroup callback
+ * Remove a server from the cached server list it's unused.
+ *
+ * @param context    pointer to smb context
+ *
+ * @param srv        pointer to server to remove
+ *
+ * @return On success, 0 is returned. 1 is returned if the server could not
+ *         be removed. Also usable outside libsmbclient.
+ */
+int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**@ingroup directory
+ * Convert strings of %xx to their single character equivalent.
+ *
+ * @param dest      A pointer to a buffer in which the resulting decoded
+ *                  string should be placed.  This may be a pointer to the
+ *                  same buffer as src_segment.
+ *
+ * @param src       A pointer to the buffer containing the URL to be decoded.
+ *                  Any %xx sequences herein are converted to their single
+ *                  character equivalent.  Each 'x' must be a valid hexadecimal
+ *                  digit, or that % sequence is left undecoded.
+ *
+ * @param max_dest_len
+ *                  The size of the buffer pointed to by dest_segment.
+ *
+ * @return          The number of % sequences which could not be converted
+ *                  due to lack of two following hexadecimal digits.
+ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+int
+smbc_urldecode(char *dest, char * src, size_t max_dest_len);
+#ifdef __cplusplus
+}
+#endif
+
+
+/*
+ * Convert any characters not specifically allowed in a URL into their %xx
+ * equivalent.
+ *
+ * @param dest      A pointer to a buffer in which the resulting encoded
+ *                  string should be placed.  Unlike smbc_urldecode(), this
+ *                  must be a buffer unique from src.
+ *
+ * @param src       A pointer to the buffer containing the string to be encoded.
+ *                  Any character not specifically allowed in a URL is converted
+ *                  into its hexadecimal value and encoded as %xx.
+ *
+ * @param max_dest_len
+ *                  The size of the buffer pointed to by dest_segment.
+ *
+ * @returns         The remaining buffer length.
+ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+int
+smbc_urlencode(char * dest, char * src, int max_dest_len);
+#ifdef __cplusplus
+}
+#endif
+
+
+/**@ingroup directory
+ * Return the version of the linked Samba code, and thus the version of the
+ * libsmbclient code.
+ *
+ * @return          The version string.
+ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+const char *
+smbc_version(void);
+#ifdef __cplusplus
+}
+#endif
+
+/**@ingroup misc
+ * @deprecated This interface has been deprecated use
+ * smbc_set_credentials_with_fallback() instead.
+ *
+ * @see smbc_set_credentials_with_fallback()
+ */
+DEPRECATED_SMBC_INTERFACE
+void
+smbc_set_credentials(const char *workgroup,
+                     const char *user,
+                     const char *password,
+                     smbc_bool use_kerberos,
+                     const char *signing_state);
+
+/**@ingroup misc
+ *
+ * Set the users credentials globally so they can be used for DFS
+ * referrals. Probably best to use this function in the smbc_get_auth_data_fn
+ * callback.
+ *
+ * @param ctx            The smb context.
+ *
+ * @param workgroup      Workgroup of the user.
+ *
+ * @param user           Username of user.
+ *
+ * @param password       Password of user.
+ */
+void
+smbc_set_credentials_with_fallback(SMBCCTX *ctx,
+		                   const char *workgroup,
+			     	   const char *user,
+			    	   const char *password);
+
+
+/**
+ * @ingroup threads
+ *
+ * Initialize for threads using the Posix Threads (pthread)
+ * implementation. This is a built-in implementation, avoiding the need to
+ * implement the component functions of the thread interface. If this function
+ * is used, it is not necessary to call smbc_thread_impl().
+ *
+ * @return {void}
+ */
+void
+smbc_thread_posix(void);
+
+/**
+ * @ingroup threads
+ *
+ * Initialize for an arbitrary thread implementation. The caller should
+ * provide, as parameters, pointers to functions to implement the requisite
+ * low-level thread functionality. A function must be provided for each
+ * parameter; none may be null.
+ *
+ * If the thread implementation is POSIX Threads (pthreads), then the much
+ * simpler smbc_thread_pthread() function may be used instead of this one.
+ *
+ * @param create_mutex
+ *   Create a mutex. This function should expect three parameters: lockname,
+ *   pplock, and location. It should create a unique mutex for each unique
+ *   lockname it is provided, and return the mutex identifier in *pplock. The
+ *   location parameter can be used for debugging, as it contains the
+ *   compiler-provided __location__ of the call.
+ *
+ * @param destroy_mutex
+ *   Destroy a mutex. This function should expect two parameters: plock and
+ *   location. It should destroy the mutex associated with the identifier
+ *   plock. The location parameter can be used for debugging, as it contains
+ *   the compiler-provided __location__ of the call.
+ *
+ * @param lock_mutex
+ *   Lock a mutex. This function should expect three parameters: plock,
+ *   lock_type, and location. The mutex associated with identifier plock
+ *   should be locked if lock_type is 1, and unlocked if lock_type is 2. The
+ *   location parameter can be used for debugging, as it contains the
+ *   compiler-provided __location__ of the call.
+ *
+ * @param create_tls
+ *   Create thread local storage. This function should expect three
+ *   parameters: keyname, ppkey, and location. It should allocate an
+ *   implementation-specific amount of memory and assign the pointer to that
+ *   allocated memory to *ppkey. The location parameter can be used for
+ *   debugging, as it contains the compiler-provided __location__ of the
+ *   call. This function should return 0 upon success, non-zero upon failure.
+ *
+ * @param destroy_tls
+ *   Destroy thread local storage. This function should expect two parameters:
+ *   ppkey and location. The ppkey parameter points to a variable containing a
+ *   thread local storage key previously provided by the create_tls
+ *   function. The location parameter can be used for debugging, as it
+ *   contains the compiler-provided __location__ of the call.
+ *
+ * @param set_tls
+ *   Set a thread local storage variable's value. This function should expect
+ *   three parameters: pkey, pval, and location. The pkey parameter is a
+ *   thread local storage key previously provided by the create_tls
+ *   function. The (void *) pval parameter contains the value to be placed in
+ *   the thread local storage variable identified by pkey. The location
+ *   parameter can be used for debugging, as it contains the compiler-provided
+ *   __location__ of the call. This function should return 0 upon success;
+ *   non-zero otherwise.
+ *
+ * @param get_tls
+ *   Retrieve a thread local storage variable's value. This function should
+ *   expect two parameters: pkey and location. The pkey parameter is a thread
+ *   local storage key previously provided by the create_tls function, and
+ *   which has previously been used in a call to the set_tls function to
+ *   initialize a thread local storage variable. The location parameter can be
+ *   used for debugging, as it contains the compiler-provided __location__ of
+ *   the call. This function should return the (void *) value stored in the
+ *   variable identified by pkey.
+ *
+ * @return {void}
+ */
+void
+smbc_thread_impl(
+        /* Mutex functions. */
+        int (*create_mutex)(const char *lockname,
+                            void **pplock,
+                            const char *location),
+        void (*destroy_mutex)(void *plock,
+                              const char *location),
+        int (*lock_mutex)(void *plock,
+                          int lock_type,
+                          const char *location),
+
+        /* Thread local storage. */
+        int (*create_tls)(const char *keyname,
+                          void **ppkey,
+                          const char *location),
+        void (*destroy_tls)(void **ppkey,
+                            const char *location),
+        int (*set_tls)(void *pkey,
+                       const void *pval,
+                       const char *location),
+        void *(*get_tls)(void *pkey,
+                         const char *location)
+        );
+
+
+
+/**
+ * @ingroup structure
+ * Structure that contains a client context information
+ * This structure is known as SMBCCTX
+ *
+ * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE!  The data in the context
+ * structure should all be considered private to the library.  It remains here
+ * only for backward compatibility.
+ *
+ * See the comments herein for use of the setter and getter functions which
+ * should now be used for manipulating these values.  New features, functions,
+ * etc., are not added here but rather in _internal where they are not
+ * directly visible to applications.  This makes it much easier to maintain
+ * ABI compatibility.
+ */
+struct _SMBCCTX
+{
+        /**
+         * debug level
+         *
+         * DEPRECATED:
+         * Use smbc_getDebug() and smbc_setDebug()
+         */
+        int     debug DEPRECATED_SMBC_INTERFACE;
+
+        /**
+         * netbios name used for making connections
+         *
+         * DEPRECATED:
+         * Use smbc_getNetbiosName() and smbc_setNetbiosName()
+         */
+        char * netbios_name DEPRECATED_SMBC_INTERFACE;
+
+        /**
+         * workgroup name used for making connections
+         *
+         * DEPRECATED:
+         * Use smbc_getWorkgroup() and smbc_setWorkgroup()
+         */
+        char * workgroup DEPRECATED_SMBC_INTERFACE;
+
+        /**
+         * username used for making connections
+         *
+         * DEPRECATED:
+         * Use smbc_getUser() and smbc_setUser()
+         */
+        char * user DEPRECATED_SMBC_INTERFACE;
+
+        /**
+         * timeout used for waiting on connections / response data (in
+         * milliseconds)
+         *
+         * DEPRECATED:
+         * Use smbc_getTimeout() and smbc_setTimeout()
+         */
+        int timeout DEPRECATED_SMBC_INTERFACE;
+
+	/**
+         * callable functions for files:
+	 * For usage and return values see the SMBC_* functions
+         *
+         * DEPRECATED:
+         *
+         * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
+         * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
+	 */
+        smbc_open_fn                    open DEPRECATED_SMBC_INTERFACE;
+        smbc_creat_fn                   creat DEPRECATED_SMBC_INTERFACE;
+        smbc_read_fn                    read DEPRECATED_SMBC_INTERFACE;
+        smbc_write_fn                   write DEPRECATED_SMBC_INTERFACE;
+        smbc_unlink_fn                  unlink DEPRECATED_SMBC_INTERFACE;
+        smbc_rename_fn                  rename DEPRECATED_SMBC_INTERFACE;
+        smbc_lseek_fn                   lseek DEPRECATED_SMBC_INTERFACE;
+        smbc_stat_fn                    stat DEPRECATED_SMBC_INTERFACE;
+        smbc_fstat_fn                   fstat DEPRECATED_SMBC_INTERFACE;
+#if 0 /* internal */
+        smbc_ftruncate_fn               ftruncate_fn;
+#endif
+        smbc_close_fn                   close_fn DEPRECATED_SMBC_INTERFACE;
+        smbc_opendir_fn                 opendir DEPRECATED_SMBC_INTERFACE;
+        smbc_closedir_fn                closedir DEPRECATED_SMBC_INTERFACE;
+        smbc_readdir_fn                 readdir DEPRECATED_SMBC_INTERFACE;
+        smbc_readdirplus_fn             readdirplus DEPRECATED_SMBC_INTERFACE;
+	smbc_readdirplus2_fn            readdirplus2 DEPRECATED_SMBC_INTERFACE;
+        smbc_getdents_fn                getdents DEPRECATED_SMBC_INTERFACE;
+        smbc_mkdir_fn                   mkdir DEPRECATED_SMBC_INTERFACE;
+        smbc_rmdir_fn                   rmdir DEPRECATED_SMBC_INTERFACE;
+        smbc_telldir_fn                 telldir DEPRECATED_SMBC_INTERFACE;
+        smbc_lseekdir_fn                lseekdir DEPRECATED_SMBC_INTERFACE;
+        smbc_fstatdir_fn                fstatdir DEPRECATED_SMBC_INTERFACE;
+        smbc_chmod_fn                   chmod DEPRECATED_SMBC_INTERFACE;
+        smbc_utimes_fn                  utimes DEPRECATED_SMBC_INTERFACE;
+        smbc_setxattr_fn                setxattr DEPRECATED_SMBC_INTERFACE;
+        smbc_getxattr_fn                getxattr DEPRECATED_SMBC_INTERFACE;
+        smbc_removexattr_fn             removexattr DEPRECATED_SMBC_INTERFACE;
+        smbc_listxattr_fn               listxattr DEPRECATED_SMBC_INTERFACE;
+
+        /* Printing-related functions */
+        smbc_print_file_fn              print_file DEPRECATED_SMBC_INTERFACE;
+        smbc_open_print_job_fn          open_print_job DEPRECATED_SMBC_INTERFACE;
+        smbc_list_print_jobs_fn         list_print_jobs DEPRECATED_SMBC_INTERFACE;
+        smbc_unlink_print_job_fn        unlink_print_job DEPRECATED_SMBC_INTERFACE;
+
+        /*
+        ** Callbacks
+        *
+        * DEPRECATED:
+        *
+        * See the comment above each field, for the getter and setter
+        * functions that should now be used.
+        */
+	struct _smbc_callbacks
+        {
+		/**
+                 * authentication function callback: called upon auth requests
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
+		 */
+                smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
+
+		/**
+                 * check if a server is still good
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionCheckServer(),
+                 * smbc_setFunctionCheckServer()
+		 */
+		smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
+
+		/**
+                 * remove a server if unused
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionRemoveUnusedServer(),
+                 * smbc_setFunctionCheckServer()
+		 */
+		smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
+
+		/** Cache subsystem
+                 *
+		 * For an example cache system see
+		 * samba/source/libsmb/libsmb_cache.c
+                 *
+                 * Cache subsystem * functions follow.
+		 */
+
+		/**
+                 * server cache addition
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionAddCachedServer(),
+                 * smbc_setFunctionAddCachedServer()
+		 */
+		smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
+
+		/**
+                 * server cache lookup
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionGetCachedServer(),
+                 * smbc_setFunctionGetCachedServer()
+		 */
+		smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
+
+		/**
+                 * server cache removal
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionRemoveCachedServer(),
+                 * smbc_setFunctionRemoveCachedServer()
+		 */
+		smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
+
+		/**
+                 * server cache purging, try to remove all cached servers
+                 * (disconnect)
+                 *
+                 * DEPRECATED:
+                 * Use smbc_getFunctionPurgeCachedServers(),
+                 * smbc_setFunctionPurgeCachedServers()
+		 */
+		smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
+	} callbacks;
+
+        /**
+         * Space where the private data of the server cache used to be
+         *
+         * DEPRECATED:
+         * Use smbc_getServerCacheData(), smbc_setServerCacheData()
+         */
+        void * reserved DEPRECATED_SMBC_INTERFACE;
+
+        /*
+         * Very old configuration options.
+         *
+         * DEPRECATED:
+         * Use one of the following functions instead:
+         *   smbc_setOptionUseKerberos()
+         *   smbc_getOptionUseKerberos()
+         *   smbc_setOptionFallbackAfterKerberos()
+         *   smbc_getOptionFallbackAfterKerberos()
+         *   smbc_setOptionNoAutoAnonymousLogin()
+         *   smbc_getOptionNoAutoAnonymousLogin()
+         */
+        int flags DEPRECATED_SMBC_INTERFACE;
+
+        /**
+         * user options selections that apply to this session
+         *
+         * NEW OPTIONS ARE NOT ADDED HERE!
+         *
+         * DEPRECATED:
+         * To set and retrieve options, use the smbc_setOption*() and
+         * smbc_getOption*() functions.
+         */
+        struct _smbc_options {
+                int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
+                int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
+                int one_share_per_server DEPRECATED_SMBC_INTERFACE;
+        } options DEPRECATED_SMBC_INTERFACE;
+
+	/** INTERNAL DATA
+	 * do _NOT_ touch this from your program !
+	 */
+	struct SMBC_internal_data * internal;
+};
+
+
+#endif /* SMBCLIENT_H_INCLUDED */