1 /*=====================================================================
2 Unix SMB/Netbios implementation.
3 SMB client library API definitions
4 Copyright (C) Andrew Tridgell 1998
5 Copyright (C) Richard Sharpe 2000
6 Copyright (C) John Terpsra 2000
7 Copyright (C) Tom Jansen (Ninja ISD) 2002
8 Copyright (C) Derrell Lipman 2003-2008
11 This program is free software; you can redistribute it and/or modify
12 it under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 3 of the License, or
14 (at your option) any later version.
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <http://www.gnu.org/licenses/>.
23 =====================================================================*/
25 #ifndef SMBCLIENT_H_INCLUDED
26 #define SMBCLIENT_H_INCLUDED
28 #undef DEPRECATED_SMBC_INTERFACE
29 #if ! defined(__LIBSMBCLIENT_INTERNAL__) && defined(__GNUC__)
30 # define DEPRECATED_SMBC_INTERFACE __attribute__ ((deprecated))
32 # define DEPRECATED_SMBC_INTERFACE
39 /*-------------------------------------------------------------------*/
40 /* The following are special comments to instruct DOXYGEN (automated
43 /** \defgroup libsmbclient
45 /** \defgroup structure Data Structures Type and Constants
46 * \ingroup libsmbclient
47 * Data structures, types, and constants
49 /** \defgroup callback Callback function types
50 * \ingroup libsmbclient
53 /** \defgroup file File Functions
54 * \ingroup libsmbclient
55 * Functions used to access individual file contents
57 /** \defgroup directory Directory Functions
58 * \ingroup libsmbclient
59 * Functions used to access directory entries
61 /** \defgroup attribute Attributes Functions
62 * \ingroup libsmbclient
63 * Functions used to view or change file and directory attributes
65 /** \defgroup print Print Functions
66 * \ingroup libsmbclient
67 * Functions used to access printing functionality
69 /** \defgroup misc Miscellaneous Functions
70 * \ingroup libsmbclient
71 * Functions that don't fit in to other categories
73 /*-------------------------------------------------------------------*/
75 /* Make sure we have the following includes for now ... */
76 #include <sys/types.h>
81 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
83 #define SMBC_WORKGROUP 1
85 #define SMBC_FILE_SHARE 3
86 #define SMBC_PRINTER_SHARE 4
87 #define SMBC_COMMS_SHARE 5
88 #define SMBC_IPC_SHARE 6
94 * Structure that represents a directory entry.
103 SMBC_PRINTER_SHARE=4,
109 unsigned int smbc_type;
111 /** Length of this smbc_dirent in bytes
114 /** The length of the comment string in bytes (does not include
117 unsigned int commentlen;
118 /** Points to the null terminated comment string
121 /** The length of the name string in bytes (does not include
124 unsigned int namelen;
125 /** Points to the null terminated name string
131 * Flags for smbc_setxattr()
132 * Specify a bitwise OR of these, or 0 to add or replace as necessary
134 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
135 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
139 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
140 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
141 * "system.*") is specified.
143 #define SMBC_DOS_MODE_READONLY 0x01
144 #define SMBC_DOS_MODE_HIDDEN 0x02
145 #define SMBC_DOS_MODE_SYSTEM 0x04
146 #define SMBC_DOS_MODE_VOLUME_ID 0x08
147 #define SMBC_DOS_MODE_DIRECTORY 0x10
148 #define SMBC_DOS_MODE_ARCHIVE 0x20
151 * Valid values for the option "open_share_mode", when calling
152 * smbc_setOptionOpenShareMode()
154 typedef enum smbc_share_mode
156 SMBC_SHAREMODE_DENY_DOS = 0,
157 SMBC_SHAREMODE_DENY_ALL = 1,
158 SMBC_SHAREMODE_DENY_WRITE = 2,
159 SMBC_SHAREMODE_DENY_READ = 3,
160 SMBC_SHAREMODE_DENY_NONE = 4,
161 SMBC_SHAREMODE_DENY_FCB = 7
166 * Values for option SMB Encryption Level, as set and retrieved with
167 * smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
169 typedef enum smbc_smb_encrypt_level
171 SMBC_ENCRYPTLEVEL_NONE = 0,
172 SMBC_ENCRYPTLEVEL_REQUEST = 1,
173 SMBC_ENCRYPTLEVEL_REQUIRE = 2
174 } smbc_smb_encrypt_level;
177 typedef int smbc_bool;
181 # define ENOATTR ENOENT /* No such attribute */
187 /**@ingroup structure
188 * Structure that represents a print job.
192 struct print_job_info
194 /** numeric ID of the print job
198 /** represents print job priority (lower numbers mean higher priority)
200 unsigned short priority;
202 /** Size of the print job
206 /** Name of the user that owns the print job
210 /** Name of the print job. This will have no name if an anonymous print
211 * file was opened. Ie smb://server/printer
215 /** Time the print job was spooled
219 #endif /* _CLIENT_H */
222 /**@ingroup structure
225 typedef struct _SMBCSRV SMBCSRV;
227 /**@ingroup structure
228 * File or directory handle
230 typedef struct _SMBCFILE SMBCFILE;
232 /**@ingroup structure
233 * File or directory handle
235 typedef struct _SMBCCTX SMBCCTX;
239 * Flags for SMBCCTX->flags
241 * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
243 * smbc_setOptionUseKerberos()
244 * smbc_getOptionUseKerberos()
245 * smbc_setOptionFallbackAfterKerberos()
246 * smbc_getOptionFallbackAFterKerberos()
247 * smbc_setOptionNoAutoAnonymousLogin()
248 * smbc_getOptionNoAutoAnonymousLogin()
250 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
251 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
252 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
257 * Authentication callback function type (traditional method)
259 * Type for the the authentication function called by the library to
260 * obtain authentication credentals
262 * For kerberos support the function should just be called without
263 * prompting the user for credentials. Which means a simple 'return'
264 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
265 * and examples/libsmbclient/testbrowse.c.
267 * @param srv Server being authenticated to
269 * @param shr Share being authenticated to
271 * @param wg Pointer to buffer containing a "hint" for the
272 * workgroup to be authenticated. Should be filled in
273 * with the correct workgroup if the hint is wrong.
275 * @param wglen The size of the workgroup buffer in bytes
277 * @param un Pointer to buffer containing a "hint" for the
278 * user name to be use for authentication. Should be
279 * filled in with the correct workgroup if the hint is
282 * @param unlen The size of the username buffer in bytes
284 * @param pw Pointer to buffer containing to which password
287 * @param pwlen The size of the password buffer in bytes
290 typedef void (*smbc_get_auth_data_fn)(const char *srv,
294 char *pw, int pwlen);
296 * Authentication callback function type (method that includes context)
298 * Type for the the authentication function called by the library to
299 * obtain authentication credentals
301 * For kerberos support the function should just be called without
302 * prompting the user for credentials. Which means a simple 'return'
303 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
304 * and examples/libsmbclient/testbrowse.c.
306 * @param c Pointer to the smb context
308 * @param srv Server being authenticated to
310 * @param shr Share being authenticated to
312 * @param wg Pointer to buffer containing a "hint" for the
313 * workgroup to be authenticated. Should be filled in
314 * with the correct workgroup if the hint is wrong.
316 * @param wglen The size of the workgroup buffer in bytes
318 * @param un Pointer to buffer containing a "hint" for the
319 * user name to be use for authentication. Should be
320 * filled in with the correct workgroup if the hint is
323 * @param unlen The size of the username buffer in bytes
325 * @param pw Pointer to buffer containing to which password
328 * @param pwlen The size of the password buffer in bytes
331 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
336 char *pw, int pwlen);
340 * Print job info callback function type.
342 * @param i pointer to print job information structure
345 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
349 * Check if a server is still good
351 * @param c pointer to smb context
353 * @param srv pointer to server to check
355 * @return 0 when connection is good. 1 on error.
358 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
361 * Remove a server if unused
363 * @param c pointer to smb context
365 * @param srv pointer to server to remove
367 * @return 0 on success. 1 on failure.
370 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
374 * Add a server to the cache system
376 * @param c pointer to smb context
378 * @param srv pointer to server to add
380 * @param server server name
382 * @param share share name
384 * @param workgroup workgroup used to connect
386 * @param username username used to connect
388 * @return 0 on success. 1 on failure.
391 typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
392 const char * server, const char * share,
393 const char * workgroup, const char * username);
396 * Look up a server in the cache system
398 * @param c pointer to smb context
400 * @param server server name to match
402 * @param share share name to match
404 * @param workgroup workgroup to match
406 * @param username username to match
408 * @return pointer to SMBCSRV on success. NULL on failure.
411 typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
412 const char * share, const char * workgroup,
413 const char * username);
416 * Check if a server is still good
418 * @param c pointer to smb context
420 * @param srv pointer to server to remove
422 * @return 0 when found and removed. 1 on failure.
425 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
429 * Try to remove all servers from the cache system and disconnect
431 * @param c pointer to smb context
433 * @return 0 when found and removed. 1 on failure.
436 typedef int (*smbc_purge_cached_fn) (SMBCCTX * c);
440 /*****************************************
441 * Getters and setters for CONFIGURATION *
442 *****************************************/
444 /** Get the debug level */
446 smbc_getDebug(SMBCCTX *c);
448 /** Set the debug level */
450 smbc_setDebug(SMBCCTX *c, int debug);
452 /** Get the netbios name used for making connections */
454 smbc_getNetbiosName(SMBCCTX *c);
456 /** Set the netbios name used for making connections */
458 smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
460 /** Get the workgroup used for making connections */
462 smbc_getWorkgroup(SMBCCTX *c);
464 /** Set the workgroup used for making connections */
465 void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
467 /** Get the username used for making connections */
469 smbc_getUser(SMBCCTX *c);
471 /** Set the username used for making connections */
473 smbc_setUser(SMBCCTX *c, char * user);
476 * Get the timeout used for waiting on connections and response data
480 smbc_getTimeout(SMBCCTX *c);
483 * Set the timeout used for waiting on connections and response data
487 smbc_setTimeout(SMBCCTX *c, int timeout);
491 /***********************************
492 * Getters and setters for OPTIONS *
493 ***********************************/
495 /** Get whether to log to standard error instead of standard output */
497 smbc_getOptionDebugToStderr(SMBCCTX *c);
499 /** Set whether to log to standard error instead of standard output */
501 smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
504 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
505 * than the old-style names such as M_TIME. This allows also setting/getting
506 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
507 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
511 smbc_getOptionFullTimeNames(SMBCCTX *c);
514 * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
515 * than the old-style names such as M_TIME. This allows also setting/getting
516 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
517 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
521 smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
524 * Get the share mode to use for files opened with SMBC_open_ctx(). The
525 * default is SMBC_SHAREMODE_DENY_NONE.
528 smbc_getOptionOpenShareMode(SMBCCTX *c);
531 * Set the share mode to use for files opened with SMBC_open_ctx(). The
532 * default is SMBC_SHAREMODE_DENY_NONE.
535 smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
537 /** Retrieve a previously saved user data handle */
539 smbc_getOptionUserData(SMBCCTX *c);
541 /** Save a user data handle */
543 smbc_setOptionUserData(SMBCCTX *c, void *user_data);
545 /** Get the encoded value for encryption level. */
546 smbc_smb_encrypt_level
547 smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
549 /** Set the encoded value for encryption level. */
551 smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
553 /** Get whether to treat file names as case-sensitive. */
555 smbc_getOptionCaseSensitive(SMBCCTX *c);
557 /** Set whether to treat file names as case-sensitive. */
559 smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
563 * Get from how many local master browsers should the list of workgroups be
564 * retrieved. It can take up to 12 minutes or longer after a server becomes a
565 * local master browser, for it to have the entire browse list (the list of
566 * workgroups/domains) from an entire network. Since a client never knows
567 * which local master browser will be found first, the one which is found
568 * first and used to retrieve a browse list may have an incomplete or empty
569 * browse list. By requesting the browse list from multiple local master
570 * browsers, a more complete list can be generated. For small networks (few
571 * workgroups), it is recommended that this value be set to 0, causing the
572 * browse lists from all found local master browsers to be retrieved and
573 * merged. For networks with many workgroups, a suitable value for this
574 * variable is probably somewhere around 3. (Default: 3).
577 smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
580 * Set from how many local master browsers should the list of workgroups be
581 * retrieved. It can take up to 12 minutes or longer after a server becomes a
582 * local master browser, for it to have the entire browse list (the list of
583 * workgroups/domains) from an entire network. Since a client never knows
584 * which local master browser will be found first, the one which is found
585 * first and used to retrieve a browse list may have an incomplete or empty
586 * browse list. By requesting the browse list from multiple local master
587 * browsers, a more complete list can be generated. For small networks (few
588 * workgroups), it is recommended that this value be set to 0, causing the
589 * browse lists from all found local master browsers to be retrieved and
590 * merged. For networks with many workgroups, a suitable value for this
591 * variable is probably somewhere around 3. (Default: 3).
594 smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
597 * Get whether to url-encode readdir entries.
599 * There is a difference in the desired return strings from
600 * smbc_readdir() depending upon whether the filenames are to
601 * be displayed to the user, or whether they are to be
602 * appended to the path name passed to smbc_opendir() to call
603 * a further smbc_ function (e.g. open the file with
604 * smbc_open()). In the former case, the filename should be
605 * in "human readable" form. In the latter case, the smbc_
606 * functions expect a URL which must be url-encoded. Those
607 * functions decode the URL. If, for example, smbc_readdir()
608 * returned a file name of "abc%20def.txt", passing a path
609 * with this file name attached to smbc_open() would cause
610 * smbc_open to attempt to open the file "abc def.txt" since
611 * the %20 is decoded into a space.
613 * Set this option to True if the names returned by
614 * smbc_readdir() should be url-encoded such that they can be
615 * passed back to another smbc_ call. Set it to False if the
616 * names returned by smbc_readdir() are to be presented to the
619 * For backwards compatibility, this option defaults to False.
622 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
625 * Set whether to url-encode readdir entries.
627 * There is a difference in the desired return strings from
628 * smbc_readdir() depending upon whether the filenames are to
629 * be displayed to the user, or whether they are to be
630 * appended to the path name passed to smbc_opendir() to call
631 * a further smbc_ function (e.g. open the file with
632 * smbc_open()). In the former case, the filename should be
633 * in "human readable" form. In the latter case, the smbc_
634 * functions expect a URL which must be url-encoded. Those
635 * functions decode the URL. If, for example, smbc_readdir()
636 * returned a file name of "abc%20def.txt", passing a path
637 * with this file name attached to smbc_open() would cause
638 * smbc_open to attempt to open the file "abc def.txt" since
639 * the %20 is decoded into a space.
641 * Set this option to True if the names returned by
642 * smbc_readdir() should be url-encoded such that they can be
643 * passed back to another smbc_ call. Set it to False if the
644 * names returned by smbc_readdir() are to be presented to the
647 * For backwards compatibility, this option defaults to False.
650 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
653 * Get whether to use the same connection for all shares on a server.
655 * Some Windows versions appear to have a limit to the number
656 * of concurrent SESSIONs and/or TREE CONNECTions. In
657 * one-shot programs (i.e. the program runs and then quickly
658 * ends, thereby shutting down all connections), it is
659 * probably reasonable to establish a new connection for each
660 * share. In long-running applications, the limitation can be
661 * avoided by using only a single connection to each server,
662 * and issuing a new TREE CONNECT when the share is accessed.
665 smbc_getOptionOneSharePerServer(SMBCCTX *c);
668 * Set whether to use the same connection for all shares on a server.
670 * Some Windows versions appear to have a limit to the number
671 * of concurrent SESSIONs and/or TREE CONNECTions. In
672 * one-shot programs (i.e. the program runs and then quickly
673 * ends, thereby shutting down all connections), it is
674 * probably reasonable to establish a new connection for each
675 * share. In long-running applications, the limitation can be
676 * avoided by using only a single connection to each server,
677 * and issuing a new TREE CONNECT when the share is accessed.
680 smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
682 /** Get whether to enable use of kerberos */
684 smbc_getOptionUseKerberos(SMBCCTX *c);
686 /** Set whether to enable use of kerberos */
688 smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
690 /** Get whether to fallback after kerberos */
692 smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
694 /** Set whether to fallback after kerberos */
696 smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
698 /** Get whether to automatically select anonymous login */
700 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
702 /** Set whether to automatically select anonymous login */
704 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
708 /*************************************
709 * Getters and setters for FUNCTIONS *
710 *************************************/
712 /** Get the function for obtaining authentication data */
713 smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
715 /** Set the function for obtaining authentication data */
716 void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
718 /** Get the new-style authentication function which includes the context. */
719 smbc_get_auth_data_with_context_fn
720 smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
722 /** Set the new-style authentication function which includes the context. */
724 smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
725 smbc_get_auth_data_with_context_fn fn);
727 /** Get the function for checking if a server is still good */
728 smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
730 /** Set the function for checking if a server is still good */
731 void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
733 /** Get the function for removing a server if unused */
734 smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
736 /** Set the function for removing a server if unused */
737 void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
738 smbc_remove_unused_server_fn fn);
740 /** Get the function for adding a cached server */
741 smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
743 /** Set the function for adding a cached server */
744 void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
746 /** Get the function for server cache lookup */
747 smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
749 /** Set the function for server cache lookup */
750 void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
752 /** Get the function for server cache removal */
753 smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
755 /** Set the function for server cache removal */
756 void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
757 smbc_remove_cached_srv_fn fn);
760 * Get the function for server cache purging. This function tries to
761 * remove all cached servers (e.g. on disconnect)
763 smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
766 * Set the function for server cache purging. This function tries to
767 * remove all cached servers (e.g. on disconnect)
769 void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
770 smbc_purge_cached_fn fn);
772 /** Get the function to store private data of the server cache */
773 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
775 /** Set the function to store private data of the server cache */
776 void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
780 /*****************************************************************
781 * Callable functions for files. *
782 * Each callable has a function signature typedef, a declaration *
783 * for the getter, and a declaration for the setter. *
784 *****************************************************************/
786 typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
790 smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
791 void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
793 typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
796 smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
797 void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
799 typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
803 smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
804 void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
806 typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
810 smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
811 void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
813 typedef int (*smbc_unlink_fn)(SMBCCTX *c,
815 smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
816 void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
818 typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
822 smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
823 void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
825 typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
829 smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
830 void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
832 typedef int (*smbc_stat_fn)(SMBCCTX *c,
835 smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
836 void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
838 typedef int (*smbc_fstat_fn)(SMBCCTX *c,
841 smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
842 void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
844 typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
847 smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
848 void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
850 typedef int (*smbc_close_fn)(SMBCCTX *c,
852 smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
853 void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
857 /*****************************************************************
858 * Callable functions for directories. *
859 * Each callable has a function signature typedef, a declaration *
860 * for the getter, and a declaration for the setter. *
861 *****************************************************************/
863 typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
865 smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
866 void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
868 typedef int (*smbc_closedir_fn)(SMBCCTX *c,
870 smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
871 void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
873 typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
875 smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
876 void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
878 typedef int (*smbc_getdents_fn)(SMBCCTX *c,
880 struct smbc_dirent *dirp,
882 smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
883 void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
885 typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
888 smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
889 void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
891 typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
893 smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
894 void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
896 typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
898 smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
899 void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
901 typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
904 smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
905 void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
907 typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
910 smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
911 void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
915 /*****************************************************************
916 * Callable functions applicable to both files and directories. *
917 * Each callable has a function signature typedef, a declaration *
918 * for the getter, and a declaration for the setter. *
919 *****************************************************************/
921 typedef int (*smbc_chmod_fn)(SMBCCTX *c,
924 smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
925 void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
927 typedef int (*smbc_utimes_fn)(SMBCCTX *c,
929 struct timeval *tbuf);
930 smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
931 void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
933 typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
939 smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
940 void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
942 typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
947 smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
948 void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
950 typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
953 smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
954 void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
956 typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
960 smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
961 void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
965 /*****************************************************************
966 * Callable functions for printing. *
967 * Each callable has a function signature typedef, a declaration *
968 * for the getter, and a declaration for the setter. *
969 *****************************************************************/
971 typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
975 smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
976 void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
978 typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
980 smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
981 void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
982 smbc_open_print_job_fn fn);
984 typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
986 smbc_list_print_job_fn fn);
987 smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
988 void smbc_setFunctionListPrintJobs(SMBCCTX *c,
989 smbc_list_print_jobs_fn fn);
991 typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
994 smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
995 void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
996 smbc_unlink_print_job_fn fn);
1000 * Create a new SBMCCTX (a context).
1002 * Must be called before the context is passed to smbc_context_init()
1004 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
1005 * - ENOMEM Out of memory
1007 * @see smbc_free_context(), smbc_init_context()
1009 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1011 SMBCCTX * smbc_new_context(void);
1014 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1016 * The context will be deleted if possible.
1018 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1020 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1023 * @return Returns 0 on succes. Returns 1 on failure with errno set:
1024 * - EBUSY Server connections are still used, Files are open or cache
1025 * could not be purged
1026 * - EBADF context == NULL
1028 * @see smbc_new_context()
1030 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1031 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1032 * use in periodical cleanup functions for example.
1034 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1039 * @deprecated. Use smbc_setOption*() functions instead.
1042 smbc_option_set(SMBCCTX *context,
1044 ... /* option_value */);
1047 * @deprecated. Use smbc_getOption*() functions instead.
1050 smbc_option_get(SMBCCTX *context,
1054 * Initialize a SBMCCTX (a context).
1056 * Must be called before using any SMBCCTX API function
1058 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1060 * @return A pointer to the given SMBCCTX on success,
1061 * NULL on error with errno set:
1062 * - EBADF NULL context given
1063 * - ENOMEM Out of memory
1064 * - ENOENT The smb.conf file would not load
1066 * @see smbc_new_context()
1068 * @note my_context = smbc_init_context(smbc_new_context())
1069 * is perfectly safe, but it might leak memory on
1070 * smbc_context_init() failure. Avoid this.
1071 * You'll have to call smbc_free_context() yourself
1075 SMBCCTX * smbc_init_context(SMBCCTX * context);
1078 * Initialize the samba client library.
1080 * Must be called before using any of the smbclient API function
1082 * @param fn The function that will be called to obtaion
1083 * authentication credentials.
1085 * @param debug Allows caller to set the debug level. Can be
1086 * changed in smb.conf file. Allows caller to set
1087 * debugging if no smb.conf.
1089 * @return 0 on success, < 0 on error with errno set:
1090 * - ENOMEM Out of memory
1091 * - ENOENT The smb.conf file would not load
1095 int smbc_init(smbc_get_auth_data_fn fn, int debug);
1098 * Set or retrieve the compatibility library's context pointer
1100 * @param context New context to use, or NULL. If a new context is provided,
1101 * it must have allocated with smbc_new_context() and
1102 * initialized with smbc_init_context(), followed, optionally,
1103 * by some manual changes to some of the non-internal fields.
1105 * @return The old context.
1107 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1109 * @note This function may be called prior to smbc_init() to force
1110 * use of the next context without any internal calls to
1111 * smbc_new_context() or smbc_init_context(). It may also
1112 * be called after smbc_init() has already called those two
1113 * functions, to replace the existing context with a new one.
1114 * Care should be taken, in this latter case, to ensure that
1115 * the server cache and any data allocated by the
1116 * authentication functions have been freed, if necessary.
1119 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1122 * Open a file on an SMB server.
1124 * @param furl The smb url of the file to be opened.
1126 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1127 * request opening the file read-only,write-only
1128 * or read/write. flags may also be bitwise-or'd with
1129 * one or more of the following:
1130 * O_CREAT - If the file does not exist it will be
1132 * O_EXCL - When used with O_CREAT, if the file
1133 * already exists it is an error and the open will
1135 * O_TRUNC - If the file already exists it will be
1137 * O_APPEND The file is opened in append mode
1139 * @param mode mode specifies the permissions to use if a new
1140 * file is created. It is modified by the
1141 * process's umask in the usual way: the permissions
1142 * of the created file are (mode & ~umask)
1144 * Not currently use, but there for future use.
1145 * We will map this to SYSTEM, HIDDEN, etc bits
1146 * that reverses the mapping that smbc_fstat does.
1148 * @return Valid file handle, < 0 on error with errno set:
1149 * - ENOMEM Out of memory
1150 * - EINVAL if an invalid parameter passed, like no
1151 * file, or smbc_init not called.
1152 * - EEXIST pathname already exists and O_CREAT and
1154 * - EISDIR pathname refers to a directory and
1155 * the access requested involved writing.
1156 * - EACCES The requested access to the file is not
1158 * - ENODEV The requested share does not exist
1159 * - ENOTDIR A file on the path is not a directory
1160 * - ENOENT A directory component in pathname does
1165 * @note This call uses an underlying routine that may create
1166 * a new connection to the server specified in the URL.
1167 * If the credentials supplied in the URL, or via the
1168 * auth_fn in the smbc_init call, fail, this call will
1169 * try again with an empty username and password. This
1170 * often gets mapped to the guest account on some machines.
1173 int smbc_open(const char *furl, int flags, mode_t mode);
1176 * Create a file on an SMB server.
1178 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1180 * @param furl The smb url of the file to be created
1182 * @param mode mode specifies the permissions to use if a new
1183 * file is created. It is modified by the
1184 * process's umask in the usual way: the permissions
1185 * of the created file are (mode & ~umask)
1187 * NOTE, the above is not true. We are dealing with
1188 * an SMB server, which has no concept of a umask!
1190 * @return Valid file handle, < 0 on error with errno set:
1191 * - ENOMEM Out of memory
1192 * - EINVAL if an invalid parameter passed, like no
1193 * file, or smbc_init not called.
1194 * - EEXIST pathname already exists and O_CREAT and
1196 * - EISDIR pathname refers to a directory and
1197 * the access requested involved writing.
1198 * - EACCES The requested access to the file is not
1200 * - ENOENT A directory component in pathname does
1202 * - ENODEV The requested share does not exist.
1207 int smbc_creat(const char *furl, mode_t mode);
1210 * Read from a file using an opened file handle.
1212 * @param fd Open file handle from smbc_open() or smbc_creat()
1214 * @param buf Pointer to buffer to recieve read data
1216 * @param bufsize Size of buf in bytes
1218 * @return Number of bytes read, < 0 on error with errno set:
1219 * - EISDIR fd refers to a directory
1220 * - EBADF fd is not a valid file descriptor or
1221 * is not open for reading.
1222 * - EINVAL fd is attached to an object which is
1223 * unsuitable for reading, or no buffer passed or
1224 * smbc_init not called.
1226 * @see smbc_open(), smbc_write()
1229 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1233 * Write to a file using an opened file handle.
1235 * @param fd Open file handle from smbc_open() or smbc_creat()
1237 * @param buf Pointer to buffer to recieve read data
1239 * @param bufsize Size of buf in bytes
1241 * @return Number of bytes written, < 0 on error with errno set:
1242 * - EISDIR fd refers to a directory.
1243 * - EBADF fd is not a valid file descriptor or
1244 * is not open for reading.
1245 * - EINVAL fd is attached to an object which is
1246 * unsuitable for reading, or no buffer passed or
1247 * smbc_init not called.
1249 * @see smbc_open(), smbc_read()
1252 ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
1256 * Seek to a specific location in a file.
1258 * @param fd Open file handle from smbc_open() or smbc_creat()
1260 * @param offset Offset in bytes from whence
1262 * @param whence A location in the file:
1263 * - SEEK_SET The offset is set to offset bytes from
1264 * the beginning of the file
1265 * - SEEK_CUR The offset is set to current location
1266 * plus offset bytes.
1267 * - SEEK_END The offset is set to the size of the
1268 * file plus offset bytes.
1270 * @return Upon successful completion, lseek returns the
1271 * resulting offset location as measured in bytes
1272 * from the beginning of the file. Otherwise, a value
1273 * of (off_t)-1 is returned and errno is set to
1274 * indicate the error:
1275 * - EBADF Fildes is not an open file descriptor.
1276 * - EINVAL Whence is not a proper value or smbc_init
1279 * @todo Are all the whence values really supported?
1281 * @todo Are errno values complete and correct?
1283 off_t smbc_lseek(int fd, off_t offset, int whence);
1287 * Close an open file handle.
1289 * @param fd The file handle to close
1291 * @return 0 on success, < 0 on error with errno set:
1292 * - EBADF fd isn't a valid open file descriptor
1293 * - EINVAL smbc_init() failed or has not been called
1295 * @see smbc_open(), smbc_creat()
1297 int smbc_close(int fd);
1300 /**@ingroup directory
1301 * Unlink (delete) a file or directory.
1303 * @param furl The smb url of the file to delete
1305 * @return 0 on success, < 0 on error with errno set:
1306 * - EACCES or EPERM Write access to the directory
1307 * containing pathname is not allowed or one
1308 * of the directories in pathname did not allow
1309 * search (execute) permission
1310 * - ENOENT A directory component in pathname does
1312 * - EINVAL NULL was passed in the file param or
1313 * smbc_init not called.
1314 * - EACCES You do not have access to the file
1315 * - ENOMEM Insufficient kernel memory was available
1317 * @see smbc_rmdir()s
1319 * @todo Are errno values complete and correct?
1321 int smbc_unlink(const char *furl);
1324 /**@ingroup directory
1325 * Rename or move a file or directory.
1327 * @param ourl The original smb url (source url) of file or
1328 * directory to be moved
1330 * @param nurl The new smb url (destination url) of the file
1331 * or directory after the move. Currently nurl must
1332 * be on the same share as ourl.
1334 * @return 0 on success, < 0 on error with errno set:
1335 * - EISDIR nurl is an existing directory, but ourl is
1337 * - EEXIST nurl is a non-empty directory,
1338 * i.e., contains entries other than "." and ".."
1339 * - EINVAL The new url contained a path prefix
1340 * of the old, or, more generally, an attempt was
1341 * made to make a directory a subdirectory of itself
1342 * or smbc_init not called.
1343 * - ENOTDIR A component used as a directory in ourl
1344 * or nurl path is not, in fact, a directory. Or,
1345 * ourl is a directory, and newpath exists but is not
1347 * - EACCES or EPERM Write access to the directory
1348 * containing ourl or nurl is not allowed for the
1349 * process's effective uid, or one of the
1350 * directories in ourl or nurl did not allow search
1351 * (execute) permission, or ourl was a directory
1352 * and did not allow write permission.
1353 * - ENOENT A directory component in ourl or nurl
1355 * - EXDEV Rename across shares not supported.
1356 * - ENOMEM Insufficient kernel memory was available.
1357 * - EEXIST The target file, nurl, already exists.
1360 * @todo Are we going to support copying when urls are not on the same
1361 * share? I say no... NOTE. I agree for the moment.
1364 int smbc_rename(const char *ourl, const char *nurl);
1367 /**@ingroup directory
1368 * Open a directory used to obtain directory entries.
1370 * @param durl The smb url of the directory to open
1372 * @return Valid directory handle. < 0 on error with errno set:
1373 * - EACCES Permission denied.
1374 * - EINVAL A NULL file/URL was passed, or the URL would
1375 * not parse, or was of incorrect form or smbc_init not
1377 * - ENOENT durl does not exist, or name is an
1378 * - ENOMEM Insufficient memory to complete the
1380 * - ENOTDIR name is not a directory.
1381 * - EPERM the workgroup could not be found.
1382 * - ENODEV the workgroup or server could not be found.
1384 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1387 int smbc_opendir(const char *durl);
1390 /**@ingroup directory
1391 * Close a directory handle opened by smbc_opendir().
1393 * @param dh Directory handle to close
1395 * @return 0 on success, < 0 on error with errno set:
1396 * - EBADF dh is an invalid directory handle
1398 * @see smbc_opendir()
1400 int smbc_closedir(int dh);
1403 /**@ingroup directory
1404 * Get multiple directory entries.
1406 * smbc_getdents() reads as many dirent structures from the an open
1407 * directory handle into a specified memory area as will fit.
1409 * @param dh Valid directory as returned by smbc_opendir()
1411 * @param dirp pointer to buffer that will receive the directory
1414 * @param count The size of the dirp buffer in bytes
1416 * @returns If any dirents returned, return will indicate the
1417 * total size. If there were no more dirents available,
1418 * 0 is returned. < 0 indicates an error.
1419 * - EBADF Invalid directory handle
1420 * - EINVAL Result buffer is too small or smbc_init
1422 * - ENOENT No such directory.
1423 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1425 * @todo Are errno values complete and correct?
1427 * @todo Add example code so people know how to parse buffers.
1429 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1432 /**@ingroup directory
1433 * Get a single directory entry.
1435 * @param dh Valid directory as returned by smbc_opendir()
1437 * @return A pointer to a smbc_dirent structure, or NULL if an
1438 * error occurs or end-of-directory is reached:
1439 * - EBADF Invalid directory handle
1440 * - EINVAL smbc_init() failed or has not been called
1442 * @see smbc_dirent, smbc_getdents(), smbc_open()
1444 struct smbc_dirent* smbc_readdir(unsigned int dh);
1447 /**@ingroup directory
1448 * Get the current directory offset.
1450 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1453 * @param dh Valid directory as returned by smbc_opendir()
1455 * @return The current location in the directory stream or -1
1456 * if an error occur. The current location is not
1457 * an offset. Becuase of the implementation, it is a
1458 * handle that allows the library to find the entry
1460 * - EBADF dh is not a valid directory handle
1461 * - EINVAL smbc_init() failed or has not been called
1462 * - ENOTDIR if dh is not a directory
1464 * @see smbc_readdir()
1467 off_t smbc_telldir(int dh);
1470 /**@ingroup directory
1471 * lseek on directories.
1473 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1474 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1476 * @param fd Valid directory as returned by smbc_opendir()
1478 * @param offset The offset (as returned by smbc_telldir). Can be
1479 * NULL, in which case we will rewind
1481 * @return 0 on success, -1 on failure
1482 * - EBADF dh is not a valid directory handle
1483 * - ENOTDIR if dh is not a directory
1484 * - EINVAL offset did not refer to a valid dirent or
1485 * smbc_init not called.
1487 * @see smbc_telldir()
1490 * @todo In what does the reture and errno values mean?
1492 int smbc_lseekdir(int fd, off_t offset);
1494 /**@ingroup directory
1495 * Create a directory.
1497 * @param durl The url of the directory to create
1499 * @param mode Specifies the permissions to use. It is modified
1500 * by the process's umask in the usual way: the
1501 * permissions of the created file are (mode & ~umask).
1503 * @return 0 on success, < 0 on error with errno set:
1504 * - EEXIST directory url already exists
1505 * - EACCES The parent directory does not allow write
1506 * permission to the process, or one of the directories
1507 * - ENOENT A directory component in pathname does not
1509 * - EINVAL NULL durl passed or smbc_init not called.
1510 * - ENOMEM Insufficient memory was available.
1515 int smbc_mkdir(const char *durl, mode_t mode);
1518 /**@ingroup directory
1519 * Remove a directory.
1521 * @param durl The smb url of the directory to remove
1523 * @return 0 on success, < 0 on error with errno set:
1524 * - EACCES or EPERM Write access to the directory
1525 * containing pathname was not allowed.
1526 * - EINVAL durl is NULL or smbc_init not called.
1527 * - ENOENT A directory component in pathname does not
1529 * - ENOTEMPTY directory contains entries.
1530 * - ENOMEM Insufficient kernel memory was available.
1532 * @see smbc_mkdir(), smbc_unlink()
1534 * @todo Are errno values complete and correct?
1536 int smbc_rmdir(const char *durl);
1539 /**@ingroup attribute
1540 * Get information about a file or directory.
1542 * @param url The smb url to get information for
1544 * @param st pointer to a buffer that will be filled with
1545 * standard Unix struct stat information.
1547 * @return 0 on success, < 0 on error with errno set:
1548 * - ENOENT A component of the path file_name does not
1550 * - EINVAL a NULL url was passed or smbc_init not called.
1551 * - EACCES Permission denied.
1552 * - ENOMEM Out of memory
1553 * - ENOTDIR The target dir, url, is not a directory.
1558 int smbc_stat(const char *url, struct stat *st);
1561 /**@ingroup attribute
1562 * Get file information via an file descriptor.
1564 * @param fd Open file handle from smbc_open() or smbc_creat()
1566 * @param st pointer to a buffer that will be filled with
1567 * standard Unix struct stat information.
1569 * @return EBADF filedes is bad.
1570 * - EACCES Permission denied.
1571 * - EBADF fd is not a valid file descriptor
1572 * - EINVAL Problems occurred in the underlying routines
1573 * or smbc_init not called.
1574 * - ENOMEM Out of memory
1576 * @see smbc_stat(), Unix stat()
1579 int smbc_fstat(int fd, struct stat *st);
1582 /**@ingroup attribute
1583 * Truncate a file given a file descriptor
1585 * @param fd Open file handle from smbc_open() or smbc_creat()
1587 * @param size size to truncate the file to
1589 * @return EBADF filedes is bad.
1590 * - EACCES Permission denied.
1591 * - EBADF fd is not a valid file descriptor
1592 * - EINVAL Problems occurred in the underlying routines
1593 * or smbc_init not called.
1594 * - ENOMEM Out of memory
1596 * @see , Unix ftruncate()
1599 int smbc_ftruncate(int fd, off_t size);
1602 /**@ingroup attribute
1603 * Change the permissions of a file.
1605 * @param url The smb url of the file or directory to change
1608 * @param mode The permissions to set:
1609 * - Put good explaination of permissions here!
1611 * @return 0 on success, < 0 on error with errno set:
1612 * - EPERM The effective UID does not match the owner
1613 * of the file, and is not zero
1614 * - ENOENT The file does not exist.
1615 * - ENOMEM Insufficient was available.
1616 * - ENOENT file or directory does not exist
1618 * @todo Actually implement this fuction?
1620 * @todo Are errno values complete and correct?
1622 int smbc_chmod(const char *url, mode_t mode);
1625 * @ingroup attribute
1626 * Change the last modification time on a file
1628 * @param url The smb url of the file or directory to change
1629 * the modification time of
1631 * @param tbuf An array of two timeval structures which contains,
1632 * respectively, the desired access and modification times.
1633 * NOTE: Only the tv_sec field off each timeval structure is
1634 * used. The tv_usec (microseconds) portion is ignored.
1636 * @return 0 on success, < 0 on error with errno set:
1637 * - EINVAL The client library is not properly initialized
1638 * - EPERM Permission was denied.
1641 int smbc_utimes(const char *url, struct timeval *tbuf);
1645 * @ingroup attribute
1646 * Change the last modification time on a file
1648 * @param url The smb url of the file or directory to change
1649 * the modification time of
1651 * @param utbuf A pointer to a utimebuf structure which contains the
1652 * desired access and modification times.
1654 * @return 0 on success, < 0 on error with errno set:
1655 * - EINVAL The client library is not properly initialized
1656 * - ENOMEM No memory was available for internal needs
1657 * - EPERM Permission was denied.
1660 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1663 /**@ingroup attribute
1664 * Set extended attributes for a file. This is used for modifying a file's
1665 * security descriptor (i.e. owner, group, and access control list)
1667 * @param url The smb url of the file or directory to set extended
1670 * @param name The name of an attribute to be changed. Names are of
1671 * one of the following forms:
1673 * system.nt_sec_desc.<attribute name>
1674 * system.nt_sec_desc.*
1675 * system.nt_sec_desc.*+
1677 * where <attribute name> is one of:
1685 * acl+:<name or sid>
1687 * In the forms "system.nt_sec_desc.*" and
1688 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1689 * literal, i.e. the string is provided exactly as shown, and
1690 * the value parameter should contain a complete security
1691 * descriptor with name:value pairs separated by tabs,
1692 * commas, or newlines (not spaces!).
1694 * The plus sign ('+') indicates that SIDs should be mapped
1695 * to names. Without the plus sign, SIDs are not mapped;
1696 * rather they are simply converted to a string format.
1698 * @param value The value to be assigned to the specified attribute name.
1699 * This buffer should contain only the attribute value if the
1700 * name was of the "system.nt_sec_desc.<attribute_name>"
1701 * form. If the name was of the "system.nt_sec_desc.*" form
1702 * then a complete security descriptor, with name:value pairs
1703 * separated by tabs, commas, or newlines (not spaces!),
1704 * should be provided in this value buffer. A complete
1705 * security descriptor will contain one or more entries
1706 * selected from the following:
1708 * REVISION:<revision number>
1709 * OWNER:<sid or name>
1710 * GROUP:<sid or name>
1711 * ACL:<sid or name>:<type>/<flags>/<mask>
1713 * The revision of the ACL specifies the internal Windows NT
1714 * ACL revision for the security descriptor. If not specified
1715 * it defaults to 1. Using values other than 1 may cause
1716 * strange behaviour.
1718 * The owner and group specify the owner and group sids for
1719 * the object. If the attribute name (either '*+' with a
1720 * complete security descriptor, or individual 'owner+' or
1721 * 'group+' attribute names) ended with a plus sign, the
1722 * specified name is resolved to a SID value, using the
1723 * server on which the file or directory resides. Otherwise,
1724 * the value should be provided in SID-printable format as
1725 * S-1-x-y-z, and is used directly. The <sid or name>
1726 * associated with the ACL: attribute should be provided
1729 * @param size The number of the bytes of data in the value buffer
1731 * @param flags A bit-wise OR of zero or more of the following:
1732 * SMBC_XATTR_FLAG_CREATE -
1733 * fail if the named attribute already exists
1734 * SMBC_XATTR_FLAG_REPLACE -
1735 * fail if the attribute does not already exist
1737 * If neither flag is specified, the specified attributes
1738 * will be added or replace existing attributes of the same
1739 * name, as necessary.
1741 * @return 0 on success, < 0 on error with errno set:
1742 * - EINVAL The client library is not properly initialized
1743 * or one of the parameters is not of a correct
1745 * - ENOMEM No memory was available for internal needs
1746 * - EEXIST If the attribute already exists and the flag
1747 * SMBC_XATTR_FLAG_CREAT was specified
1748 * - ENOATTR If the attribute does not exist and the flag
1749 * SMBC_XATTR_FLAG_REPLACE was specified
1750 * - EPERM Permission was denied.
1751 * - ENOTSUP The referenced file system does not support
1752 * extended attributes
1754 * @note Attribute names are compared in a case-insensitive
1755 * fashion. All of the following are equivalent, although
1756 * the all-lower-case name is the preferred format:
1757 * system.nt_sec_desc.owner
1758 * SYSTEM.NT_SEC_DESC.OWNER
1759 * sYsTeM.nt_sEc_desc.owNER
1762 int smbc_setxattr(const char *url,
1769 /**@ingroup attribute
1770 * Set extended attributes for a file. This is used for modifying a file's
1771 * security descriptor (i.e. owner, group, and access control list). The
1772 * POSIX function which this maps to would act on a symbolic link rather than
1773 * acting on what the symbolic link points to, but with no symbolic links in
1774 * SMB file systems, this function is functionally identical to
1777 * @param url The smb url of the file or directory to set extended
1780 * @param name The name of an attribute to be changed. Names are of
1781 * one of the following forms:
1783 * system.nt_sec_desc.<attribute name>
1784 * system.nt_sec_desc.*
1785 * system.nt_sec_desc.*+
1787 * where <attribute name> is one of:
1795 * acl+:<name or sid>
1797 * In the forms "system.nt_sec_desc.*" and
1798 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1799 * literal, i.e. the string is provided exactly as shown, and
1800 * the value parameter should contain a complete security
1801 * descriptor with name:value pairs separated by tabs,
1802 * commas, or newlines (not spaces!).
1804 * The plus sign ('+') indicates that SIDs should be mapped
1805 * to names. Without the plus sign, SIDs are not mapped;
1806 * rather they are simply converted to a string format.
1808 * @param value The value to be assigned to the specified attribute name.
1809 * This buffer should contain only the attribute value if the
1810 * name was of the "system.nt_sec_desc.<attribute_name>"
1811 * form. If the name was of the "system.nt_sec_desc.*" form
1812 * then a complete security descriptor, with name:value pairs
1813 * separated by tabs, commas, or newlines (not spaces!),
1814 * should be provided in this value buffer. A complete
1815 * security descriptor will contain one or more entries
1816 * selected from the following:
1818 * REVISION:<revision number>
1819 * OWNER:<sid or name>
1820 * GROUP:<sid or name>
1821 * ACL:<sid or name>:<type>/<flags>/<mask>
1823 * The revision of the ACL specifies the internal Windows NT
1824 * ACL revision for the security descriptor. If not specified
1825 * it defaults to 1. Using values other than 1 may cause
1826 * strange behaviour.
1828 * The owner and group specify the owner and group sids for
1829 * the object. If the attribute name (either '*+' with a
1830 * complete security descriptor, or individual 'owner+' or
1831 * 'group+' attribute names) ended with a plus sign, the
1832 * specified name is resolved to a SID value, using the
1833 * server on which the file or directory resides. Otherwise,
1834 * the value should be provided in SID-printable format as
1835 * S-1-x-y-z, and is used directly. The <sid or name>
1836 * associated with the ACL: attribute should be provided
1839 * @param size The number of the bytes of data in the value buffer
1841 * @param flags A bit-wise OR of zero or more of the following:
1842 * SMBC_XATTR_FLAG_CREATE -
1843 * fail if the named attribute already exists
1844 * SMBC_XATTR_FLAG_REPLACE -
1845 * fail if the attribute does not already exist
1847 * If neither flag is specified, the specified attributes
1848 * will be added or replace existing attributes of the same
1849 * name, as necessary.
1851 * @return 0 on success, < 0 on error with errno set:
1852 * - EINVAL The client library is not properly initialized
1853 * or one of the parameters is not of a correct
1855 * - ENOMEM No memory was available for internal needs
1856 * - EEXIST If the attribute already exists and the flag
1857 * SMBC_XATTR_FLAG_CREAT was specified
1858 * - ENOATTR If the attribute does not exist and the flag
1859 * SMBC_XATTR_FLAG_REPLACE was specified
1860 * - EPERM Permission was denied.
1861 * - ENOTSUP The referenced file system does not support
1862 * extended attributes
1864 * @note Attribute names are compared in a case-insensitive
1865 * fashion. All of the following are equivalent, although
1866 * the all-lower-case name is the preferred format:
1867 * system.nt_sec_desc.owner
1868 * SYSTEM.NT_SEC_DESC.OWNER
1869 * sYsTeM.nt_sEc_desc.owNER
1872 int smbc_lsetxattr(const char *url,
1879 /**@ingroup attribute
1880 * Set extended attributes for a file. This is used for modifying a file's
1881 * security descriptor (i.e. owner, group, and access control list)
1883 * @param fd A file descriptor associated with an open file (as
1884 * previously returned by smbc_open(), to get extended
1887 * @param name The name of an attribute to be changed. Names are of
1888 * one of the following forms:
1890 * system.nt_sec_desc.<attribute name>
1891 * system.nt_sec_desc.*
1892 * system.nt_sec_desc.*+
1894 * where <attribute name> is one of:
1902 * acl+:<name or sid>
1904 * In the forms "system.nt_sec_desc.*" and
1905 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1906 * literal, i.e. the string is provided exactly as shown, and
1907 * the value parameter should contain a complete security
1908 * descriptor with name:value pairs separated by tabs,
1909 * commas, or newlines (not spaces!).
1911 * The plus sign ('+') indicates that SIDs should be mapped
1912 * to names. Without the plus sign, SIDs are not mapped;
1913 * rather they are simply converted to a string format.
1915 * @param value The value to be assigned to the specified attribute name.
1916 * This buffer should contain only the attribute value if the
1917 * name was of the "system.nt_sec_desc.<attribute_name>"
1918 * form. If the name was of the "system.nt_sec_desc.*" form
1919 * then a complete security descriptor, with name:value pairs
1920 * separated by tabs, commas, or newlines (not spaces!),
1921 * should be provided in this value buffer. A complete
1922 * security descriptor will contain one or more entries
1923 * selected from the following:
1925 * REVISION:<revision number>
1926 * OWNER:<sid or name>
1927 * GROUP:<sid or name>
1928 * ACL:<sid or name>:<type>/<flags>/<mask>
1930 * The revision of the ACL specifies the internal Windows NT
1931 * ACL revision for the security descriptor. If not specified
1932 * it defaults to 1. Using values other than 1 may cause
1933 * strange behaviour.
1935 * The owner and group specify the owner and group sids for
1936 * the object. If the attribute name (either '*+' with a
1937 * complete security descriptor, or individual 'owner+' or
1938 * 'group+' attribute names) ended with a plus sign, the
1939 * specified name is resolved to a SID value, using the
1940 * server on which the file or directory resides. Otherwise,
1941 * the value should be provided in SID-printable format as
1942 * S-1-x-y-z, and is used directly. The <sid or name>
1943 * associated with the ACL: attribute should be provided
1946 * @param size The number of the bytes of data in the value buffer
1948 * @param flags A bit-wise OR of zero or more of the following:
1949 * SMBC_XATTR_FLAG_CREATE -
1950 * fail if the named attribute already exists
1951 * SMBC_XATTR_FLAG_REPLACE -
1952 * fail if the attribute does not already exist
1954 * If neither flag is specified, the specified attributes
1955 * will be added or replace existing attributes of the same
1956 * name, as necessary.
1958 * @return 0 on success, < 0 on error with errno set:
1959 * - EINVAL The client library is not properly initialized
1960 * or one of the parameters is not of a correct
1962 * - ENOMEM No memory was available for internal needs
1963 * - EEXIST If the attribute already exists and the flag
1964 * SMBC_XATTR_FLAG_CREAT was specified
1965 * - ENOATTR If the attribute does not exist and the flag
1966 * SMBC_XATTR_FLAG_REPLACE was specified
1967 * - EPERM Permission was denied.
1968 * - ENOTSUP The referenced file system does not support
1969 * extended attributes
1971 * @note Attribute names are compared in a case-insensitive
1972 * fashion. All of the following are equivalent, although
1973 * the all-lower-case name is the preferred format:
1974 * system.nt_sec_desc.owner
1975 * SYSTEM.NT_SEC_DESC.OWNER
1976 * sYsTeM.nt_sEc_desc.owNER
1979 int smbc_fsetxattr(int fd,
1986 /**@ingroup attribute
1987 * Get extended attributes for a file.
1989 * @param url The smb url of the file or directory to get extended
1992 * @param name The name of an attribute to be retrieved. Names are of
1993 * one of the following forms:
1995 * system.nt_sec_desc.<attribute name>
1996 * system.nt_sec_desc.*
1997 * system.nt_sec_desc.*+
1999 * where <attribute name> is one of:
2007 * acl+:<name or sid>
2009 * In the forms "system.nt_sec_desc.*" and
2010 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2011 * literal, i.e. the string is provided exactly as shown, and
2012 * the value parameter will return a complete security
2013 * descriptor with name:value pairs separated by tabs,
2014 * commas, or newlines (not spaces!).
2016 * The plus sign ('+') indicates that SIDs should be mapped
2017 * to names. Without the plus sign, SIDs are not mapped;
2018 * rather they are simply converted to a string format.
2020 * @param value A pointer to a buffer in which the value of the specified
2021 * attribute will be placed (unless size is zero).
2023 * @param size The size of the buffer pointed to by value. This parameter
2024 * may also be zero, in which case the size of the buffer
2025 * required to hold the attribute value will be returned,
2026 * but nothing will be placed into the value buffer.
2028 * @return 0 on success, < 0 on error with errno set:
2029 * - EINVAL The client library is not properly initialized
2030 * or one of the parameters is not of a correct
2032 * - ENOMEM No memory was available for internal needs
2033 * - EEXIST If the attribute already exists and the flag
2034 * SMBC_XATTR_FLAG_CREAT was specified
2035 * - ENOATTR If the attribute does not exist and the flag
2036 * SMBC_XATTR_FLAG_REPLACE was specified
2037 * - EPERM Permission was denied.
2038 * - ENOTSUP The referenced file system does not support
2039 * extended attributes
2042 int smbc_getxattr(const char *url,
2048 /**@ingroup attribute
2049 * Get extended attributes for a file. The POSIX function which this maps to
2050 * would act on a symbolic link rather than acting on what the symbolic link
2051 * points to, but with no symbolic links in SMB file systems, this function
2052 * is functionally identical to smbc_getxattr().
2054 * @param url The smb url of the file or directory to get extended
2057 * @param name The name of an attribute to be retrieved. Names are of
2058 * one of the following forms:
2060 * system.nt_sec_desc.<attribute name>
2061 * system.nt_sec_desc.*
2062 * system.nt_sec_desc.*+
2064 * where <attribute name> is one of:
2072 * acl+:<name or sid>
2074 * In the forms "system.nt_sec_desc.*" and
2075 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2076 * literal, i.e. the string is provided exactly as shown, and
2077 * the value parameter will return a complete security
2078 * descriptor with name:value pairs separated by tabs,
2079 * commas, or newlines (not spaces!).
2081 * The plus sign ('+') indicates that SIDs should be mapped
2082 * to names. Without the plus sign, SIDs are not mapped;
2083 * rather they are simply converted to a string format.
2085 * @param value A pointer to a buffer in which the value of the specified
2086 * attribute will be placed (unless size is zero).
2088 * @param size The size of the buffer pointed to by value. This parameter
2089 * may also be zero, in which case the size of the buffer
2090 * required to hold the attribute value will be returned,
2091 * but nothing will be placed into the value buffer.
2093 * @return 0 on success, < 0 on error with errno set:
2094 * - EINVAL The client library is not properly initialized
2095 * or one of the parameters is not of a correct
2097 * - ENOMEM No memory was available for internal needs
2098 * - EEXIST If the attribute already exists and the flag
2099 * SMBC_XATTR_FLAG_CREAT was specified
2100 * - ENOATTR If the attribute does not exist and the flag
2101 * SMBC_XATTR_FLAG_REPLACE was specified
2102 * - EPERM Permission was denied.
2103 * - ENOTSUP The referenced file system does not support
2104 * extended attributes
2107 int smbc_lgetxattr(const char *url,
2113 /**@ingroup attribute
2114 * Get extended attributes for a file.
2116 * @param fd A file descriptor associated with an open file (as
2117 * previously returned by smbc_open(), to get extended
2120 * @param name The name of an attribute to be retrieved. Names are of
2121 * one of the following forms:
2123 * system.nt_sec_desc.<attribute name>
2124 * system.nt_sec_desc.*
2125 * system.nt_sec_desc.*+
2127 * where <attribute name> is one of:
2135 * acl+:<name or sid>
2137 * In the forms "system.nt_sec_desc.*" and
2138 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2139 * literal, i.e. the string is provided exactly as shown, and
2140 * the value parameter will return a complete security
2141 * descriptor with name:value pairs separated by tabs,
2142 * commas, or newlines (not spaces!).
2144 * The plus sign ('+') indicates that SIDs should be mapped
2145 * to names. Without the plus sign, SIDs are not mapped;
2146 * rather they are simply converted to a string format.
2148 * @param value A pointer to a buffer in which the value of the specified
2149 * attribute will be placed (unless size is zero).
2151 * @param size The size of the buffer pointed to by value. This parameter
2152 * may also be zero, in which case the size of the buffer
2153 * required to hold the attribute value will be returned,
2154 * but nothing will be placed into the value buffer.
2156 * @return 0 on success, < 0 on error with errno set:
2157 * - EINVAL The client library is not properly initialized
2158 * or one of the parameters is not of a correct
2160 * - ENOMEM No memory was available for internal needs
2161 * - EEXIST If the attribute already exists and the flag
2162 * SMBC_XATTR_FLAG_CREAT was specified
2163 * - ENOATTR If the attribute does not exist and the flag
2164 * SMBC_XATTR_FLAG_REPLACE was specified
2165 * - EPERM Permission was denied.
2166 * - ENOTSUP The referenced file system does not support
2167 * extended attributes
2170 int smbc_fgetxattr(int fd,
2176 /**@ingroup attribute
2177 * Remove extended attributes for a file. This is used for modifying a file's
2178 * security descriptor (i.e. owner, group, and access control list)
2180 * @param url The smb url of the file or directory to remove the extended
2183 * @param name The name of an attribute to be removed. Names are of
2184 * one of the following forms:
2186 * system.nt_sec_desc.<attribute name>
2187 * system.nt_sec_desc.*
2188 * system.nt_sec_desc.*+
2190 * where <attribute name> is one of:
2198 * acl+:<name or sid>
2200 * In the forms "system.nt_sec_desc.*" and
2201 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2202 * literal, i.e. the string is provided exactly as shown, and
2203 * the value parameter will return a complete security
2204 * descriptor with name:value pairs separated by tabs,
2205 * commas, or newlines (not spaces!).
2207 * The plus sign ('+') indicates that SIDs should be mapped
2208 * to names. Without the plus sign, SIDs are not mapped;
2209 * rather they are simply converted to a string format.
2211 * @return 0 on success, < 0 on error with errno set:
2212 * - EINVAL The client library is not properly initialized
2213 * - ENOMEM No memory was available for internal needs
2214 * - EPERM Permission was denied.
2215 * - ENOTSUP The referenced file system does not support
2216 * extended attributes
2219 int smbc_removexattr(const char *url,
2223 /**@ingroup attribute
2224 * Remove extended attributes for a file. This is used for modifying a file's
2225 * security descriptor (i.e. owner, group, and access control list) The POSIX
2226 * function which this maps to would act on a symbolic link rather than acting
2227 * on what the symbolic link points to, but with no symbolic links in SMB file
2228 * systems, this function is functionally identical to smbc_removexattr().
2230 * @param url The smb url of the file or directory to remove the extended
2233 * @param name The name of an attribute to be removed. Names are of
2234 * one of the following forms:
2236 * system.nt_sec_desc.<attribute name>
2237 * system.nt_sec_desc.*
2238 * system.nt_sec_desc.*+
2240 * where <attribute name> is one of:
2248 * acl+:<name or sid>
2250 * In the forms "system.nt_sec_desc.*" and
2251 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2252 * literal, i.e. the string is provided exactly as shown, and
2253 * the value parameter will return a complete security
2254 * descriptor with name:value pairs separated by tabs,
2255 * commas, or newlines (not spaces!).
2257 * The plus sign ('+') indicates that SIDs should be mapped
2258 * to names. Without the plus sign, SIDs are not mapped;
2259 * rather they are simply converted to a string format.
2261 * @return 0 on success, < 0 on error with errno set:
2262 * - EINVAL The client library is not properly initialized
2263 * - ENOMEM No memory was available for internal needs
2264 * - EPERM Permission was denied.
2265 * - ENOTSUP The referenced file system does not support
2266 * extended attributes
2269 int smbc_lremovexattr(const char *url,
2273 /**@ingroup attribute
2274 * Remove extended attributes for a file. This is used for modifying a file's
2275 * security descriptor (i.e. owner, group, and access control list)
2277 * @param fd A file descriptor associated with an open file (as
2278 * previously returned by smbc_open(), to get extended
2281 * @param name The name of an attribute to be removed. Names are of
2282 * one of the following forms:
2284 * system.nt_sec_desc.<attribute name>
2285 * system.nt_sec_desc.*
2286 * system.nt_sec_desc.*+
2288 * where <attribute name> is one of:
2296 * acl+:<name or sid>
2298 * In the forms "system.nt_sec_desc.*" and
2299 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2300 * literal, i.e. the string is provided exactly as shown, and
2301 * the value parameter will return a complete security
2302 * descriptor with name:value pairs separated by tabs,
2303 * commas, or newlines (not spaces!).
2305 * The plus sign ('+') indicates that SIDs should be mapped
2306 * to names. Without the plus sign, SIDs are not mapped;
2307 * rather they are simply converted to a string format.
2309 * @return 0 on success, < 0 on error with errno set:
2310 * - EINVAL The client library is not properly initialized
2311 * - ENOMEM No memory was available for internal needs
2312 * - EPERM Permission was denied.
2313 * - ENOTSUP The referenced file system does not support
2314 * extended attributes
2317 int smbc_fremovexattr(int fd,
2321 /**@ingroup attribute
2322 * List the supported extended attribute names associated with a file
2324 * @param url The smb url of the file or directory to list the extended
2327 * @param list A pointer to a buffer in which the list of attributes for
2328 * the specified file or directory will be placed (unless
2331 * @param size The size of the buffer pointed to by list. This parameter
2332 * may also be zero, in which case the size of the buffer
2333 * required to hold all of the attribute names will be
2334 * returned, but nothing will be placed into the list buffer.
2336 * @return 0 on success, < 0 on error with errno set:
2337 * - EINVAL The client library is not properly initialized
2338 * - ENOMEM No memory was available for internal needs
2339 * - EPERM Permission was denied.
2340 * - ENOTSUP The referenced file system does not support
2341 * extended attributes
2343 * @note This function always returns all attribute names supported
2344 * by NT file systems, regardless of whether the referenced
2345 * file system supports extended attributes (e.g. a Windows
2346 * 2000 machine supports extended attributes if NTFS is used,
2347 * but not if FAT is used, and Windows 98 doesn't support
2348 * extended attributes at all. Whether this is a feature or
2349 * a bug is yet to be decided.
2351 int smbc_listxattr(const char *url,
2355 /**@ingroup attribute
2356 * List the supported extended attribute names associated with a file The
2357 * POSIX function which this maps to would act on a symbolic link rather than
2358 * acting on what the symbolic link points to, but with no symbolic links in
2359 * SMB file systems, this function is functionally identical to
2362 * @param url The smb url of the file or directory to list the extended
2365 * @param list A pointer to a buffer in which the list of attributes for
2366 * the specified file or directory will be placed (unless
2369 * @param size The size of the buffer pointed to by list. This parameter
2370 * may also be zero, in which case the size of the buffer
2371 * required to hold all of the attribute names will be
2372 * returned, but nothing will be placed into the list buffer.
2374 * @return 0 on success, < 0 on error with errno set:
2375 * - EINVAL The client library is not properly initialized
2376 * - ENOMEM No memory was available for internal needs
2377 * - EPERM Permission was denied.
2378 * - ENOTSUP The referenced file system does not support
2379 * extended attributes
2381 * @note This function always returns all attribute names supported
2382 * by NT file systems, regardless of wether the referenced
2383 * file system supports extended attributes (e.g. a Windows
2384 * 2000 machine supports extended attributes if NTFS is used,
2385 * but not if FAT is used, and Windows 98 doesn't support
2386 * extended attributes at all. Whether this is a feature or
2387 * a bug is yet to be decided.
2389 int smbc_llistxattr(const char *url,
2393 /**@ingroup attribute
2394 * List the supported extended attribute names associated with a file
2396 * @param fd A file descriptor associated with an open file (as
2397 * previously returned by smbc_open(), to get extended
2400 * @param list A pointer to a buffer in which the list of attributes for
2401 * the specified file or directory will be placed (unless
2404 * @param size The size of the buffer pointed to by list. This parameter
2405 * may also be zero, in which case the size of the buffer
2406 * required to hold all of the attribute names will be
2407 * returned, but nothing will be placed into the list buffer.
2409 * @return 0 on success, < 0 on error with errno set:
2410 * - EINVAL The client library is not properly initialized
2411 * - ENOMEM No memory was available for internal needs
2412 * - EPERM Permission was denied.
2413 * - ENOTSUP The referenced file system does not support
2414 * extended attributes
2416 * @note This function always returns all attribute names supported
2417 * by NT file systems, regardless of wether the referenced
2418 * file system supports extended attributes (e.g. a Windows
2419 * 2000 machine supports extended attributes if NTFS is used,
2420 * but not if FAT is used, and Windows 98 doesn't support
2421 * extended attributes at all. Whether this is a feature or
2422 * a bug is yet to be decided.
2424 int smbc_flistxattr(int fd,
2429 * Print a file given the name in fname. It would be a URL ...
2431 * @param fname The URL of a file on a remote SMB server that the
2432 * caller wants printed
2434 * @param printq The URL of the print share to print the file to.
2436 * @return 0 on success, < 0 on error with errno set:
2438 * - EINVAL fname or printq was NULL or smbc_init not
2440 * and errors returned by smbc_open
2443 int smbc_print_file(const char *fname, const char *printq);
2446 * Open a print file that can be written to by other calls. This simply
2447 * does an smbc_open call after checking if there is a file name on the
2448 * URI. If not, a temporary name is added ...
2450 * @param fname The URL of the print share to print to?
2452 * @returns A file handle for the print file if successful.
2453 * Returns -1 if an error ocurred and errno has the values
2454 * - EINVAL fname was NULL or smbc_init not called.
2455 * - all errors returned by smbc_open
2458 int smbc_open_print_job(const char *fname);
2461 * List the print jobs on a print share, for the moment, pass a callback
2463 * @param purl The url of the print share to list the jobs of
2465 * @param fn Callback function the receives printjob info
2467 * @return 0 on success, < 0 on error with errno set:
2468 * - EINVAL fname was NULL or smbc_init not called
2471 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2474 * Delete a print job
2476 * @param purl Url of the print share
2478 * @param id The id of the job to delete
2480 * @return 0 on success, < 0 on error with errno set:
2481 * - EINVAL fname was NULL or smbc_init not called
2483 * @todo what errno values are possible here?
2485 int smbc_unlink_print_job(const char *purl, int id);
2487 /**@ingroup callback
2488 * Remove a server from the cached server list it's unused.
2490 * @param context pointer to smb context
2492 * @param srv pointer to server to remove
2494 * @return On success, 0 is returned. 1 is returned if the server could not
2495 * be removed. Also useable outside libsmbclient.
2497 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2503 /**@ingroup directory
2504 * Convert strings of %xx to their single character equivalent.
2506 * @param dest A pointer to a buffer in which the resulting decoded
2507 * string should be placed. This may be a pointer to the
2508 * same buffer as src_segment.
2510 * @param src A pointer to the buffer containing the URL to be decoded.
2511 * Any %xx sequences herein are converted to their single
2512 * character equivalent. Each 'x' must be a valid hexadecimal
2513 * digit, or that % sequence is left undecoded.
2515 * @param max_dest_len
2516 * The size of the buffer pointed to by dest_segment.
2518 * @return The number of % sequences which could not be converted
2519 * due to lack of two following hexadecimal digits.
2525 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2532 * Convert any characters not specifically allowed in a URL into their %xx
2535 * @param dest A pointer to a buffer in which the resulting encoded
2536 * string should be placed. Unlike smbc_urldecode(), this
2537 * must be a buffer unique from src.
2539 * @param src A pointer to the buffer containing the string to be encoded.
2540 * Any character not specifically allowed in a URL is converted
2541 * into its hexadecimal value and encoded as %xx.
2543 * @param max_dest_len
2544 * The size of the buffer pointed to by dest_segment.
2546 * @returns The remaining buffer length.
2552 smbc_urlencode(char * dest, char * src, int max_dest_len);
2558 /**@ingroup directory
2559 * Return the version of the linked Samba code, and thus the version of the
2560 * libsmbclient code.
2562 * @return The version string.
2574 * Set the users credentials globally so they can be used for DFS
2575 * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2578 * @param workgroup Workgroup of the user.
2580 * @param user Username of user.
2582 * @param password Password of user.
2584 * @param use_kerberos Whether to use Kerberos
2586 * @param signing_state One of these strings (all equivalents on same line):
2587 * "off", "no", "false"
2588 * "on", "yes", "true", "auto"
2589 * "force", "required", "forced"
2593 smbc_set_credentials(char *workgroup,
2596 smbc_bool use_kerberos,
2597 char *signing_state);
2601 * @ingroup structure
2602 * Structure that contains a client context information
2603 * This structure is known as SMBCCTX
2605 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
2606 * structure should all be considered private to the library. It remains here
2607 * only for backward compatibility.
2609 * See the comments herein for use of the setter and getter functions which
2610 * should now be used for manipulating these values. New features, functions,
2611 * etc., are not added here but rather in _internal where they are not
2612 * directly visible to applications. This makes it much easier to maintain
2613 * ABI compatibility.
2621 * Use smbc_getDebug() and smbc_setDebug()
2623 int debug DEPRECATED_SMBC_INTERFACE;
2626 * netbios name used for making connections
2629 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2631 char * netbios_name DEPRECATED_SMBC_INTERFACE;
2634 * workgroup name used for making connections
2637 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2639 char * workgroup DEPRECATED_SMBC_INTERFACE;
2642 * username used for making connections
2645 * Use smbc_getUser() and smbc_setUser()
2647 char * user DEPRECATED_SMBC_INTERFACE;
2650 * timeout used for waiting on connections / response data (in
2654 * Use smbc_getTimeout() and smbc_setTimeout()
2656 int timeout DEPRECATED_SMBC_INTERFACE;
2659 * callable functions for files:
2660 * For usage and return values see the SMBC_* functions
2664 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2665 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2667 smbc_open_fn open DEPRECATED_SMBC_INTERFACE;
2668 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE;
2669 smbc_read_fn read DEPRECATED_SMBC_INTERFACE;
2670 smbc_write_fn write DEPRECATED_SMBC_INTERFACE;
2671 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE;
2672 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE;
2673 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE;
2674 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE;
2675 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE;
2676 #if 0 /* internal */
2677 smbc_ftruncate_fn ftruncate_fn;
2679 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE;
2680 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
2681 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
2682 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
2683 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE;
2684 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE;
2685 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE;
2686 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE;
2687 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE;
2688 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE;
2689 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE;
2690 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE;
2691 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE;
2692 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE;
2693 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE;
2694 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE;
2696 /* Printing-related functions */
2697 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE;
2698 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE;
2699 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE;
2700 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE;
2707 * See the comment above each field, for the getter and setter
2708 * functions that should now be used.
2710 struct _smbc_callbacks
2713 * authentication function callback: called upon auth requests
2716 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2718 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
2721 * check if a server is still good
2724 * Use smbc_getFunctionCheckServer(),
2725 * smbc_setFunctionCheckServer()
2727 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
2730 * remove a server if unused
2733 * Use smbc_getFunctionRemoveUnusedServer(),
2734 * smbc_setFunctionCheckServer()
2736 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
2740 * For an example cache system see
2741 * samba/source/libsmb/libsmb_cache.c
2743 * Cache subsystem * functions follow.
2747 * server cache addition
2750 * Use smbc_getFunctionAddCachedServer(),
2751 * smbc_setFunctionAddCachedServer()
2753 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2756 * server cache lookup
2759 * Use smbc_getFunctionGetCachedServer(),
2760 * smbc_setFunctionGetCachedServer()
2762 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2765 * server cache removal
2768 * Use smbc_getFunctionRemoveCachedServer(),
2769 * smbc_setFunctionRemoveCachedServer()
2771 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2774 * server cache purging, try to remove all cached servers
2778 * Use smbc_getFunctionPurgeCachedServers(),
2779 * smbc_setFunctionPurgeCachedServers()
2781 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
2785 * Space where the private data of the server cache used to be
2788 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
2790 void * reserved DEPRECATED_SMBC_INTERFACE;
2793 * Very old configuration options.
2796 * Use one of the following functions instead:
2797 * smbc_setOptionUseKerberos()
2798 * smbc_getOptionUseKerberos()
2799 * smbc_setOptionFallbackAfterKerberos()
2800 * smbc_getOptionFallbackAfterKerberos()
2801 * smbc_setOptionNoAutoAnonymousLogin()
2802 * smbc_getOptionNoAutoAnonymousLogin()
2804 int flags DEPRECATED_SMBC_INTERFACE;
2807 * user options selections that apply to this session
2809 * NEW OPTIONS ARE NOT ADDED HERE!
2812 * To set and retrieve options, use the smbc_setOption*() and
2813 * smbc_getOption*() functions.
2815 struct _smbc_options {
2816 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
2817 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
2818 int one_share_per_server DEPRECATED_SMBC_INTERFACE;
2819 } options DEPRECATED_SMBC_INTERFACE;
2822 * do _NOT_ touch this from your program !
2824 struct SMBC_internal_data * internal;
2828 #endif /* SMBCLIENT_H_INCLUDED */