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 * @param srv Server being authenticated to
264 * @param shr Share being authenticated to
266 * @param wg Pointer to buffer containing a "hint" for the
267 * workgroup to be authenticated. Should be filled in
268 * with the correct workgroup if the hint is wrong.
270 * @param wglen The size of the workgroup buffer in bytes
272 * @param un Pointer to buffer containing a "hint" for the
273 * user name to be use for authentication. Should be
274 * filled in with the correct workgroup if the hint is
277 * @param unlen The size of the username buffer in bytes
279 * @param pw Pointer to buffer containing to which password
282 * @param pwlen The size of the password buffer in bytes
285 typedef void (*smbc_get_auth_data_fn)(const char *srv,
289 char *pw, int pwlen);
291 * Authentication callback function type (method that includes context)
293 * Type for the the authentication function called by the library to
294 * obtain authentication credentals
296 * @param c Pointer to the smb context
298 * @param srv Server being authenticated to
300 * @param shr Share being authenticated to
302 * @param wg Pointer to buffer containing a "hint" for the
303 * workgroup to be authenticated. Should be filled in
304 * with the correct workgroup if the hint is wrong.
306 * @param wglen The size of the workgroup buffer in bytes
308 * @param un Pointer to buffer containing a "hint" for the
309 * user name to be use for authentication. Should be
310 * filled in with the correct workgroup if the hint is
313 * @param unlen The size of the username buffer in bytes
315 * @param pw Pointer to buffer containing to which password
318 * @param pwlen The size of the password buffer in bytes
321 typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
326 char *pw, int pwlen);
330 * Print job info callback function type.
332 * @param i pointer to print job information structure
335 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
339 * Check if a server is still good
341 * @param c pointer to smb context
343 * @param srv pointer to server to check
345 * @return 0 when connection is good. 1 on error.
348 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
351 * Remove a server if unused
353 * @param c pointer to smb context
355 * @param srv pointer to server to remove
357 * @return 0 on success. 1 on failure.
360 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
364 * Add a server to the cache system
366 * @param c pointer to smb context
368 * @param srv pointer to server to add
370 * @param server server name
372 * @param share share name
374 * @param workgroup workgroup used to connect
376 * @param username username used to connect
378 * @return 0 on success. 1 on failure.
381 typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
382 const char * server, const char * share,
383 const char * workgroup, const char * username);
386 * Look up a server in the cache system
388 * @param c pointer to smb context
390 * @param server server name to match
392 * @param share share name to match
394 * @param workgroup workgroup to match
396 * @param username username to match
398 * @return pointer to SMBCSRV on success. NULL on failure.
401 typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
402 const char * share, const char * workgroup,
403 const char * username);
406 * Check if a server is still good
408 * @param c pointer to smb context
410 * @param srv pointer to server to remove
412 * @return 0 when found and removed. 1 on failure.
415 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
419 * Try to remove all servers from the cache system and disconnect
421 * @param c pointer to smb context
423 * @return 0 when found and removed. 1 on failure.
426 typedef int (*smbc_purge_cached_fn) (SMBCCTX * c);
430 /*****************************************
431 * Getters and setters for CONFIGURATION *
432 *****************************************/
434 /** Get the debug level */
436 smbc_getDebug(SMBCCTX *c);
438 /** Set the debug level */
440 smbc_setDebug(SMBCCTX *c, int debug);
442 /** Get the netbios name used for making connections */
444 smbc_getNetbiosName(SMBCCTX *c);
446 /** Set the netbios name used for making connections */
448 smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
450 /** Get the workgroup used for making connections */
452 smbc_getWorkgroup(SMBCCTX *c);
454 /** Set the workgroup used for making connections */
455 void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
457 /** Get the username used for making connections */
459 smbc_getUser(SMBCCTX *c);
461 /** Set the username used for making connections */
463 smbc_setUser(SMBCCTX *c, char * user);
466 * Get the timeout used for waiting on connections and response data
470 smbc_getTimeout(SMBCCTX *c);
473 * Set the timeout used for waiting on connections and response data
477 smbc_setTimeout(SMBCCTX *c, int timeout);
481 /***********************************
482 * Getters and setters for OPTIONS *
483 ***********************************/
485 /** Get whether to log to standard error instead of standard output */
487 smbc_getOptionDebugToStderr(SMBCCTX *c);
489 /** Set whether to log to standard error instead of standard output */
491 smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
494 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
495 * than the old-style names such as M_TIME. This allows also setting/getting
496 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
497 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
501 smbc_getOptionFullTimeNames(SMBCCTX *c);
504 * Set 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_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
514 * Get the share mode to use for files opened with SMBC_open_ctx(). The
515 * default is SMBC_SHAREMODE_DENY_NONE.
518 smbc_getOptionOpenShareMode(SMBCCTX *c);
521 * Set the share mode to use for files opened with SMBC_open_ctx(). The
522 * default is SMBC_SHAREMODE_DENY_NONE.
525 smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
527 /** Retrieve a previously saved user data handle */
529 smbc_getOptionUserData(SMBCCTX *c);
531 /** Save a user data handle */
533 smbc_setOptionUserData(SMBCCTX *c, void *user_data);
535 /** Get the encoded value for encryption level. */
536 smbc_smb_encrypt_level
537 smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
539 /** Set the encoded value for encryption level. */
541 smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
544 * Get from how many local master browsers should the list of workgroups be
545 * retrieved. It can take up to 12 minutes or longer after a server becomes a
546 * local master browser, for it to have the entire browse list (the list of
547 * workgroups/domains) from an entire network. Since a client never knows
548 * which local master browser will be found first, the one which is found
549 * first and used to retrieve a browse list may have an incomplete or empty
550 * browse list. By requesting the browse list from multiple local master
551 * browsers, a more complete list can be generated. For small networks (few
552 * workgroups), it is recommended that this value be set to 0, causing the
553 * browse lists from all found local master browsers to be retrieved and
554 * merged. For networks with many workgroups, a suitable value for this
555 * variable is probably somewhere around 3. (Default: 3).
558 smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
561 * Set from how many local master browsers should the list of workgroups be
562 * retrieved. It can take up to 12 minutes or longer after a server becomes a
563 * local master browser, for it to have the entire browse list (the list of
564 * workgroups/domains) from an entire network. Since a client never knows
565 * which local master browser will be found first, the one which is found
566 * first and used to retrieve a browse list may have an incomplete or empty
567 * browse list. By requesting the browse list from multiple local master
568 * browsers, a more complete list can be generated. For small networks (few
569 * workgroups), it is recommended that this value be set to 0, causing the
570 * browse lists from all found local master browsers to be retrieved and
571 * merged. For networks with many workgroups, a suitable value for this
572 * variable is probably somewhere around 3. (Default: 3).
575 smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
578 * Get whether to url-encode readdir entries.
580 * There is a difference in the desired return strings from
581 * smbc_readdir() depending upon whether the filenames are to
582 * be displayed to the user, or whether they are to be
583 * appended to the path name passed to smbc_opendir() to call
584 * a further smbc_ function (e.g. open the file with
585 * smbc_open()). In the former case, the filename should be
586 * in "human readable" form. In the latter case, the smbc_
587 * functions expect a URL which must be url-encoded. Those
588 * functions decode the URL. If, for example, smbc_readdir()
589 * returned a file name of "abc%20def.txt", passing a path
590 * with this file name attached to smbc_open() would cause
591 * smbc_open to attempt to open the file "abc def.txt" since
592 * the %20 is decoded into a space.
594 * Set this option to True if the names returned by
595 * smbc_readdir() should be url-encoded such that they can be
596 * passed back to another smbc_ call. Set it to False if the
597 * names returned by smbc_readdir() are to be presented to the
600 * For backwards compatibility, this option defaults to False.
603 smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
606 * Set whether to url-encode readdir entries.
608 * There is a difference in the desired return strings from
609 * smbc_readdir() depending upon whether the filenames are to
610 * be displayed to the user, or whether they are to be
611 * appended to the path name passed to smbc_opendir() to call
612 * a further smbc_ function (e.g. open the file with
613 * smbc_open()). In the former case, the filename should be
614 * in "human readable" form. In the latter case, the smbc_
615 * functions expect a URL which must be url-encoded. Those
616 * functions decode the URL. If, for example, smbc_readdir()
617 * returned a file name of "abc%20def.txt", passing a path
618 * with this file name attached to smbc_open() would cause
619 * smbc_open to attempt to open the file "abc def.txt" since
620 * the %20 is decoded into a space.
622 * Set this option to True if the names returned by
623 * smbc_readdir() should be url-encoded such that they can be
624 * passed back to another smbc_ call. Set it to False if the
625 * names returned by smbc_readdir() are to be presented to the
628 * For backwards compatibility, this option defaults to False.
631 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
634 * Get whether to use the same connection for all shares on a server.
636 * Some Windows versions appear to have a limit to the number
637 * of concurrent SESSIONs and/or TREE CONNECTions. In
638 * one-shot programs (i.e. the program runs and then quickly
639 * ends, thereby shutting down all connections), it is
640 * probably reasonable to establish a new connection for each
641 * share. In long-running applications, the limitation can be
642 * avoided by using only a single connection to each server,
643 * and issuing a new TREE CONNECT when the share is accessed.
646 smbc_getOptionOneSharePerServer(SMBCCTX *c);
649 * Set whether to use the same connection for all shares on a server.
651 * Some Windows versions appear to have a limit to the number
652 * of concurrent SESSIONs and/or TREE CONNECTions. In
653 * one-shot programs (i.e. the program runs and then quickly
654 * ends, thereby shutting down all connections), it is
655 * probably reasonable to establish a new connection for each
656 * share. In long-running applications, the limitation can be
657 * avoided by using only a single connection to each server,
658 * and issuing a new TREE CONNECT when the share is accessed.
661 smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
663 /** Get whether to enable use of kerberos */
665 smbc_getOptionUseKerberos(SMBCCTX *c);
667 /** Set whether to enable use of kerberos */
669 smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
671 /** Get whether to fallback after kerberos */
673 smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
675 /** Set whether to fallback after kerberos */
677 smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
679 /** Get whether to automatically select anonymous login */
681 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
683 /** Set whether to automatically select anonymous login */
685 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
689 /*************************************
690 * Getters and setters for FUNCTIONS *
691 *************************************/
693 /** Get the function for obtaining authentication data */
694 smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
696 /** Set the function for obtaining authentication data */
697 void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
699 /** Get the new-style authentication function which includes the context. */
700 smbc_get_auth_data_with_context_fn
701 smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
703 /** Set the new-style authentication function which includes the context. */
705 smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
706 smbc_get_auth_data_with_context_fn fn);
708 /** Get the function for checking if a server is still good */
709 smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
711 /** Set the function for checking if a server is still good */
712 void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
714 /** Get the function for removing a server if unused */
715 smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
717 /** Set the function for removing a server if unused */
718 void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
719 smbc_remove_unused_server_fn fn);
721 /** Get the function for adding a cached server */
722 smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
724 /** Set the function for adding a cached server */
725 void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
727 /** Get the function for server cache lookup */
728 smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
730 /** Set the function for server cache lookup */
731 void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
733 /** Get the function for server cache removal */
734 smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
736 /** Set the function for server cache removal */
737 void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
738 smbc_remove_cached_srv_fn fn);
741 * Get the function for server cache purging. This function tries to
742 * remove all cached servers (e.g. on disconnect)
744 smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
747 * Set the function for server cache purging. This function tries to
748 * remove all cached servers (e.g. on disconnect)
750 void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
751 smbc_purge_cached_fn fn);
753 /** Get the function to store private data of the server cache */
754 struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
756 /** Set the function to store private data of the server cache */
757 void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
761 /*****************************************************************
762 * Callable functions for files. *
763 * Each callable has a function signature typedef, a declaration *
764 * for the getter, and a declaration for the setter. *
765 *****************************************************************/
767 typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
771 smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
772 void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
774 typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
777 smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
778 void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
780 typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
784 smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
785 void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
787 typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
791 smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
792 void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
794 typedef int (*smbc_unlink_fn)(SMBCCTX *c,
796 smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
797 void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
799 typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
803 smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
804 void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
806 typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
810 smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
811 void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
813 typedef int (*smbc_stat_fn)(SMBCCTX *c,
816 smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
817 void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
819 typedef int (*smbc_fstat_fn)(SMBCCTX *c,
822 smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
823 void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
825 typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
828 smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
829 void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
831 typedef int (*smbc_close_fn)(SMBCCTX *c,
833 smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
834 void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
838 /*****************************************************************
839 * Callable functions for directories. *
840 * Each callable has a function signature typedef, a declaration *
841 * for the getter, and a declaration for the setter. *
842 *****************************************************************/
844 typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
846 smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
847 void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
849 typedef int (*smbc_closedir_fn)(SMBCCTX *c,
851 smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
852 void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
854 typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
856 smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
857 void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
859 typedef int (*smbc_getdents_fn)(SMBCCTX *c,
861 struct smbc_dirent *dirp,
863 smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
864 void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
866 typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
869 smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
870 void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
872 typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
874 smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
875 void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
877 typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
879 smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
880 void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
882 typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
885 smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
886 void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
888 typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
891 smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
892 void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
896 /*****************************************************************
897 * Callable functions applicable to both files and directories. *
898 * Each callable has a function signature typedef, a declaration *
899 * for the getter, and a declaration for the setter. *
900 *****************************************************************/
902 typedef int (*smbc_chmod_fn)(SMBCCTX *c,
905 smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
906 void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
908 typedef int (*smbc_utimes_fn)(SMBCCTX *c,
910 struct timeval *tbuf);
911 smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
912 void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
914 typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
920 smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
921 void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
923 typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
928 smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
929 void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
931 typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
934 smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
935 void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
937 typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
941 smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
942 void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
946 /*****************************************************************
947 * Callable functions for printing. *
948 * Each callable has a function signature typedef, a declaration *
949 * for the getter, and a declaration for the setter. *
950 *****************************************************************/
952 typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
956 smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
957 void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
959 typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
961 smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
962 void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
963 smbc_open_print_job_fn fn);
965 typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
967 smbc_list_print_job_fn fn);
968 smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
969 void smbc_setFunctionListPrintJobs(SMBCCTX *c,
970 smbc_list_print_jobs_fn fn);
972 typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
975 smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
976 void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
977 smbc_unlink_print_job_fn fn);
981 * Create a new SBMCCTX (a context).
983 * Must be called before the context is passed to smbc_context_init()
985 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
986 * - ENOMEM Out of memory
988 * @see smbc_free_context(), smbc_init_context()
990 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
992 SMBCCTX * smbc_new_context(void);
995 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
997 * The context will be deleted if possible.
999 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1001 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1004 * @return Returns 0 on succes. Returns 1 on failure with errno set:
1005 * - EBUSY Server connections are still used, Files are open or cache
1006 * could not be purged
1007 * - EBADF context == NULL
1009 * @see smbc_new_context()
1011 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1012 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1013 * use in periodical cleanup functions for example.
1015 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1020 * @deprecated. Use smbc_setOption*() functions instead.
1023 smbc_option_set(SMBCCTX *context,
1025 ... /* option_value */);
1028 * @deprecated. Use smbc_getOption*() functions instead.
1031 smbc_option_get(SMBCCTX *context,
1035 * Initialize a SBMCCTX (a context).
1037 * Must be called before using any SMBCCTX API function
1039 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1041 * @return A pointer to the given SMBCCTX on success,
1042 * NULL on error with errno set:
1043 * - EBADF NULL context given
1044 * - ENOMEM Out of memory
1045 * - ENOENT The smb.conf file would not load
1047 * @see smbc_new_context()
1049 * @note my_context = smbc_init_context(smbc_new_context())
1050 * is perfectly safe, but it might leak memory on
1051 * smbc_context_init() failure. Avoid this.
1052 * You'll have to call smbc_free_context() yourself
1056 SMBCCTX * smbc_init_context(SMBCCTX * context);
1059 * Initialize the samba client library.
1061 * Must be called before using any of the smbclient API function
1063 * @param fn The function that will be called to obtaion
1064 * authentication credentials.
1066 * @param debug Allows caller to set the debug level. Can be
1067 * changed in smb.conf file. Allows caller to set
1068 * debugging if no smb.conf.
1070 * @return 0 on success, < 0 on error with errno set:
1071 * - ENOMEM Out of memory
1072 * - ENOENT The smb.conf file would not load
1076 int smbc_init(smbc_get_auth_data_fn fn, int debug);
1079 * Set or retrieve the compatibility library's context pointer
1081 * @param context New context to use, or NULL. If a new context is provided,
1082 * it must have allocated with smbc_new_context() and
1083 * initialized with smbc_init_context(), followed, optionally,
1084 * by some manual changes to some of the non-internal fields.
1086 * @return The old context.
1088 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1090 * @note This function may be called prior to smbc_init() to force
1091 * use of the next context without any internal calls to
1092 * smbc_new_context() or smbc_init_context(). It may also
1093 * be called after smbc_init() has already called those two
1094 * functions, to replace the existing context with a new one.
1095 * Care should be taken, in this latter case, to ensure that
1096 * the server cache and any data allocated by the
1097 * authentication functions have been freed, if necessary.
1100 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1103 * Open a file on an SMB server.
1105 * @param furl The smb url of the file to be opened.
1107 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1108 * request opening the file read-only,write-only
1109 * or read/write. flags may also be bitwise-or'd with
1110 * one or more of the following:
1111 * O_CREAT - If the file does not exist it will be
1113 * O_EXCL - When used with O_CREAT, if the file
1114 * already exists it is an error and the open will
1116 * O_TRUNC - If the file already exists it will be
1118 * O_APPEND The file is opened in append mode
1120 * @param mode mode specifies the permissions to use if a new
1121 * file is created. It is modified by the
1122 * process's umask in the usual way: the permissions
1123 * of the created file are (mode & ~umask)
1125 * Not currently use, but there for future use.
1126 * We will map this to SYSTEM, HIDDEN, etc bits
1127 * that reverses the mapping that smbc_fstat does.
1129 * @return Valid file handle, < 0 on error with errno set:
1130 * - ENOMEM Out of memory
1131 * - EINVAL if an invalid parameter passed, like no
1132 * file, or smbc_init not called.
1133 * - EEXIST pathname already exists and O_CREAT and
1135 * - EISDIR pathname refers to a directory and
1136 * the access requested involved writing.
1137 * - EACCES The requested access to the file is not
1139 * - ENODEV The requested share does not exist
1140 * - ENOTDIR A file on the path is not a directory
1141 * - ENOENT A directory component in pathname does
1146 * @note This call uses an underlying routine that may create
1147 * a new connection to the server specified in the URL.
1148 * If the credentials supplied in the URL, or via the
1149 * auth_fn in the smbc_init call, fail, this call will
1150 * try again with an empty username and password. This
1151 * often gets mapped to the guest account on some machines.
1154 int smbc_open(const char *furl, int flags, mode_t mode);
1157 * Create a file on an SMB server.
1159 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1161 * @param furl The smb url of the file to be created
1163 * @param mode mode specifies the permissions to use if a new
1164 * file is created. It is modified by the
1165 * process's umask in the usual way: the permissions
1166 * of the created file are (mode & ~umask)
1168 * NOTE, the above is not true. We are dealing with
1169 * an SMB server, which has no concept of a umask!
1171 * @return Valid file handle, < 0 on error with errno set:
1172 * - ENOMEM Out of memory
1173 * - EINVAL if an invalid parameter passed, like no
1174 * file, or smbc_init not called.
1175 * - EEXIST pathname already exists and O_CREAT and
1177 * - EISDIR pathname refers to a directory and
1178 * the access requested involved writing.
1179 * - EACCES The requested access to the file is not
1181 * - ENOENT A directory component in pathname does
1183 * - ENODEV The requested share does not exist.
1188 int smbc_creat(const char *furl, mode_t mode);
1191 * Read from a file using an opened file handle.
1193 * @param fd Open file handle from smbc_open() or smbc_creat()
1195 * @param buf Pointer to buffer to recieve read data
1197 * @param bufsize Size of buf in bytes
1199 * @return Number of bytes read, < 0 on error with errno set:
1200 * - EISDIR fd refers to a directory
1201 * - EBADF fd is not a valid file descriptor or
1202 * is not open for reading.
1203 * - EINVAL fd is attached to an object which is
1204 * unsuitable for reading, or no buffer passed or
1205 * smbc_init not called.
1207 * @see smbc_open(), smbc_write()
1210 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1214 * Write to a file using an opened file handle.
1216 * @param fd Open file handle from smbc_open() or smbc_creat()
1218 * @param buf Pointer to buffer to recieve read data
1220 * @param bufsize Size of buf in bytes
1222 * @return Number of bytes written, < 0 on error with errno set:
1223 * - EISDIR fd refers to a directory.
1224 * - EBADF fd is not a valid file descriptor or
1225 * is not open for reading.
1226 * - EINVAL fd is attached to an object which is
1227 * unsuitable for reading, or no buffer passed or
1228 * smbc_init not called.
1230 * @see smbc_open(), smbc_read()
1233 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
1237 * Seek to a specific location in a file.
1239 * @param fd Open file handle from smbc_open() or smbc_creat()
1241 * @param offset Offset in bytes from whence
1243 * @param whence A location in the file:
1244 * - SEEK_SET The offset is set to offset bytes from
1245 * the beginning of the file
1246 * - SEEK_CUR The offset is set to current location
1247 * plus offset bytes.
1248 * - SEEK_END The offset is set to the size of the
1249 * file plus offset bytes.
1251 * @return Upon successful completion, lseek returns the
1252 * resulting offset location as measured in bytes
1253 * from the beginning of the file. Otherwise, a value
1254 * of (off_t)-1 is returned and errno is set to
1255 * indicate the error:
1256 * - EBADF Fildes is not an open file descriptor.
1257 * - EINVAL Whence is not a proper value or smbc_init
1260 * @todo Are all the whence values really supported?
1262 * @todo Are errno values complete and correct?
1264 off_t smbc_lseek(int fd, off_t offset, int whence);
1268 * Close an open file handle.
1270 * @param fd The file handle to close
1272 * @return 0 on success, < 0 on error with errno set:
1273 * - EBADF fd isn't a valid open file descriptor
1274 * - EINVAL smbc_init() failed or has not been called
1276 * @see smbc_open(), smbc_creat()
1278 int smbc_close(int fd);
1281 /**@ingroup directory
1282 * Unlink (delete) a file or directory.
1284 * @param furl The smb url of the file to delete
1286 * @return 0 on success, < 0 on error with errno set:
1287 * - EACCES or EPERM Write access to the directory
1288 * containing pathname is not allowed or one
1289 * of the directories in pathname did not allow
1290 * search (execute) permission
1291 * - ENOENT A directory component in pathname does
1293 * - EINVAL NULL was passed in the file param or
1294 * smbc_init not called.
1295 * - EACCES You do not have access to the file
1296 * - ENOMEM Insufficient kernel memory was available
1298 * @see smbc_rmdir()s
1300 * @todo Are errno values complete and correct?
1302 int smbc_unlink(const char *furl);
1305 /**@ingroup directory
1306 * Rename or move a file or directory.
1308 * @param ourl The original smb url (source url) of file or
1309 * directory to be moved
1311 * @param nurl The new smb url (destination url) of the file
1312 * or directory after the move. Currently nurl must
1313 * be on the same share as ourl.
1315 * @return 0 on success, < 0 on error with errno set:
1316 * - EISDIR nurl is an existing directory, but ourl is
1318 * - EEXIST nurl is a non-empty directory,
1319 * i.e., contains entries other than "." and ".."
1320 * - EINVAL The new url contained a path prefix
1321 * of the old, or, more generally, an attempt was
1322 * made to make a directory a subdirectory of itself
1323 * or smbc_init not called.
1324 * - ENOTDIR A component used as a directory in ourl
1325 * or nurl path is not, in fact, a directory. Or,
1326 * ourl is a directory, and newpath exists but is not
1328 * - EACCES or EPERM Write access to the directory
1329 * containing ourl or nurl is not allowed for the
1330 * process's effective uid, or one of the
1331 * directories in ourl or nurl did not allow search
1332 * (execute) permission, or ourl was a directory
1333 * and did not allow write permission.
1334 * - ENOENT A directory component in ourl or nurl
1336 * - EXDEV Rename across shares not supported.
1337 * - ENOMEM Insufficient kernel memory was available.
1338 * - EEXIST The target file, nurl, already exists.
1341 * @todo Are we going to support copying when urls are not on the same
1342 * share? I say no... NOTE. I agree for the moment.
1345 int smbc_rename(const char *ourl, const char *nurl);
1348 /**@ingroup directory
1349 * Open a directory used to obtain directory entries.
1351 * @param durl The smb url of the directory to open
1353 * @return Valid directory handle. < 0 on error with errno set:
1354 * - EACCES Permission denied.
1355 * - EINVAL A NULL file/URL was passed, or the URL would
1356 * not parse, or was of incorrect form or smbc_init not
1358 * - ENOENT durl does not exist, or name is an
1359 * - ENOMEM Insufficient memory to complete the
1361 * - ENOTDIR name is not a directory.
1362 * - EPERM the workgroup could not be found.
1363 * - ENODEV the workgroup or server could not be found.
1365 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1368 int smbc_opendir(const char *durl);
1371 /**@ingroup directory
1372 * Close a directory handle opened by smbc_opendir().
1374 * @param dh Directory handle to close
1376 * @return 0 on success, < 0 on error with errno set:
1377 * - EBADF dh is an invalid directory handle
1379 * @see smbc_opendir()
1381 int smbc_closedir(int dh);
1384 /**@ingroup directory
1385 * Get multiple directory entries.
1387 * smbc_getdents() reads as many dirent structures from the an open
1388 * directory handle into a specified memory area as will fit.
1390 * @param dh Valid directory as returned by smbc_opendir()
1392 * @param dirp pointer to buffer that will receive the directory
1395 * @param count The size of the dirp buffer in bytes
1397 * @returns If any dirents returned, return will indicate the
1398 * total size. If there were no more dirents available,
1399 * 0 is returned. < 0 indicates an error.
1400 * - EBADF Invalid directory handle
1401 * - EINVAL Result buffer is too small or smbc_init
1403 * - ENOENT No such directory.
1404 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1406 * @todo Are errno values complete and correct?
1408 * @todo Add example code so people know how to parse buffers.
1410 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1413 /**@ingroup directory
1414 * Get a single directory entry.
1416 * @param dh Valid directory as returned by smbc_opendir()
1418 * @return A pointer to a smbc_dirent structure, or NULL if an
1419 * error occurs or end-of-directory is reached:
1420 * - EBADF Invalid directory handle
1421 * - EINVAL smbc_init() failed or has not been called
1423 * @see smbc_dirent, smbc_getdents(), smbc_open()
1425 struct smbc_dirent* smbc_readdir(unsigned int dh);
1428 /**@ingroup directory
1429 * Get the current directory offset.
1431 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1434 * @param dh Valid directory as returned by smbc_opendir()
1436 * @return The current location in the directory stream or -1
1437 * if an error occur. The current location is not
1438 * an offset. Becuase of the implementation, it is a
1439 * handle that allows the library to find the entry
1441 * - EBADF dh is not a valid directory handle
1442 * - EINVAL smbc_init() failed or has not been called
1443 * - ENOTDIR if dh is not a directory
1445 * @see smbc_readdir()
1448 off_t smbc_telldir(int dh);
1451 /**@ingroup directory
1452 * lseek on directories.
1454 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1455 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1457 * @param fd Valid directory as returned by smbc_opendir()
1459 * @param offset The offset (as returned by smbc_telldir). Can be
1460 * NULL, in which case we will rewind
1462 * @return 0 on success, -1 on failure
1463 * - EBADF dh is not a valid directory handle
1464 * - ENOTDIR if dh is not a directory
1465 * - EINVAL offset did not refer to a valid dirent or
1466 * smbc_init not called.
1468 * @see smbc_telldir()
1471 * @todo In what does the reture and errno values mean?
1473 int smbc_lseekdir(int fd, off_t offset);
1475 /**@ingroup directory
1476 * Create a directory.
1478 * @param durl The url of the directory to create
1480 * @param mode Specifies the permissions to use. It is modified
1481 * by the process's umask in the usual way: the
1482 * permissions of the created file are (mode & ~umask).
1484 * @return 0 on success, < 0 on error with errno set:
1485 * - EEXIST directory url already exists
1486 * - EACCES The parent directory does not allow write
1487 * permission to the process, or one of the directories
1488 * - ENOENT A directory component in pathname does not
1490 * - EINVAL NULL durl passed or smbc_init not called.
1491 * - ENOMEM Insufficient memory was available.
1496 int smbc_mkdir(const char *durl, mode_t mode);
1499 /**@ingroup directory
1500 * Remove a directory.
1502 * @param durl The smb url of the directory to remove
1504 * @return 0 on success, < 0 on error with errno set:
1505 * - EACCES or EPERM Write access to the directory
1506 * containing pathname was not allowed.
1507 * - EINVAL durl is NULL or smbc_init not called.
1508 * - ENOENT A directory component in pathname does not
1510 * - ENOTEMPTY directory contains entries.
1511 * - ENOMEM Insufficient kernel memory was available.
1513 * @see smbc_mkdir(), smbc_unlink()
1515 * @todo Are errno values complete and correct?
1517 int smbc_rmdir(const char *durl);
1520 /**@ingroup attribute
1521 * Get information about a file or directory.
1523 * @param url The smb url to get information for
1525 * @param st pointer to a buffer that will be filled with
1526 * standard Unix struct stat information.
1528 * @return 0 on success, < 0 on error with errno set:
1529 * - ENOENT A component of the path file_name does not
1531 * - EINVAL a NULL url was passed or smbc_init not called.
1532 * - EACCES Permission denied.
1533 * - ENOMEM Out of memory
1534 * - ENOTDIR The target dir, url, is not a directory.
1539 int smbc_stat(const char *url, struct stat *st);
1542 /**@ingroup attribute
1543 * Get file information via an file descriptor.
1545 * @param fd Open file handle from smbc_open() or smbc_creat()
1547 * @param st pointer to a buffer that will be filled with
1548 * standard Unix struct stat information.
1550 * @return EBADF filedes is bad.
1551 * - EACCES Permission denied.
1552 * - EBADF fd is not a valid file descriptor
1553 * - EINVAL Problems occurred in the underlying routines
1554 * or smbc_init not called.
1555 * - ENOMEM Out of memory
1557 * @see smbc_stat(), Unix stat()
1560 int smbc_fstat(int fd, struct stat *st);
1563 /**@ingroup attribute
1564 * Truncate a file given a file descriptor
1566 * @param fd Open file handle from smbc_open() or smbc_creat()
1568 * @param size size to truncate the file to
1570 * @return EBADF filedes is bad.
1571 * - EACCES Permission denied.
1572 * - EBADF fd is not a valid file descriptor
1573 * - EINVAL Problems occurred in the underlying routines
1574 * or smbc_init not called.
1575 * - ENOMEM Out of memory
1577 * @see , Unix ftruncate()
1580 int smbc_ftruncate(int fd, off_t size);
1583 /**@ingroup attribute
1584 * Change the permissions of a file.
1586 * @param url The smb url of the file or directory to change
1589 * @param mode The permissions to set:
1590 * - Put good explaination of permissions here!
1592 * @return 0 on success, < 0 on error with errno set:
1593 * - EPERM The effective UID does not match the owner
1594 * of the file, and is not zero
1595 * - ENOENT The file does not exist.
1596 * - ENOMEM Insufficient was available.
1597 * - ENOENT file or directory does not exist
1599 * @todo Actually implement this fuction?
1601 * @todo Are errno values complete and correct?
1603 int smbc_chmod(const char *url, mode_t mode);
1606 * @ingroup attribute
1607 * Change the last modification time on a file
1609 * @param url The smb url of the file or directory to change
1610 * the modification time of
1612 * @param tbuf An array of two timeval structures which contains,
1613 * respectively, the desired access and modification times.
1614 * NOTE: Only the tv_sec field off each timeval structure is
1615 * used. The tv_usec (microseconds) portion is ignored.
1617 * @return 0 on success, < 0 on error with errno set:
1618 * - EINVAL The client library is not properly initialized
1619 * - EPERM Permission was denied.
1622 int smbc_utimes(const char *url, struct timeval *tbuf);
1626 * @ingroup attribute
1627 * Change the last modification time on a file
1629 * @param url The smb url of the file or directory to change
1630 * the modification time of
1632 * @param utbuf A pointer to a utimebuf structure which contains the
1633 * desired access and modification times.
1635 * @return 0 on success, < 0 on error with errno set:
1636 * - EINVAL The client library is not properly initialized
1637 * - ENOMEM No memory was available for internal needs
1638 * - EPERM Permission was denied.
1641 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1644 /**@ingroup attribute
1645 * Set extended attributes for a file. This is used for modifying a file's
1646 * security descriptor (i.e. owner, group, and access control list)
1648 * @param url The smb url of the file or directory to set extended
1651 * @param name The name of an attribute to be changed. Names are of
1652 * one of the following forms:
1654 * system.nt_sec_desc.<attribute name>
1655 * system.nt_sec_desc.*
1656 * system.nt_sec_desc.*+
1658 * where <attribute name> is one of:
1666 * acl+:<name or sid>
1668 * In the forms "system.nt_sec_desc.*" and
1669 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1670 * literal, i.e. the string is provided exactly as shown, and
1671 * the value parameter should contain a complete security
1672 * descriptor with name:value pairs separated by tabs,
1673 * commas, or newlines (not spaces!).
1675 * The plus sign ('+') indicates that SIDs should be mapped
1676 * to names. Without the plus sign, SIDs are not mapped;
1677 * rather they are simply converted to a string format.
1679 * @param value The value to be assigned to the specified attribute name.
1680 * This buffer should contain only the attribute value if the
1681 * name was of the "system.nt_sec_desc.<attribute_name>"
1682 * form. If the name was of the "system.nt_sec_desc.*" form
1683 * then a complete security descriptor, with name:value pairs
1684 * separated by tabs, commas, or newlines (not spaces!),
1685 * should be provided in this value buffer. A complete
1686 * security descriptor will contain one or more entries
1687 * selected from the following:
1689 * REVISION:<revision number>
1690 * OWNER:<sid or name>
1691 * GROUP:<sid or name>
1692 * ACL:<sid or name>:<type>/<flags>/<mask>
1694 * The revision of the ACL specifies the internal Windows NT
1695 * ACL revision for the security descriptor. If not specified
1696 * it defaults to 1. Using values other than 1 may cause
1697 * strange behaviour.
1699 * The owner and group specify the owner and group sids for
1700 * the object. If the attribute name (either '*+' with a
1701 * complete security descriptor, or individual 'owner+' or
1702 * 'group+' attribute names) ended with a plus sign, the
1703 * specified name is resolved to a SID value, using the
1704 * server on which the file or directory resides. Otherwise,
1705 * the value should be provided in SID-printable format as
1706 * S-1-x-y-z, and is used directly. The <sid or name>
1707 * associated with the ACL: attribute should be provided
1710 * @param size The number of the bytes of data in the value buffer
1712 * @param flags A bit-wise OR of zero or more of the following:
1713 * SMBC_XATTR_FLAG_CREATE -
1714 * fail if the named attribute already exists
1715 * SMBC_XATTR_FLAG_REPLACE -
1716 * fail if the attribute does not already exist
1718 * If neither flag is specified, the specified attributes
1719 * will be added or replace existing attributes of the same
1720 * name, as necessary.
1722 * @return 0 on success, < 0 on error with errno set:
1723 * - EINVAL The client library is not properly initialized
1724 * or one of the parameters is not of a correct
1726 * - ENOMEM No memory was available for internal needs
1727 * - EEXIST If the attribute already exists and the flag
1728 * SMBC_XATTR_FLAG_CREAT was specified
1729 * - ENOATTR If the attribute does not exist and the flag
1730 * SMBC_XATTR_FLAG_REPLACE was specified
1731 * - EPERM Permission was denied.
1732 * - ENOTSUP The referenced file system does not support
1733 * extended attributes
1735 * @note Attribute names are compared in a case-insensitive
1736 * fashion. All of the following are equivalent, although
1737 * the all-lower-case name is the preferred format:
1738 * system.nt_sec_desc.owner
1739 * SYSTEM.NT_SEC_DESC.OWNER
1740 * sYsTeM.nt_sEc_desc.owNER
1743 int smbc_setxattr(const char *url,
1750 /**@ingroup attribute
1751 * Set extended attributes for a file. This is used for modifying a file's
1752 * security descriptor (i.e. owner, group, and access control list). The
1753 * POSIX function which this maps to would act on a symbolic link rather than
1754 * acting on what the symbolic link points to, but with no symbolic links in
1755 * SMB file systems, this function is functionally identical to
1758 * @param url The smb url of the file or directory to set extended
1761 * @param name The name of an attribute to be changed. Names are of
1762 * one of the following forms:
1764 * system.nt_sec_desc.<attribute name>
1765 * system.nt_sec_desc.*
1766 * system.nt_sec_desc.*+
1768 * where <attribute name> is one of:
1776 * acl+:<name or sid>
1778 * In the forms "system.nt_sec_desc.*" and
1779 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1780 * literal, i.e. the string is provided exactly as shown, and
1781 * the value parameter should contain a complete security
1782 * descriptor with name:value pairs separated by tabs,
1783 * commas, or newlines (not spaces!).
1785 * The plus sign ('+') indicates that SIDs should be mapped
1786 * to names. Without the plus sign, SIDs are not mapped;
1787 * rather they are simply converted to a string format.
1789 * @param value The value to be assigned to the specified attribute name.
1790 * This buffer should contain only the attribute value if the
1791 * name was of the "system.nt_sec_desc.<attribute_name>"
1792 * form. If the name was of the "system.nt_sec_desc.*" form
1793 * then a complete security descriptor, with name:value pairs
1794 * separated by tabs, commas, or newlines (not spaces!),
1795 * should be provided in this value buffer. A complete
1796 * security descriptor will contain one or more entries
1797 * selected from the following:
1799 * REVISION:<revision number>
1800 * OWNER:<sid or name>
1801 * GROUP:<sid or name>
1802 * ACL:<sid or name>:<type>/<flags>/<mask>
1804 * The revision of the ACL specifies the internal Windows NT
1805 * ACL revision for the security descriptor. If not specified
1806 * it defaults to 1. Using values other than 1 may cause
1807 * strange behaviour.
1809 * The owner and group specify the owner and group sids for
1810 * the object. If the attribute name (either '*+' with a
1811 * complete security descriptor, or individual 'owner+' or
1812 * 'group+' attribute names) ended with a plus sign, the
1813 * specified name is resolved to a SID value, using the
1814 * server on which the file or directory resides. Otherwise,
1815 * the value should be provided in SID-printable format as
1816 * S-1-x-y-z, and is used directly. The <sid or name>
1817 * associated with the ACL: attribute should be provided
1820 * @param size The number of the bytes of data in the value buffer
1822 * @param flags A bit-wise OR of zero or more of the following:
1823 * SMBC_XATTR_FLAG_CREATE -
1824 * fail if the named attribute already exists
1825 * SMBC_XATTR_FLAG_REPLACE -
1826 * fail if the attribute does not already exist
1828 * If neither flag is specified, the specified attributes
1829 * will be added or replace existing attributes of the same
1830 * name, as necessary.
1832 * @return 0 on success, < 0 on error with errno set:
1833 * - EINVAL The client library is not properly initialized
1834 * or one of the parameters is not of a correct
1836 * - ENOMEM No memory was available for internal needs
1837 * - EEXIST If the attribute already exists and the flag
1838 * SMBC_XATTR_FLAG_CREAT was specified
1839 * - ENOATTR If the attribute does not exist and the flag
1840 * SMBC_XATTR_FLAG_REPLACE was specified
1841 * - EPERM Permission was denied.
1842 * - ENOTSUP The referenced file system does not support
1843 * extended attributes
1845 * @note Attribute names are compared in a case-insensitive
1846 * fashion. All of the following are equivalent, although
1847 * the all-lower-case name is the preferred format:
1848 * system.nt_sec_desc.owner
1849 * SYSTEM.NT_SEC_DESC.OWNER
1850 * sYsTeM.nt_sEc_desc.owNER
1853 int smbc_lsetxattr(const char *url,
1860 /**@ingroup attribute
1861 * Set extended attributes for a file. This is used for modifying a file's
1862 * security descriptor (i.e. owner, group, and access control list)
1864 * @param fd A file descriptor associated with an open file (as
1865 * previously returned by smbc_open(), to get extended
1868 * @param name The name of an attribute to be changed. Names are of
1869 * one of the following forms:
1871 * system.nt_sec_desc.<attribute name>
1872 * system.nt_sec_desc.*
1873 * system.nt_sec_desc.*+
1875 * where <attribute name> is one of:
1883 * acl+:<name or sid>
1885 * In the forms "system.nt_sec_desc.*" and
1886 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1887 * literal, i.e. the string is provided exactly as shown, and
1888 * the value parameter should contain a complete security
1889 * descriptor with name:value pairs separated by tabs,
1890 * commas, or newlines (not spaces!).
1892 * The plus sign ('+') indicates that SIDs should be mapped
1893 * to names. Without the plus sign, SIDs are not mapped;
1894 * rather they are simply converted to a string format.
1896 * @param value The value to be assigned to the specified attribute name.
1897 * This buffer should contain only the attribute value if the
1898 * name was of the "system.nt_sec_desc.<attribute_name>"
1899 * form. If the name was of the "system.nt_sec_desc.*" form
1900 * then a complete security descriptor, with name:value pairs
1901 * separated by tabs, commas, or newlines (not spaces!),
1902 * should be provided in this value buffer. A complete
1903 * security descriptor will contain one or more entries
1904 * selected from the following:
1906 * REVISION:<revision number>
1907 * OWNER:<sid or name>
1908 * GROUP:<sid or name>
1909 * ACL:<sid or name>:<type>/<flags>/<mask>
1911 * The revision of the ACL specifies the internal Windows NT
1912 * ACL revision for the security descriptor. If not specified
1913 * it defaults to 1. Using values other than 1 may cause
1914 * strange behaviour.
1916 * The owner and group specify the owner and group sids for
1917 * the object. If the attribute name (either '*+' with a
1918 * complete security descriptor, or individual 'owner+' or
1919 * 'group+' attribute names) ended with a plus sign, the
1920 * specified name is resolved to a SID value, using the
1921 * server on which the file or directory resides. Otherwise,
1922 * the value should be provided in SID-printable format as
1923 * S-1-x-y-z, and is used directly. The <sid or name>
1924 * associated with the ACL: attribute should be provided
1927 * @param size The number of the bytes of data in the value buffer
1929 * @param flags A bit-wise OR of zero or more of the following:
1930 * SMBC_XATTR_FLAG_CREATE -
1931 * fail if the named attribute already exists
1932 * SMBC_XATTR_FLAG_REPLACE -
1933 * fail if the attribute does not already exist
1935 * If neither flag is specified, the specified attributes
1936 * will be added or replace existing attributes of the same
1937 * name, as necessary.
1939 * @return 0 on success, < 0 on error with errno set:
1940 * - EINVAL The client library is not properly initialized
1941 * or one of the parameters is not of a correct
1943 * - ENOMEM No memory was available for internal needs
1944 * - EEXIST If the attribute already exists and the flag
1945 * SMBC_XATTR_FLAG_CREAT was specified
1946 * - ENOATTR If the attribute does not exist and the flag
1947 * SMBC_XATTR_FLAG_REPLACE was specified
1948 * - EPERM Permission was denied.
1949 * - ENOTSUP The referenced file system does not support
1950 * extended attributes
1952 * @note Attribute names are compared in a case-insensitive
1953 * fashion. All of the following are equivalent, although
1954 * the all-lower-case name is the preferred format:
1955 * system.nt_sec_desc.owner
1956 * SYSTEM.NT_SEC_DESC.OWNER
1957 * sYsTeM.nt_sEc_desc.owNER
1960 int smbc_fsetxattr(int fd,
1967 /**@ingroup attribute
1968 * Get extended attributes for a file.
1970 * @param url The smb url of the file or directory to get extended
1973 * @param name The name of an attribute to be retrieved. Names are of
1974 * one of the following forms:
1976 * system.nt_sec_desc.<attribute name>
1977 * system.nt_sec_desc.*
1978 * system.nt_sec_desc.*+
1980 * where <attribute name> is one of:
1988 * acl+:<name or sid>
1990 * In the forms "system.nt_sec_desc.*" and
1991 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1992 * literal, i.e. the string is provided exactly as shown, and
1993 * the value parameter will return a complete security
1994 * descriptor with name:value pairs separated by tabs,
1995 * commas, or newlines (not spaces!).
1997 * The plus sign ('+') indicates that SIDs should be mapped
1998 * to names. Without the plus sign, SIDs are not mapped;
1999 * rather they are simply converted to a string format.
2001 * @param value A pointer to a buffer in which the value of the specified
2002 * attribute will be placed (unless size is zero).
2004 * @param size The size of the buffer pointed to by value. This parameter
2005 * may also be zero, in which case the size of the buffer
2006 * required to hold the attribute value will be returned,
2007 * but nothing will be placed into the value buffer.
2009 * @return 0 on success, < 0 on error with errno set:
2010 * - EINVAL The client library is not properly initialized
2011 * or one of the parameters is not of a correct
2013 * - ENOMEM No memory was available for internal needs
2014 * - EEXIST If the attribute already exists and the flag
2015 * SMBC_XATTR_FLAG_CREAT was specified
2016 * - ENOATTR If the attribute does not exist and the flag
2017 * SMBC_XATTR_FLAG_REPLACE was specified
2018 * - EPERM Permission was denied.
2019 * - ENOTSUP The referenced file system does not support
2020 * extended attributes
2023 int smbc_getxattr(const char *url,
2029 /**@ingroup attribute
2030 * Get extended attributes for a file. The POSIX function which this maps to
2031 * would act on a symbolic link rather than acting on what the symbolic link
2032 * points to, but with no symbolic links in SMB file systems, this function
2033 * is functionally identical to smbc_getxattr().
2035 * @param url The smb url of the file or directory to get extended
2038 * @param name The name of an attribute to be retrieved. Names are of
2039 * one of the following forms:
2041 * system.nt_sec_desc.<attribute name>
2042 * system.nt_sec_desc.*
2043 * system.nt_sec_desc.*+
2045 * where <attribute name> is one of:
2053 * acl+:<name or sid>
2055 * In the forms "system.nt_sec_desc.*" and
2056 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2057 * literal, i.e. the string is provided exactly as shown, and
2058 * the value parameter will return a complete security
2059 * descriptor with name:value pairs separated by tabs,
2060 * commas, or newlines (not spaces!).
2062 * The plus sign ('+') indicates that SIDs should be mapped
2063 * to names. Without the plus sign, SIDs are not mapped;
2064 * rather they are simply converted to a string format.
2066 * @param value A pointer to a buffer in which the value of the specified
2067 * attribute will be placed (unless size is zero).
2069 * @param size The size of the buffer pointed to by value. This parameter
2070 * may also be zero, in which case the size of the buffer
2071 * required to hold the attribute value will be returned,
2072 * but nothing will be placed into the value buffer.
2074 * @return 0 on success, < 0 on error with errno set:
2075 * - EINVAL The client library is not properly initialized
2076 * or one of the parameters is not of a correct
2078 * - ENOMEM No memory was available for internal needs
2079 * - EEXIST If the attribute already exists and the flag
2080 * SMBC_XATTR_FLAG_CREAT was specified
2081 * - ENOATTR If the attribute does not exist and the flag
2082 * SMBC_XATTR_FLAG_REPLACE was specified
2083 * - EPERM Permission was denied.
2084 * - ENOTSUP The referenced file system does not support
2085 * extended attributes
2088 int smbc_lgetxattr(const char *url,
2094 /**@ingroup attribute
2095 * Get extended attributes for a file.
2097 * @param fd A file descriptor associated with an open file (as
2098 * previously returned by smbc_open(), to get extended
2101 * @param name The name of an attribute to be retrieved. Names are of
2102 * one of the following forms:
2104 * system.nt_sec_desc.<attribute name>
2105 * system.nt_sec_desc.*
2106 * system.nt_sec_desc.*+
2108 * where <attribute name> is one of:
2116 * acl+:<name or sid>
2118 * In the forms "system.nt_sec_desc.*" and
2119 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2120 * literal, i.e. the string is provided exactly as shown, and
2121 * the value parameter will return a complete security
2122 * descriptor with name:value pairs separated by tabs,
2123 * commas, or newlines (not spaces!).
2125 * The plus sign ('+') indicates that SIDs should be mapped
2126 * to names. Without the plus sign, SIDs are not mapped;
2127 * rather they are simply converted to a string format.
2129 * @param value A pointer to a buffer in which the value of the specified
2130 * attribute will be placed (unless size is zero).
2132 * @param size The size of the buffer pointed to by value. This parameter
2133 * may also be zero, in which case the size of the buffer
2134 * required to hold the attribute value will be returned,
2135 * but nothing will be placed into the value buffer.
2137 * @return 0 on success, < 0 on error with errno set:
2138 * - EINVAL The client library is not properly initialized
2139 * or one of the parameters is not of a correct
2141 * - ENOMEM No memory was available for internal needs
2142 * - EEXIST If the attribute already exists and the flag
2143 * SMBC_XATTR_FLAG_CREAT was specified
2144 * - ENOATTR If the attribute does not exist and the flag
2145 * SMBC_XATTR_FLAG_REPLACE was specified
2146 * - EPERM Permission was denied.
2147 * - ENOTSUP The referenced file system does not support
2148 * extended attributes
2151 int smbc_fgetxattr(int fd,
2157 /**@ingroup attribute
2158 * Remove extended attributes for a file. This is used for modifying a file's
2159 * security descriptor (i.e. owner, group, and access control list)
2161 * @param url The smb url of the file or directory to remove the extended
2164 * @param name The name of an attribute to be removed. Names are of
2165 * one of the following forms:
2167 * system.nt_sec_desc.<attribute name>
2168 * system.nt_sec_desc.*
2169 * system.nt_sec_desc.*+
2171 * where <attribute name> is one of:
2179 * acl+:<name or sid>
2181 * In the forms "system.nt_sec_desc.*" and
2182 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2183 * literal, i.e. the string is provided exactly as shown, and
2184 * the value parameter will return a complete security
2185 * descriptor with name:value pairs separated by tabs,
2186 * commas, or newlines (not spaces!).
2188 * The plus sign ('+') indicates that SIDs should be mapped
2189 * to names. Without the plus sign, SIDs are not mapped;
2190 * rather they are simply converted to a string format.
2192 * @return 0 on success, < 0 on error with errno set:
2193 * - EINVAL The client library is not properly initialized
2194 * - ENOMEM No memory was available for internal needs
2195 * - EPERM Permission was denied.
2196 * - ENOTSUP The referenced file system does not support
2197 * extended attributes
2200 int smbc_removexattr(const char *url,
2204 /**@ingroup attribute
2205 * Remove extended attributes for a file. This is used for modifying a file's
2206 * security descriptor (i.e. owner, group, and access control list) The POSIX
2207 * function which this maps to would act on a symbolic link rather than acting
2208 * on what the symbolic link points to, but with no symbolic links in SMB file
2209 * systems, this function is functionally identical to smbc_removexattr().
2211 * @param url The smb url of the file or directory to remove the extended
2214 * @param name The name of an attribute to be removed. Names are of
2215 * one of the following forms:
2217 * system.nt_sec_desc.<attribute name>
2218 * system.nt_sec_desc.*
2219 * system.nt_sec_desc.*+
2221 * where <attribute name> is one of:
2229 * acl+:<name or sid>
2231 * In the forms "system.nt_sec_desc.*" and
2232 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2233 * literal, i.e. the string is provided exactly as shown, and
2234 * the value parameter will return a complete security
2235 * descriptor with name:value pairs separated by tabs,
2236 * commas, or newlines (not spaces!).
2238 * The plus sign ('+') indicates that SIDs should be mapped
2239 * to names. Without the plus sign, SIDs are not mapped;
2240 * rather they are simply converted to a string format.
2242 * @return 0 on success, < 0 on error with errno set:
2243 * - EINVAL The client library is not properly initialized
2244 * - ENOMEM No memory was available for internal needs
2245 * - EPERM Permission was denied.
2246 * - ENOTSUP The referenced file system does not support
2247 * extended attributes
2250 int smbc_lremovexattr(const char *url,
2254 /**@ingroup attribute
2255 * Remove extended attributes for a file. This is used for modifying a file's
2256 * security descriptor (i.e. owner, group, and access control list)
2258 * @param fd A file descriptor associated with an open file (as
2259 * previously returned by smbc_open(), to get extended
2262 * @param name The name of an attribute to be removed. Names are of
2263 * one of the following forms:
2265 * system.nt_sec_desc.<attribute name>
2266 * system.nt_sec_desc.*
2267 * system.nt_sec_desc.*+
2269 * where <attribute name> is one of:
2277 * acl+:<name or sid>
2279 * In the forms "system.nt_sec_desc.*" and
2280 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2281 * literal, i.e. the string is provided exactly as shown, and
2282 * the value parameter will return a complete security
2283 * descriptor with name:value pairs separated by tabs,
2284 * commas, or newlines (not spaces!).
2286 * The plus sign ('+') indicates that SIDs should be mapped
2287 * to names. Without the plus sign, SIDs are not mapped;
2288 * rather they are simply converted to a string format.
2290 * @return 0 on success, < 0 on error with errno set:
2291 * - EINVAL The client library is not properly initialized
2292 * - ENOMEM No memory was available for internal needs
2293 * - EPERM Permission was denied.
2294 * - ENOTSUP The referenced file system does not support
2295 * extended attributes
2298 int smbc_fremovexattr(int fd,
2302 /**@ingroup attribute
2303 * List the supported extended attribute names associated with a file
2305 * @param url The smb url of the file or directory to list the extended
2308 * @param list A pointer to a buffer in which the list of attributes for
2309 * the specified file or directory will be placed (unless
2312 * @param size The size of the buffer pointed to by list. This parameter
2313 * may also be zero, in which case the size of the buffer
2314 * required to hold all of the attribute names will be
2315 * returned, but nothing will be placed into the list buffer.
2317 * @return 0 on success, < 0 on error with errno set:
2318 * - EINVAL The client library is not properly initialized
2319 * - ENOMEM No memory was available for internal needs
2320 * - EPERM Permission was denied.
2321 * - ENOTSUP The referenced file system does not support
2322 * extended attributes
2324 * @note This function always returns all attribute names supported
2325 * by NT file systems, regardless of whether the referenced
2326 * file system supports extended attributes (e.g. a Windows
2327 * 2000 machine supports extended attributes if NTFS is used,
2328 * but not if FAT is used, and Windows 98 doesn't support
2329 * extended attributes at all. Whether this is a feature or
2330 * a bug is yet to be decided.
2332 int smbc_listxattr(const char *url,
2336 /**@ingroup attribute
2337 * List the supported extended attribute names associated with a file The
2338 * POSIX function which this maps to would act on a symbolic link rather than
2339 * acting on what the symbolic link points to, but with no symbolic links in
2340 * SMB file systems, this function is functionally identical to
2343 * @param url The smb url of the file or directory to list the extended
2346 * @param list A pointer to a buffer in which the list of attributes for
2347 * the specified file or directory will be placed (unless
2350 * @param size The size of the buffer pointed to by list. This parameter
2351 * may also be zero, in which case the size of the buffer
2352 * required to hold all of the attribute names will be
2353 * returned, but nothing will be placed into the list buffer.
2355 * @return 0 on success, < 0 on error with errno set:
2356 * - EINVAL The client library is not properly initialized
2357 * - ENOMEM No memory was available for internal needs
2358 * - EPERM Permission was denied.
2359 * - ENOTSUP The referenced file system does not support
2360 * extended attributes
2362 * @note This function always returns all attribute names supported
2363 * by NT file systems, regardless of wether the referenced
2364 * file system supports extended attributes (e.g. a Windows
2365 * 2000 machine supports extended attributes if NTFS is used,
2366 * but not if FAT is used, and Windows 98 doesn't support
2367 * extended attributes at all. Whether this is a feature or
2368 * a bug is yet to be decided.
2370 int smbc_llistxattr(const char *url,
2374 /**@ingroup attribute
2375 * List the supported extended attribute names associated with a file
2377 * @param fd A file descriptor associated with an open file (as
2378 * previously returned by smbc_open(), to get extended
2381 * @param list A pointer to a buffer in which the list of attributes for
2382 * the specified file or directory will be placed (unless
2385 * @param size The size of the buffer pointed to by list. This parameter
2386 * may also be zero, in which case the size of the buffer
2387 * required to hold all of the attribute names will be
2388 * returned, but nothing will be placed into the list buffer.
2390 * @return 0 on success, < 0 on error with errno set:
2391 * - EINVAL The client library is not properly initialized
2392 * - ENOMEM No memory was available for internal needs
2393 * - EPERM Permission was denied.
2394 * - ENOTSUP The referenced file system does not support
2395 * extended attributes
2397 * @note This function always returns all attribute names supported
2398 * by NT file systems, regardless of wether the referenced
2399 * file system supports extended attributes (e.g. a Windows
2400 * 2000 machine supports extended attributes if NTFS is used,
2401 * but not if FAT is used, and Windows 98 doesn't support
2402 * extended attributes at all. Whether this is a feature or
2403 * a bug is yet to be decided.
2405 int smbc_flistxattr(int fd,
2410 * Print a file given the name in fname. It would be a URL ...
2412 * @param fname The URL of a file on a remote SMB server that the
2413 * caller wants printed
2415 * @param printq The URL of the print share to print the file to.
2417 * @return 0 on success, < 0 on error with errno set:
2419 * - EINVAL fname or printq was NULL or smbc_init not
2421 * and errors returned by smbc_open
2424 int smbc_print_file(const char *fname, const char *printq);
2427 * Open a print file that can be written to by other calls. This simply
2428 * does an smbc_open call after checking if there is a file name on the
2429 * URI. If not, a temporary name is added ...
2431 * @param fname The URL of the print share to print to?
2433 * @returns A file handle for the print file if successful.
2434 * Returns -1 if an error ocurred and errno has the values
2435 * - EINVAL fname was NULL or smbc_init not called.
2436 * - all errors returned by smbc_open
2439 int smbc_open_print_job(const char *fname);
2442 * List the print jobs on a print share, for the moment, pass a callback
2444 * @param purl The url of the print share to list the jobs of
2446 * @param fn Callback function the receives printjob info
2448 * @return 0 on success, < 0 on error with errno set:
2449 * - EINVAL fname was NULL or smbc_init not called
2452 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2455 * Delete a print job
2457 * @param purl Url of the print share
2459 * @param id The id of the job to delete
2461 * @return 0 on success, < 0 on error with errno set:
2462 * - EINVAL fname was NULL or smbc_init not called
2464 * @todo what errno values are possible here?
2466 int smbc_unlink_print_job(const char *purl, int id);
2468 /**@ingroup callback
2469 * Remove a server from the cached server list it's unused.
2471 * @param context pointer to smb context
2473 * @param srv pointer to server to remove
2475 * @return On success, 0 is returned. 1 is returned if the server could not
2476 * be removed. Also useable outside libsmbclient.
2478 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2484 /**@ingroup directory
2485 * Convert strings of %xx to their single character equivalent.
2487 * @param dest A pointer to a buffer in which the resulting decoded
2488 * string should be placed. This may be a pointer to the
2489 * same buffer as src_segment.
2491 * @param src A pointer to the buffer containing the URL to be decoded.
2492 * Any %xx sequences herein are converted to their single
2493 * character equivalent. Each 'x' must be a valid hexadecimal
2494 * digit, or that % sequence is left undecoded.
2496 * @param max_dest_len
2497 * The size of the buffer pointed to by dest_segment.
2499 * @return The number of % sequences which could not be converted
2500 * due to lack of two following hexadecimal digits.
2506 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2513 * Convert any characters not specifically allowed in a URL into their %xx
2516 * @param dest A pointer to a buffer in which the resulting encoded
2517 * string should be placed. Unlike smbc_urldecode(), this
2518 * must be a buffer unique from src.
2520 * @param src A pointer to the buffer containing the string to be encoded.
2521 * Any character not specifically allowed in a URL is converted
2522 * into its hexadecimal value and encoded as %xx.
2524 * @param max_dest_len
2525 * The size of the buffer pointed to by dest_segment.
2527 * @returns The remaining buffer length.
2533 smbc_urlencode(char * dest, char * src, int max_dest_len);
2539 /**@ingroup directory
2540 * Return the version of the linked Samba code, and thus the version of the
2541 * libsmbclient code.
2543 * @return The version string.
2555 * @ingroup structure
2556 * Structure that contains a client context information
2557 * This structure is known as SMBCCTX
2559 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
2560 * structure should all be considered private to the library. It remains here
2561 * only for backward compatibility.
2563 * See the comments herein for use of the setter and getter functions which
2564 * should now be used for manipulating these values. New features, functions,
2565 * etc., are not added here but rather in _internal where they are not
2566 * directly visible to applications. This makes it much easier to maintain
2567 * ABI compatibility.
2575 * Use smbc_getDebug() and smbc_setDebug()
2577 int debug DEPRECATED_SMBC_INTERFACE;
2580 * netbios name used for making connections
2583 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2585 char * netbios_name DEPRECATED_SMBC_INTERFACE;
2588 * workgroup name used for making connections
2591 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2593 char * workgroup DEPRECATED_SMBC_INTERFACE;
2596 * username used for making connections
2599 * Use smbc_getUser() and smbc_setUser()
2601 char * user DEPRECATED_SMBC_INTERFACE;
2604 * timeout used for waiting on connections / response data (in
2608 * Use smbc_getTimeout() and smbc_setTimeout()
2610 int timeout DEPRECATED_SMBC_INTERFACE;
2613 * callable functions for files:
2614 * For usage and return values see the SMBC_* functions
2618 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2619 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2621 smbc_open_fn open DEPRECATED_SMBC_INTERFACE;
2622 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE;
2623 smbc_read_fn read DEPRECATED_SMBC_INTERFACE;
2624 smbc_write_fn write DEPRECATED_SMBC_INTERFACE;
2625 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE;
2626 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE;
2627 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE;
2628 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE;
2629 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE;
2630 #if 0 /* internal */
2631 smbc_ftruncate_fn ftruncate_fn;
2633 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE;
2634 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
2635 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
2636 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
2637 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE;
2638 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE;
2639 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE;
2640 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE;
2641 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE;
2642 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE;
2643 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE;
2644 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE;
2645 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE;
2646 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE;
2647 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE;
2648 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE;
2650 /* Printing-related functions */
2651 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE;
2652 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE;
2653 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE;
2654 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE;
2661 * See the comment above each field, for the getter and setter
2662 * functions that should now be used.
2664 struct _smbc_callbacks
2667 * authentication function callback: called upon auth requests
2670 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2672 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
2675 * check if a server is still good
2678 * Use smbc_getFunctionCheckServer(),
2679 * smbc_setFunctionCheckServer()
2681 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
2684 * remove a server if unused
2687 * Use smbc_getFunctionRemoveUnusedServer(),
2688 * smbc_setFunctionCheckServer()
2690 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
2694 * For an example cache system see
2695 * samba/source/libsmb/libsmb_cache.c
2697 * Cache subsystem * functions follow.
2701 * server cache addition
2704 * Use smbc_getFunctionAddCachedServer(),
2705 * smbc_setFunctionAddCachedServer()
2707 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2710 * server cache lookup
2713 * Use smbc_getFunctionGetCachedServer(),
2714 * smbc_setFunctionGetCachedServer()
2716 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2719 * server cache removal
2722 * Use smbc_getFunctionRemoveCachedServer(),
2723 * smbc_setFunctionRemoveCachedServer()
2725 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2728 * server cache purging, try to remove all cached servers
2732 * Use smbc_getFunctionPurgeCachedServers(),
2733 * smbc_setFunctionPurgeCachedServers()
2735 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
2739 * Space where the private data of the server cache used to be
2742 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
2744 void * reserved DEPRECATED_SMBC_INTERFACE;
2747 * Very old configuration options.
2750 * Use one of the following functions instead:
2751 * smbc_setOptionUseKerberos()
2752 * smbc_getOptionUseKerberos()
2753 * smbc_setOptionFallbackAfterKerberos()
2754 * smbc_getOptionFallbackAfterKerberos()
2755 * smbc_setOptionNoAutoAnonymousLogin()
2756 * smbc_getOptionNoAutoAnonymousLogin()
2758 int flags DEPRECATED_SMBC_INTERFACE;
2761 * user options selections that apply to this session
2763 * NEW OPTIONS ARE NOT ADDED HERE!
2766 * To set and retrieve options, use the smbc_setOption*() and
2767 * smbc_getOption*() functions.
2769 struct _smbc_options {
2770 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
2771 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
2772 int one_share_per_server DEPRECATED_SMBC_INTERFACE;
2773 } options DEPRECATED_SMBC_INTERFACE;
2776 * do _NOT_ touch this from your program !
2778 struct SMBC_internal_data * internal;
2782 #endif /* SMBCLIENT_H_INCLUDED */