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
;
178 * Capabilities set in the f_flag field of struct statvfs, from
179 * smbc_statvfs(). These may be OR-ed together to reflect a full set of
180 * available capabilities.
182 typedef enum smbc_vfs_capability
184 /* Defined by POSIX or in Linux include files (low-order bits) */
185 SMBC_VFS_CAP_RDONLY
= (1 << 0),
187 /* Specific to libsmbclient (high-order bits) */
188 SMBC_VFS_CAP_DFS
= (1 << 29),
189 SMBC_VFS_CAP_CASE_SENSITIVE
= (1 << 30),
190 SMBC_VFS_CAP_UNIXCIFS
= (1 << 31)
191 } smbc_vfs_capability
;
193 typedef int smbc_bool
;
197 # define ENOATTR ENOENT /* No such attribute */
203 /**@ingroup structure
204 * Structure that represents a print job.
208 struct print_job_info
210 /** numeric ID of the print job
214 /** represents print job priority (lower numbers mean higher priority)
216 unsigned short priority
;
218 /** Size of the print job
222 /** Name of the user that owns the print job
226 /** Name of the print job. This will have no name if an anonymous print
227 * file was opened. Ie smb://server/printer
231 /** Time the print job was spooled
235 #endif /* _CLIENT_H */
238 /**@ingroup structure
241 typedef struct _SMBCSRV SMBCSRV
;
243 /**@ingroup structure
244 * File or directory handle
246 typedef struct _SMBCFILE SMBCFILE
;
248 /**@ingroup structure
249 * File or directory handle
251 typedef struct _SMBCCTX SMBCCTX
;
255 * Flags for SMBCCTX->flags
257 * NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
259 * smbc_setOptionUseKerberos()
260 * smbc_getOptionUseKerberos()
261 * smbc_setOptionFallbackAfterKerberos()
262 * smbc_getOptionFallbackAFterKerberos()
263 * smbc_setOptionNoAutoAnonymousLogin()
264 * smbc_getOptionNoAutoAnonymousLogin()
266 # define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
267 # define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
268 # define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
273 * Authentication callback function type (traditional method)
275 * Type for the the authentication function called by the library to
276 * obtain authentication credentals
278 * For kerberos support the function should just be called without
279 * prompting the user for credentials. Which means a simple 'return'
280 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
281 * and examples/libsmbclient/testbrowse.c.
283 * @param srv Server being authenticated to
285 * @param shr Share being authenticated to
287 * @param wg Pointer to buffer containing a "hint" for the
288 * workgroup to be authenticated. Should be filled in
289 * with the correct workgroup if the hint is wrong.
291 * @param wglen The size of the workgroup buffer in bytes
293 * @param un Pointer to buffer containing a "hint" for the
294 * user name to be use for authentication. Should be
295 * filled in with the correct workgroup if the hint is
298 * @param unlen The size of the username buffer in bytes
300 * @param pw Pointer to buffer containing to which password
303 * @param pwlen The size of the password buffer in bytes
306 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
310 char *pw
, int pwlen
);
312 * Authentication callback function type (method that includes context)
314 * Type for the the authentication function called by the library to
315 * obtain authentication credentals
317 * For kerberos support the function should just be called without
318 * prompting the user for credentials. Which means a simple 'return'
319 * should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
320 * and examples/libsmbclient/testbrowse.c.
322 * @param c Pointer to the smb context
324 * @param srv Server being authenticated to
326 * @param shr Share being authenticated to
328 * @param wg Pointer to buffer containing a "hint" for the
329 * workgroup to be authenticated. Should be filled in
330 * with the correct workgroup if the hint is wrong.
332 * @param wglen The size of the workgroup buffer in bytes
334 * @param un Pointer to buffer containing a "hint" for the
335 * user name to be use for authentication. Should be
336 * filled in with the correct workgroup if the hint is
339 * @param unlen The size of the username buffer in bytes
341 * @param pw Pointer to buffer containing to which password
344 * @param pwlen The size of the password buffer in bytes
347 typedef void (*smbc_get_auth_data_with_context_fn
)(SMBCCTX
*c
,
352 char *pw
, int pwlen
);
356 * Print job info callback function type.
358 * @param i pointer to print job information structure
361 typedef void (*smbc_list_print_job_fn
)(struct print_job_info
*i
);
365 * Check if a server is still good
367 * @param c pointer to smb context
369 * @param srv pointer to server to check
371 * @return 0 when connection is good. 1 on error.
374 typedef int (*smbc_check_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
377 * Remove a server if unused
379 * @param c pointer to smb context
381 * @param srv pointer to server to remove
383 * @return 0 on success. 1 on failure.
386 typedef int (*smbc_remove_unused_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
390 * Add a server to the cache system
392 * @param c pointer to smb context
394 * @param srv pointer to server to add
396 * @param server server name
398 * @param share share name
400 * @param workgroup workgroup used to connect
402 * @param username username used to connect
404 * @return 0 on success. 1 on failure.
407 typedef int (*smbc_add_cached_srv_fn
) (SMBCCTX
* c
, SMBCSRV
*srv
,
408 const char * server
, const char * share
,
409 const char * workgroup
, const char * username
);
412 * Look up a server in the cache system
414 * @param c pointer to smb context
416 * @param server server name to match
418 * @param share share name to match
420 * @param workgroup workgroup to match
422 * @param username username to match
424 * @return pointer to SMBCSRV on success. NULL on failure.
427 typedef SMBCSRV
* (*smbc_get_cached_srv_fn
) (SMBCCTX
* c
, const char * server
,
428 const char * share
, const char * workgroup
,
429 const char * username
);
432 * Check if a server is still good
434 * @param c pointer to smb context
436 * @param srv pointer to server to remove
438 * @return 0 when found and removed. 1 on failure.
441 typedef int (*smbc_remove_cached_srv_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
445 * Try to remove all servers from the cache system and disconnect
447 * @param c pointer to smb context
449 * @return 0 when found and removed. 1 on failure.
452 typedef int (*smbc_purge_cached_fn
) (SMBCCTX
* c
);
456 /*****************************************
457 * Getters and setters for CONFIGURATION *
458 *****************************************/
460 /** Get the debug level */
462 smbc_getDebug(SMBCCTX
*c
);
464 /** Set the debug level */
466 smbc_setDebug(SMBCCTX
*c
, int debug
);
468 /** Get the netbios name used for making connections */
470 smbc_getNetbiosName(SMBCCTX
*c
);
472 /** Set the netbios name used for making connections */
474 smbc_setNetbiosName(SMBCCTX
*c
, char * netbios_name
);
476 /** Get the workgroup used for making connections */
478 smbc_getWorkgroup(SMBCCTX
*c
);
480 /** Set the workgroup used for making connections */
481 void smbc_setWorkgroup(SMBCCTX
*c
, char * workgroup
);
483 /** Get the username used for making connections */
485 smbc_getUser(SMBCCTX
*c
);
487 /** Set the username used for making connections */
489 smbc_setUser(SMBCCTX
*c
, char * user
);
492 * Get the timeout used for waiting on connections and response data
496 smbc_getTimeout(SMBCCTX
*c
);
499 * Set the timeout used for waiting on connections and response data
503 smbc_setTimeout(SMBCCTX
*c
, int timeout
);
507 /***********************************
508 * Getters and setters for OPTIONS *
509 ***********************************/
511 /** Get whether to log to standard error instead of standard output */
513 smbc_getOptionDebugToStderr(SMBCCTX
*c
);
515 /** Set whether to log to standard error instead of standard output */
517 smbc_setOptionDebugToStderr(SMBCCTX
*c
, smbc_bool b
);
520 * Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
521 * than the old-style names such as M_TIME. This allows also setting/getting
522 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
523 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
527 smbc_getOptionFullTimeNames(SMBCCTX
*c
);
530 * Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
531 * than the old-style names such as M_TIME. This allows also setting/getting
532 * CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
533 * was supposed to be CHANGE_TIME but was confused and sometimes referred to
537 smbc_setOptionFullTimeNames(SMBCCTX
*c
, smbc_bool b
);
540 * Get the share mode to use for files opened with SMBC_open_ctx(). The
541 * default is SMBC_SHAREMODE_DENY_NONE.
544 smbc_getOptionOpenShareMode(SMBCCTX
*c
);
547 * Set the share mode to use for files opened with SMBC_open_ctx(). The
548 * default is SMBC_SHAREMODE_DENY_NONE.
551 smbc_setOptionOpenShareMode(SMBCCTX
*c
, smbc_share_mode share_mode
);
553 /** Retrieve a previously saved user data handle */
555 smbc_getOptionUserData(SMBCCTX
*c
);
557 /** Save a user data handle */
559 smbc_setOptionUserData(SMBCCTX
*c
, void *user_data
);
561 /** Get the encoded value for encryption level. */
562 smbc_smb_encrypt_level
563 smbc_getOptionSmbEncryptionLevel(SMBCCTX
*c
);
565 /** Set the encoded value for encryption level. */
567 smbc_setOptionSmbEncryptionLevel(SMBCCTX
*c
, smbc_smb_encrypt_level level
);
570 * Get whether to treat file names as case-sensitive if we can't determine
571 * when connecting to the remote share whether the file system is case
572 * sensitive. This defaults to FALSE since it's most likely that if we can't
573 * retrieve the file system attributes, it's a very old file system that does
574 * not support case sensitivity.
577 smbc_getOptionCaseSensitive(SMBCCTX
*c
);
580 * Set whether to treat file names as case-sensitive if we can't determine
581 * when connecting to the remote share whether the file system is case
582 * sensitive. This defaults to FALSE since it's most likely that if we can't
583 * retrieve the file system attributes, it's a very old file system that does
584 * not support case sensitivity.
587 smbc_setOptionCaseSensitive(SMBCCTX
*c
, smbc_bool b
);
591 * Get from how many local master browsers should the list of workgroups be
592 * retrieved. It can take up to 12 minutes or longer after a server becomes a
593 * local master browser, for it to have the entire browse list (the list of
594 * workgroups/domains) from an entire network. Since a client never knows
595 * which local master browser will be found first, the one which is found
596 * first and used to retrieve a browse list may have an incomplete or empty
597 * browse list. By requesting the browse list from multiple local master
598 * browsers, a more complete list can be generated. For small networks (few
599 * workgroups), it is recommended that this value be set to 0, causing the
600 * browse lists from all found local master browsers to be retrieved and
601 * merged. For networks with many workgroups, a suitable value for this
602 * variable is probably somewhere around 3. (Default: 3).
605 smbc_getOptionBrowseMaxLmbCount(SMBCCTX
*c
);
608 * Set from how many local master browsers should the list of workgroups be
609 * retrieved. It can take up to 12 minutes or longer after a server becomes a
610 * local master browser, for it to have the entire browse list (the list of
611 * workgroups/domains) from an entire network. Since a client never knows
612 * which local master browser will be found first, the one which is found
613 * first and used to retrieve a browse list may have an incomplete or empty
614 * browse list. By requesting the browse list from multiple local master
615 * browsers, a more complete list can be generated. For small networks (few
616 * workgroups), it is recommended that this value be set to 0, causing the
617 * browse lists from all found local master browsers to be retrieved and
618 * merged. For networks with many workgroups, a suitable value for this
619 * variable is probably somewhere around 3. (Default: 3).
622 smbc_setOptionBrowseMaxLmbCount(SMBCCTX
*c
, int count
);
625 * Get 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_getOptionUrlEncodeReaddirEntries(SMBCCTX
*c
);
653 * Set whether to url-encode readdir entries.
655 * There is a difference in the desired return strings from
656 * smbc_readdir() depending upon whether the filenames are to
657 * be displayed to the user, or whether they are to be
658 * appended to the path name passed to smbc_opendir() to call
659 * a further smbc_ function (e.g. open the file with
660 * smbc_open()). In the former case, the filename should be
661 * in "human readable" form. In the latter case, the smbc_
662 * functions expect a URL which must be url-encoded. Those
663 * functions decode the URL. If, for example, smbc_readdir()
664 * returned a file name of "abc%20def.txt", passing a path
665 * with this file name attached to smbc_open() would cause
666 * smbc_open to attempt to open the file "abc def.txt" since
667 * the %20 is decoded into a space.
669 * Set this option to True if the names returned by
670 * smbc_readdir() should be url-encoded such that they can be
671 * passed back to another smbc_ call. Set it to False if the
672 * names returned by smbc_readdir() are to be presented to the
675 * For backwards compatibility, this option defaults to False.
678 smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX
*c
, smbc_bool b
);
681 * Get whether to use the same connection for all shares on a server.
683 * Some Windows versions appear to have a limit to the number
684 * of concurrent SESSIONs and/or TREE CONNECTions. In
685 * one-shot programs (i.e. the program runs and then quickly
686 * ends, thereby shutting down all connections), it is
687 * probably reasonable to establish a new connection for each
688 * share. In long-running applications, the limitation can be
689 * avoided by using only a single connection to each server,
690 * and issuing a new TREE CONNECT when the share is accessed.
693 smbc_getOptionOneSharePerServer(SMBCCTX
*c
);
696 * Set whether to use the same connection for all shares on a server.
698 * Some Windows versions appear to have a limit to the number
699 * of concurrent SESSIONs and/or TREE CONNECTions. In
700 * one-shot programs (i.e. the program runs and then quickly
701 * ends, thereby shutting down all connections), it is
702 * probably reasonable to establish a new connection for each
703 * share. In long-running applications, the limitation can be
704 * avoided by using only a single connection to each server,
705 * and issuing a new TREE CONNECT when the share is accessed.
708 smbc_setOptionOneSharePerServer(SMBCCTX
*c
, smbc_bool b
);
710 /** Get whether to enable use of kerberos */
712 smbc_getOptionUseKerberos(SMBCCTX
*c
);
714 /** Set whether to enable use of kerberos */
716 smbc_setOptionUseKerberos(SMBCCTX
*c
, smbc_bool b
);
718 /** Get whether to fallback after kerberos */
720 smbc_getOptionFallbackAfterKerberos(SMBCCTX
*c
);
722 /** Set whether to fallback after kerberos */
724 smbc_setOptionFallbackAfterKerberos(SMBCCTX
*c
, smbc_bool b
);
726 /** Get whether to automatically select anonymous login */
728 smbc_getOptionNoAutoAnonymousLogin(SMBCCTX
*c
);
730 /** Set whether to automatically select anonymous login */
732 smbc_setOptionNoAutoAnonymousLogin(SMBCCTX
*c
, smbc_bool b
);
736 /*************************************
737 * Getters and setters for FUNCTIONS *
738 *************************************/
740 /** Get the function for obtaining authentication data */
741 smbc_get_auth_data_fn
smbc_getFunctionAuthData(SMBCCTX
*c
);
743 /** Set the function for obtaining authentication data */
744 void smbc_setFunctionAuthData(SMBCCTX
*c
, smbc_get_auth_data_fn fn
);
746 /** Get the new-style authentication function which includes the context. */
747 smbc_get_auth_data_with_context_fn
748 smbc_getFunctionAuthDataWithContext(SMBCCTX
*c
);
750 /** Set the new-style authentication function which includes the context. */
752 smbc_setFunctionAuthDataWithContext(SMBCCTX
*c
,
753 smbc_get_auth_data_with_context_fn fn
);
755 /** Get the function for checking if a server is still good */
756 smbc_check_server_fn
smbc_getFunctionCheckServer(SMBCCTX
*c
);
758 /** Set the function for checking if a server is still good */
759 void smbc_setFunctionCheckServer(SMBCCTX
*c
, smbc_check_server_fn fn
);
761 /** Get the function for removing a server if unused */
762 smbc_remove_unused_server_fn
smbc_getFunctionRemoveUnusedServer(SMBCCTX
*c
);
764 /** Set the function for removing a server if unused */
765 void smbc_setFunctionRemoveUnusedServer(SMBCCTX
*c
,
766 smbc_remove_unused_server_fn fn
);
768 /** Get the function for adding a cached server */
769 smbc_add_cached_srv_fn
smbc_getFunctionAddCachedServer(SMBCCTX
*c
);
771 /** Set the function for adding a cached server */
772 void smbc_setFunctionAddCachedServer(SMBCCTX
*c
, smbc_add_cached_srv_fn fn
);
774 /** Get the function for server cache lookup */
775 smbc_get_cached_srv_fn
smbc_getFunctionGetCachedServer(SMBCCTX
*c
);
777 /** Set the function for server cache lookup */
778 void smbc_setFunctionGetCachedServer(SMBCCTX
*c
, smbc_get_cached_srv_fn fn
);
780 /** Get the function for server cache removal */
781 smbc_remove_cached_srv_fn
smbc_getFunctionRemoveCachedServer(SMBCCTX
*c
);
783 /** Set the function for server cache removal */
784 void smbc_setFunctionRemoveCachedServer(SMBCCTX
*c
,
785 smbc_remove_cached_srv_fn fn
);
788 * Get the function for server cache purging. This function tries to
789 * remove all cached servers (e.g. on disconnect)
791 smbc_purge_cached_fn
smbc_getFunctionPurgeCachedServers(SMBCCTX
*c
);
794 * Set the function for server cache purging. This function tries to
795 * remove all cached servers (e.g. on disconnect)
797 void smbc_setFunctionPurgeCachedServers(SMBCCTX
*c
,
798 smbc_purge_cached_fn fn
);
800 /** Get the function to store private data of the server cache */
801 struct smbc_server_cache
* smbc_getServerCacheData(SMBCCTX
*c
);
803 /** Set the function to store private data of the server cache */
804 void smbc_setServerCacheData(SMBCCTX
*c
, struct smbc_server_cache
* cache
);
808 /*****************************************************************
809 * Callable functions for files. *
810 * Each callable has a function signature typedef, a declaration *
811 * for the getter, and a declaration for the setter. *
812 *****************************************************************/
814 typedef SMBCFILE
* (*smbc_open_fn
)(SMBCCTX
*c
,
818 smbc_open_fn
smbc_getFunctionOpen(SMBCCTX
*c
);
819 void smbc_setFunctionOpen(SMBCCTX
*c
, smbc_open_fn fn
);
821 typedef SMBCFILE
* (*smbc_creat_fn
)(SMBCCTX
*c
,
824 smbc_creat_fn
smbc_getFunctionCreat(SMBCCTX
*c
);
825 void smbc_setFunctionCreat(SMBCCTX
*c
, smbc_creat_fn
);
827 typedef ssize_t (*smbc_read_fn
)(SMBCCTX
*c
,
831 smbc_read_fn
smbc_getFunctionRead(SMBCCTX
*c
);
832 void smbc_setFunctionRead(SMBCCTX
*c
, smbc_read_fn fn
);
834 typedef ssize_t (*smbc_write_fn
)(SMBCCTX
*c
,
838 smbc_write_fn
smbc_getFunctionWrite(SMBCCTX
*c
);
839 void smbc_setFunctionWrite(SMBCCTX
*c
, smbc_write_fn fn
);
841 typedef int (*smbc_unlink_fn
)(SMBCCTX
*c
,
843 smbc_unlink_fn
smbc_getFunctionUnlink(SMBCCTX
*c
);
844 void smbc_setFunctionUnlink(SMBCCTX
*c
, smbc_unlink_fn fn
);
846 typedef int (*smbc_rename_fn
)(SMBCCTX
*ocontext
,
850 smbc_rename_fn
smbc_getFunctionRename(SMBCCTX
*c
);
851 void smbc_setFunctionRename(SMBCCTX
*c
, smbc_rename_fn fn
);
853 typedef off_t (*smbc_lseek_fn
)(SMBCCTX
*c
,
857 smbc_lseek_fn
smbc_getFunctionLseek(SMBCCTX
*c
);
858 void smbc_setFunctionLseek(SMBCCTX
*c
, smbc_lseek_fn fn
);
860 typedef int (*smbc_stat_fn
)(SMBCCTX
*c
,
863 smbc_stat_fn
smbc_getFunctionStat(SMBCCTX
*c
);
864 void smbc_setFunctionStat(SMBCCTX
*c
, smbc_stat_fn fn
);
866 typedef int (*smbc_fstat_fn
)(SMBCCTX
*c
,
869 smbc_fstat_fn
smbc_getFunctionFstat(SMBCCTX
*c
);
870 void smbc_setFunctionFstat(SMBCCTX
*c
, smbc_fstat_fn fn
);
872 typedef int (*smbc_fstatvfs_fn
)(SMBCCTX
*c
,
875 smbc_fstatvfs_fn
smbc_getFunctionFstatVFS(SMBCCTX
*c
);
876 void smbc_setFunctionFstatVFS(SMBCCTX
*c
, smbc_fstatvfs_fn fn
);
878 typedef int (*smbc_ftruncate_fn
)(SMBCCTX
*c
,
881 smbc_ftruncate_fn
smbc_getFunctionFtruncate(SMBCCTX
*c
);
882 void smbc_setFunctionFtruncate(SMBCCTX
*c
, smbc_ftruncate_fn fn
);
884 typedef int (*smbc_close_fn
)(SMBCCTX
*c
,
886 smbc_close_fn
smbc_getFunctionClose(SMBCCTX
*c
);
887 void smbc_setFunctionClose(SMBCCTX
*c
, smbc_close_fn fn
);
891 /*****************************************************************
892 * Callable functions for directories. *
893 * Each callable has a function signature typedef, a declaration *
894 * for the getter, and a declaration for the setter. *
895 *****************************************************************/
897 typedef SMBCFILE
* (*smbc_opendir_fn
)(SMBCCTX
*c
,
899 smbc_opendir_fn
smbc_getFunctionOpendir(SMBCCTX
*c
);
900 void smbc_setFunctionOpendir(SMBCCTX
*c
, smbc_opendir_fn fn
);
902 typedef int (*smbc_closedir_fn
)(SMBCCTX
*c
,
904 smbc_closedir_fn
smbc_getFunctionClosedir(SMBCCTX
*c
);
905 void smbc_setFunctionClosedir(SMBCCTX
*c
, smbc_closedir_fn fn
);
907 typedef struct smbc_dirent
* (*smbc_readdir_fn
)(SMBCCTX
*c
,
909 smbc_readdir_fn
smbc_getFunctionReaddir(SMBCCTX
*c
);
910 void smbc_setFunctionReaddir(SMBCCTX
*c
, smbc_readdir_fn fn
);
912 typedef int (*smbc_getdents_fn
)(SMBCCTX
*c
,
914 struct smbc_dirent
*dirp
,
916 smbc_getdents_fn
smbc_getFunctionGetdents(SMBCCTX
*c
);
917 void smbc_setFunctionGetdents(SMBCCTX
*c
, smbc_getdents_fn fn
);
919 typedef int (*smbc_mkdir_fn
)(SMBCCTX
*c
,
922 smbc_mkdir_fn
smbc_getFunctionMkdir(SMBCCTX
*c
);
923 void smbc_setFunctionMkdir(SMBCCTX
*c
, smbc_mkdir_fn fn
);
925 typedef int (*smbc_rmdir_fn
)(SMBCCTX
*c
,
927 smbc_rmdir_fn
smbc_getFunctionRmdir(SMBCCTX
*c
);
928 void smbc_setFunctionRmdir(SMBCCTX
*c
, smbc_rmdir_fn fn
);
930 typedef off_t (*smbc_telldir_fn
)(SMBCCTX
*c
,
932 smbc_telldir_fn
smbc_getFunctionTelldir(SMBCCTX
*c
);
933 void smbc_setFunctionTelldir(SMBCCTX
*c
, smbc_telldir_fn fn
);
935 typedef int (*smbc_lseekdir_fn
)(SMBCCTX
*c
,
938 smbc_lseekdir_fn
smbc_getFunctionLseekdir(SMBCCTX
*c
);
939 void smbc_setFunctionLseekdir(SMBCCTX
*c
, smbc_lseekdir_fn fn
);
941 typedef int (*smbc_fstatdir_fn
)(SMBCCTX
*c
,
944 smbc_fstatdir_fn
smbc_getFunctionFstatdir(SMBCCTX
*c
);
945 void smbc_setFunctionFstatdir(SMBCCTX
*c
, smbc_fstatdir_fn fn
);
949 /*****************************************************************
950 * Callable functions applicable to both files and directories. *
951 * Each callable has a function signature typedef, a declaration *
952 * for the getter, and a declaration for the setter. *
953 *****************************************************************/
955 typedef int (*smbc_chmod_fn
)(SMBCCTX
*c
,
958 smbc_chmod_fn
smbc_getFunctionChmod(SMBCCTX
*c
);
959 void smbc_setFunctionChmod(SMBCCTX
*c
, smbc_chmod_fn fn
);
961 typedef int (*smbc_utimes_fn
)(SMBCCTX
*c
,
963 struct timeval
*tbuf
);
964 smbc_utimes_fn
smbc_getFunctionUtimes(SMBCCTX
*c
);
965 void smbc_setFunctionUtimes(SMBCCTX
*c
, smbc_utimes_fn fn
);
967 typedef int (*smbc_setxattr_fn
)(SMBCCTX
*context
,
973 smbc_setxattr_fn
smbc_getFunctionSetxattr(SMBCCTX
*c
);
974 void smbc_setFunctionSetxattr(SMBCCTX
*c
, smbc_setxattr_fn fn
);
976 typedef int (*smbc_getxattr_fn
)(SMBCCTX
*context
,
981 smbc_getxattr_fn
smbc_getFunctionGetxattr(SMBCCTX
*c
);
982 void smbc_setFunctionGetxattr(SMBCCTX
*c
, smbc_getxattr_fn fn
);
984 typedef int (*smbc_removexattr_fn
)(SMBCCTX
*context
,
987 smbc_removexattr_fn
smbc_getFunctionRemovexattr(SMBCCTX
*c
);
988 void smbc_setFunctionRemovexattr(SMBCCTX
*c
, smbc_removexattr_fn fn
);
990 typedef int (*smbc_listxattr_fn
)(SMBCCTX
*context
,
994 smbc_listxattr_fn
smbc_getFunctionListxattr(SMBCCTX
*c
);
995 void smbc_setFunctionListxattr(SMBCCTX
*c
, smbc_listxattr_fn fn
);
999 /*****************************************************************
1000 * Callable functions for printing. *
1001 * Each callable has a function signature typedef, a declaration *
1002 * for the getter, and a declaration for the setter. *
1003 *****************************************************************/
1005 typedef int (*smbc_print_file_fn
)(SMBCCTX
*c_file
,
1008 const char *printq
);
1009 smbc_print_file_fn
smbc_getFunctionPrintFile(SMBCCTX
*c
);
1010 void smbc_setFunctionPrintFile(SMBCCTX
*c
, smbc_print_file_fn fn
);
1012 typedef SMBCFILE
* (*smbc_open_print_job_fn
)(SMBCCTX
*c
,
1014 smbc_open_print_job_fn
smbc_getFunctionOpenPrintJob(SMBCCTX
*c
);
1015 void smbc_setFunctionOpenPrintJob(SMBCCTX
*c
,
1016 smbc_open_print_job_fn fn
);
1018 typedef int (*smbc_list_print_jobs_fn
)(SMBCCTX
*c
,
1020 smbc_list_print_job_fn fn
);
1021 smbc_list_print_jobs_fn
smbc_getFunctionListPrintJobs(SMBCCTX
*c
);
1022 void smbc_setFunctionListPrintJobs(SMBCCTX
*c
,
1023 smbc_list_print_jobs_fn fn
);
1025 typedef int (*smbc_unlink_print_job_fn
)(SMBCCTX
*c
,
1028 smbc_unlink_print_job_fn
smbc_getFunctionUnlinkPrintJob(SMBCCTX
*c
);
1029 void smbc_setFunctionUnlinkPrintJob(SMBCCTX
*c
,
1030 smbc_unlink_print_job_fn fn
);
1034 * Create a new SBMCCTX (a context).
1036 * Must be called before the context is passed to smbc_context_init()
1038 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
1039 * - ENOMEM Out of memory
1041 * @see smbc_free_context(), smbc_init_context()
1043 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1045 SMBCCTX
* smbc_new_context(void);
1048 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
1050 * The context will be deleted if possible.
1052 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1054 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1057 * @return Returns 0 on succes. Returns 1 on failure with errno set:
1058 * - EBUSY Server connections are still used, Files are open or cache
1059 * could not be purged
1060 * - EBADF context == NULL
1062 * @see smbc_new_context()
1064 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1065 * just before exit()'ing. When shutdown_ctx is 0, this function can be
1066 * use in periodical cleanup functions for example.
1068 int smbc_free_context(SMBCCTX
* context
, int shutdown_ctx
);
1073 * @deprecated. Use smbc_setOption*() functions instead.
1076 smbc_option_set(SMBCCTX
*context
,
1078 ... /* option_value */);
1081 * @deprecated. Use smbc_getOption*() functions instead.
1084 smbc_option_get(SMBCCTX
*context
,
1088 * Initialize a SBMCCTX (a context).
1090 * Must be called before using any SMBCCTX API function
1092 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1094 * @return A pointer to the given SMBCCTX on success,
1095 * NULL on error with errno set:
1096 * - EBADF NULL context given
1097 * - ENOMEM Out of memory
1098 * - ENOENT The smb.conf file would not load
1100 * @see smbc_new_context()
1102 * @note my_context = smbc_init_context(smbc_new_context())
1103 * is perfectly safe, but it might leak memory on
1104 * smbc_context_init() failure. Avoid this.
1105 * You'll have to call smbc_free_context() yourself
1109 SMBCCTX
* smbc_init_context(SMBCCTX
* context
);
1112 * Initialize the samba client library.
1114 * Must be called before using any of the smbclient API function
1116 * @param fn The function that will be called to obtaion
1117 * authentication credentials.
1119 * @param debug Allows caller to set the debug level. Can be
1120 * changed in smb.conf file. Allows caller to set
1121 * debugging if no smb.conf.
1123 * @return 0 on success, < 0 on error with errno set:
1124 * - ENOMEM Out of memory
1125 * - ENOENT The smb.conf file would not load
1129 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
1132 * Set or retrieve the compatibility library's context pointer
1134 * @param context New context to use, or NULL. If a new context is provided,
1135 * it must have allocated with smbc_new_context() and
1136 * initialized with smbc_init_context(), followed, optionally,
1137 * by some manual changes to some of the non-internal fields.
1139 * @return The old context.
1141 * @see smbc_new_context(), smbc_init_context(), smbc_init()
1143 * @note This function may be called prior to smbc_init() to force
1144 * use of the next context without any internal calls to
1145 * smbc_new_context() or smbc_init_context(). It may also
1146 * be called after smbc_init() has already called those two
1147 * functions, to replace the existing context with a new one.
1148 * Care should be taken, in this latter case, to ensure that
1149 * the server cache and any data allocated by the
1150 * authentication functions have been freed, if necessary.
1153 SMBCCTX
* smbc_set_context(SMBCCTX
* new_context
);
1156 * Open a file on an SMB server.
1158 * @param furl The smb url of the file to be opened.
1160 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1161 * request opening the file read-only,write-only
1162 * or read/write. flags may also be bitwise-or'd with
1163 * one or more of the following:
1164 * O_CREAT - If the file does not exist it will be
1166 * O_EXCL - When used with O_CREAT, if the file
1167 * already exists it is an error and the open will
1169 * O_TRUNC - If the file already exists it will be
1171 * O_APPEND The file is opened in append mode
1173 * @param mode mode specifies the permissions to use if a new
1174 * file is created. It is modified by the
1175 * process's umask in the usual way: the permissions
1176 * of the created file are (mode & ~umask)
1178 * Not currently use, but there for future use.
1179 * We will map this to SYSTEM, HIDDEN, etc bits
1180 * that reverses the mapping that smbc_fstat does.
1182 * @return Valid file handle, < 0 on error with errno set:
1183 * - ENOMEM Out of memory
1184 * - EINVAL if an invalid parameter passed, like no
1185 * file, or smbc_init not called.
1186 * - EEXIST pathname already exists and O_CREAT and
1188 * - EISDIR pathname refers to a directory and
1189 * the access requested involved writing.
1190 * - EACCES The requested access to the file is not
1192 * - ENODEV The requested share does not exist
1193 * - ENOTDIR A file on the path is not a directory
1194 * - ENOENT A directory component in pathname does
1199 * @note This call uses an underlying routine that may create
1200 * a new connection to the server specified in the URL.
1201 * If the credentials supplied in the URL, or via the
1202 * auth_fn in the smbc_init call, fail, this call will
1203 * try again with an empty username and password. This
1204 * often gets mapped to the guest account on some machines.
1207 int smbc_open(const char *furl
, int flags
, mode_t mode
);
1210 * Create a file on an SMB server.
1212 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1214 * @param furl The smb url of the file to be created
1216 * @param mode mode specifies the permissions to use if a new
1217 * file is created. It is modified by the
1218 * process's umask in the usual way: the permissions
1219 * of the created file are (mode & ~umask)
1221 * NOTE, the above is not true. We are dealing with
1222 * an SMB server, which has no concept of a umask!
1224 * @return Valid file handle, < 0 on error with errno set:
1225 * - ENOMEM Out of memory
1226 * - EINVAL if an invalid parameter passed, like no
1227 * file, or smbc_init not called.
1228 * - EEXIST pathname already exists and O_CREAT and
1230 * - EISDIR pathname refers to a directory and
1231 * the access requested involved writing.
1232 * - EACCES The requested access to the file is not
1234 * - ENOENT A directory component in pathname does
1236 * - ENODEV The requested share does not exist.
1241 int smbc_creat(const char *furl
, mode_t mode
);
1244 * Read from a file using an opened file handle.
1246 * @param fd Open file handle from smbc_open() or smbc_creat()
1248 * @param buf Pointer to buffer to recieve read data
1250 * @param bufsize Size of buf in bytes
1252 * @return Number of bytes read, < 0 on error with errno set:
1253 * - EISDIR fd refers to a directory
1254 * - EBADF fd is not a valid file descriptor or
1255 * is not open for reading.
1256 * - EINVAL fd is attached to an object which is
1257 * unsuitable for reading, or no buffer passed or
1258 * smbc_init not called.
1260 * @see smbc_open(), smbc_write()
1263 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
1267 * Write to a file using an opened file handle.
1269 * @param fd Open file handle from smbc_open() or smbc_creat()
1271 * @param buf Pointer to buffer to recieve read data
1273 * @param bufsize Size of buf in bytes
1275 * @return Number of bytes written, < 0 on error with errno set:
1276 * - EISDIR fd refers to a directory.
1277 * - EBADF fd is not a valid file descriptor or
1278 * is not open for reading.
1279 * - EINVAL fd is attached to an object which is
1280 * unsuitable for reading, or no buffer passed or
1281 * smbc_init not called.
1283 * @see smbc_open(), smbc_read()
1286 ssize_t
smbc_write(int fd
, const void *buf
, size_t bufsize
);
1290 * Seek to a specific location in a file.
1292 * @param fd Open file handle from smbc_open() or smbc_creat()
1294 * @param offset Offset in bytes from whence
1296 * @param whence A location in the file:
1297 * - SEEK_SET The offset is set to offset bytes from
1298 * the beginning of the file
1299 * - SEEK_CUR The offset is set to current location
1300 * plus offset bytes.
1301 * - SEEK_END The offset is set to the size of the
1302 * file plus offset bytes.
1304 * @return Upon successful completion, lseek returns the
1305 * resulting offset location as measured in bytes
1306 * from the beginning of the file. Otherwise, a value
1307 * of (off_t)-1 is returned and errno is set to
1308 * indicate the error:
1309 * - EBADF Fildes is not an open file descriptor.
1310 * - EINVAL Whence is not a proper value or smbc_init
1313 * @todo Are all the whence values really supported?
1315 * @todo Are errno values complete and correct?
1317 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
1321 * Close an open file handle.
1323 * @param fd The file handle to close
1325 * @return 0 on success, < 0 on error with errno set:
1326 * - EBADF fd isn't a valid open file descriptor
1327 * - EINVAL smbc_init() failed or has not been called
1329 * @see smbc_open(), smbc_creat()
1331 int smbc_close(int fd
);
1334 /**@ingroup directory
1335 * Unlink (delete) a file or directory.
1337 * @param furl The smb url of the file to delete
1339 * @return 0 on success, < 0 on error with errno set:
1340 * - EACCES or EPERM Write access to the directory
1341 * containing pathname is not allowed or one
1342 * of the directories in pathname did not allow
1343 * search (execute) permission
1344 * - ENOENT A directory component in pathname does
1346 * - EINVAL NULL was passed in the file param or
1347 * smbc_init not called.
1348 * - EACCES You do not have access to the file
1349 * - ENOMEM Insufficient kernel memory was available
1351 * @see smbc_rmdir()s
1353 * @todo Are errno values complete and correct?
1355 int smbc_unlink(const char *furl
);
1358 /**@ingroup directory
1359 * Rename or move a file or directory.
1361 * @param ourl The original smb url (source url) of file or
1362 * directory to be moved
1364 * @param nurl The new smb url (destination url) of the file
1365 * or directory after the move. Currently nurl must
1366 * be on the same share as ourl.
1368 * @return 0 on success, < 0 on error with errno set:
1369 * - EISDIR nurl is an existing directory, but ourl is
1371 * - EEXIST nurl is a non-empty directory,
1372 * i.e., contains entries other than "." and ".."
1373 * - EINVAL The new url contained a path prefix
1374 * of the old, or, more generally, an attempt was
1375 * made to make a directory a subdirectory of itself
1376 * or smbc_init not called.
1377 * - ENOTDIR A component used as a directory in ourl
1378 * or nurl path is not, in fact, a directory. Or,
1379 * ourl is a directory, and newpath exists but is not
1381 * - EACCES or EPERM Write access to the directory
1382 * containing ourl or nurl is not allowed for the
1383 * process's effective uid, or one of the
1384 * directories in ourl or nurl did not allow search
1385 * (execute) permission, or ourl was a directory
1386 * and did not allow write permission.
1387 * - ENOENT A directory component in ourl or nurl
1389 * - EXDEV Rename across shares not supported.
1390 * - ENOMEM Insufficient kernel memory was available.
1391 * - EEXIST The target file, nurl, already exists.
1394 * @todo Are we going to support copying when urls are not on the same
1395 * share? I say no... NOTE. I agree for the moment.
1398 int smbc_rename(const char *ourl
, const char *nurl
);
1401 /**@ingroup directory
1402 * Open a directory used to obtain directory entries.
1404 * @param durl The smb url of the directory to open
1406 * @return Valid directory handle. < 0 on error with errno set:
1407 * - EACCES Permission denied.
1408 * - EINVAL A NULL file/URL was passed, or the URL would
1409 * not parse, or was of incorrect form or smbc_init not
1411 * - ENOENT durl does not exist, or name is an
1412 * - ENOMEM Insufficient memory to complete the
1414 * - ENOTDIR name is not a directory.
1415 * - EPERM the workgroup could not be found.
1416 * - ENODEV the workgroup or server could not be found.
1418 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1421 int smbc_opendir(const char *durl
);
1424 /**@ingroup directory
1425 * Close a directory handle opened by smbc_opendir().
1427 * @param dh Directory handle to close
1429 * @return 0 on success, < 0 on error with errno set:
1430 * - EBADF dh is an invalid directory handle
1432 * @see smbc_opendir()
1434 int smbc_closedir(int dh
);
1437 /**@ingroup directory
1438 * Get multiple directory entries.
1440 * smbc_getdents() reads as many dirent structures from the an open
1441 * directory handle into a specified memory area as will fit.
1443 * @param dh Valid directory as returned by smbc_opendir()
1445 * @param dirp pointer to buffer that will receive the directory
1448 * @param count The size of the dirp buffer in bytes
1450 * @returns If any dirents returned, return will indicate the
1451 * total size. If there were no more dirents available,
1452 * 0 is returned. < 0 indicates an error.
1453 * - EBADF Invalid directory handle
1454 * - EINVAL Result buffer is too small or smbc_init
1456 * - ENOENT No such directory.
1457 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1459 * @todo Are errno values complete and correct?
1461 * @todo Add example code so people know how to parse buffers.
1463 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
1466 /**@ingroup directory
1467 * Get a single directory entry.
1469 * @param dh Valid directory as returned by smbc_opendir()
1471 * @return A pointer to a smbc_dirent structure, or NULL if an
1472 * error occurs or end-of-directory is reached:
1473 * - EBADF Invalid directory handle
1474 * - EINVAL smbc_init() failed or has not been called
1476 * @see smbc_dirent, smbc_getdents(), smbc_open()
1478 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
1481 /**@ingroup directory
1482 * Get the current directory offset.
1484 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1487 * @param dh Valid directory as returned by smbc_opendir()
1489 * @return The current location in the directory stream or -1
1490 * if an error occur. The current location is not
1491 * an offset. Becuase of the implementation, it is a
1492 * handle that allows the library to find the entry
1494 * - EBADF dh is not a valid directory handle
1495 * - EINVAL smbc_init() failed or has not been called
1496 * - ENOTDIR if dh is not a directory
1498 * @see smbc_readdir()
1501 off_t
smbc_telldir(int dh
);
1504 /**@ingroup directory
1505 * lseek on directories.
1507 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1508 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1510 * @param fd Valid directory as returned by smbc_opendir()
1512 * @param offset The offset (as returned by smbc_telldir). Can be
1513 * NULL, in which case we will rewind
1515 * @return 0 on success, -1 on failure
1516 * - EBADF dh is not a valid directory handle
1517 * - ENOTDIR if dh is not a directory
1518 * - EINVAL offset did not refer to a valid dirent or
1519 * smbc_init not called.
1521 * @see smbc_telldir()
1524 * @todo In what does the reture and errno values mean?
1526 int smbc_lseekdir(int fd
, off_t offset
);
1528 /**@ingroup directory
1529 * Create a directory.
1531 * @param durl The url of the directory to create
1533 * @param mode Specifies the permissions to use. It is modified
1534 * by the process's umask in the usual way: the
1535 * permissions of the created file are (mode & ~umask).
1537 * @return 0 on success, < 0 on error with errno set:
1538 * - EEXIST directory url already exists
1539 * - EACCES The parent directory does not allow write
1540 * permission to the process, or one of the directories
1541 * - ENOENT A directory component in pathname does not
1543 * - EINVAL NULL durl passed or smbc_init not called.
1544 * - ENOMEM Insufficient memory was available.
1549 int smbc_mkdir(const char *durl
, mode_t mode
);
1552 /**@ingroup directory
1553 * Remove a directory.
1555 * @param durl The smb url of the directory to remove
1557 * @return 0 on success, < 0 on error with errno set:
1558 * - EACCES or EPERM Write access to the directory
1559 * containing pathname was not allowed.
1560 * - EINVAL durl is NULL or smbc_init not called.
1561 * - ENOENT A directory component in pathname does not
1563 * - ENOTEMPTY directory contains entries.
1564 * - ENOMEM Insufficient kernel memory was available.
1566 * @see smbc_mkdir(), smbc_unlink()
1568 * @todo Are errno values complete and correct?
1570 int smbc_rmdir(const char *durl
);
1573 /**@ingroup attribute
1574 * Get information about a file or directory.
1576 * @param url The smb url to get information for
1578 * @param st pointer to a buffer that will be filled with
1579 * standard Unix struct stat information.
1581 * @return 0 on success, < 0 on error with errno set:
1582 * - ENOENT A component of the path file_name does not
1584 * - EINVAL a NULL url was passed or smbc_init not called.
1585 * - EACCES Permission denied.
1586 * - ENOMEM Out of memory
1587 * - ENOTDIR The target dir, url, is not a directory.
1592 int smbc_stat(const char *url
, struct stat
*st
);
1595 /**@ingroup attribute
1596 * Get file information via an file descriptor.
1598 * @param fd Open file handle from smbc_open() or smbc_creat()
1600 * @param st pointer to a buffer that will be filled with
1601 * standard Unix struct stat information.
1603 * @return EBADF filedes is bad.
1604 * - EACCES Permission denied.
1605 * - EBADF fd is not a valid file descriptor
1606 * - EINVAL Problems occurred in the underlying routines
1607 * or smbc_init not called.
1608 * - ENOMEM Out of memory
1610 * @see smbc_stat(), Unix stat()
1613 int smbc_fstat(int fd
, struct stat
*st
);
1616 /**@ingroup attribute
1617 * Get file system information via an file descriptor.
1619 * @param fd Open file handle from smbc_open(), smbc_creat(),
1622 * @param st pointer to a buffer that will be filled with
1623 * standard Unix struct statvfs information.
1625 * @return EBADF filedes is bad.
1626 * - EACCES Permission denied.
1627 * - EBADF fd is not a valid file descriptor
1628 * - EINVAL Problems occurred in the underlying routines
1629 * or smbc_init not called.
1630 * - ENOMEM Out of memory
1632 * @see Unix fstatvfs()
1636 smbc_fstatvfs(int fd
,
1637 struct statvfs
*st
);
1639 /**@ingroup attribute
1640 * Truncate a file given a file descriptor
1642 * @param fd Open file handle from smbc_open() or smbc_creat()
1644 * @param size size to truncate the file to
1646 * @return EBADF filedes is bad.
1647 * - EACCES Permission denied.
1648 * - EBADF fd is not a valid file descriptor
1649 * - EINVAL Problems occurred in the underlying routines
1650 * or smbc_init not called.
1651 * - ENOMEM Out of memory
1653 * @see , Unix ftruncate()
1656 int smbc_ftruncate(int fd
, off_t size
);
1659 /**@ingroup attribute
1660 * Change the permissions of a file.
1662 * @param url The smb url of the file or directory to change
1665 * @param mode The permissions to set:
1666 * - Put good explaination of permissions here!
1668 * @return 0 on success, < 0 on error with errno set:
1669 * - EPERM The effective UID does not match the owner
1670 * of the file, and is not zero
1671 * - ENOENT The file does not exist.
1672 * - ENOMEM Insufficient was available.
1673 * - ENOENT file or directory does not exist
1675 * @todo Actually implement this fuction?
1677 * @todo Are errno values complete and correct?
1679 int smbc_chmod(const char *url
, mode_t mode
);
1682 * @ingroup attribute
1683 * Change the last modification time on a file
1685 * @param url The smb url of the file or directory to change
1686 * the modification time of
1688 * @param tbuf An array of two timeval structures which contains,
1689 * respectively, the desired access and modification times.
1690 * NOTE: Only the tv_sec field off each timeval structure is
1691 * used. The tv_usec (microseconds) portion is ignored.
1693 * @return 0 on success, < 0 on error with errno set:
1694 * - EINVAL The client library is not properly initialized
1695 * - EPERM Permission was denied.
1698 int smbc_utimes(const char *url
, struct timeval
*tbuf
);
1702 * @ingroup attribute
1703 * Change the last modification time on a file
1705 * @param url The smb url of the file or directory to change
1706 * the modification time of
1708 * @param utbuf A pointer to a utimebuf structure which contains the
1709 * desired access and modification times.
1711 * @return 0 on success, < 0 on error with errno set:
1712 * - EINVAL The client library is not properly initialized
1713 * - ENOMEM No memory was available for internal needs
1714 * - EPERM Permission was denied.
1717 int smbc_utime(const char *fname
, struct utimbuf
*utbuf
);
1720 /**@ingroup attribute
1721 * Set extended attributes for a file. This is used for modifying a file's
1722 * security descriptor (i.e. owner, group, and access control list)
1724 * @param url The smb url of the file or directory to set extended
1727 * @param name The name of an attribute to be changed. Names are of
1728 * one of the following forms:
1730 * system.nt_sec_desc.<attribute name>
1731 * system.nt_sec_desc.*
1732 * system.nt_sec_desc.*+
1734 * where <attribute name> is one of:
1742 * acl+:<name or sid>
1744 * In the forms "system.nt_sec_desc.*" and
1745 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1746 * literal, i.e. the string is provided exactly as shown, and
1747 * the value parameter should contain a complete security
1748 * descriptor with name:value pairs separated by tabs,
1749 * commas, or newlines (not spaces!).
1751 * The plus sign ('+') indicates that SIDs should be mapped
1752 * to names. Without the plus sign, SIDs are not mapped;
1753 * rather they are simply converted to a string format.
1755 * @param value The value to be assigned to the specified attribute name.
1756 * This buffer should contain only the attribute value if the
1757 * name was of the "system.nt_sec_desc.<attribute_name>"
1758 * form. If the name was of the "system.nt_sec_desc.*" form
1759 * then a complete security descriptor, with name:value pairs
1760 * separated by tabs, commas, or newlines (not spaces!),
1761 * should be provided in this value buffer. A complete
1762 * security descriptor will contain one or more entries
1763 * selected from the following:
1765 * REVISION:<revision number>
1766 * OWNER:<sid or name>
1767 * GROUP:<sid or name>
1768 * ACL:<sid or name>:<type>/<flags>/<mask>
1770 * The revision of the ACL specifies the internal Windows NT
1771 * ACL revision for the security descriptor. If not specified
1772 * it defaults to 1. Using values other than 1 may cause
1773 * strange behaviour.
1775 * The owner and group specify the owner and group sids for
1776 * the object. If the attribute name (either '*+' with a
1777 * complete security descriptor, or individual 'owner+' or
1778 * 'group+' attribute names) ended with a plus sign, the
1779 * specified name is resolved to a SID value, using the
1780 * server on which the file or directory resides. Otherwise,
1781 * the value should be provided in SID-printable format as
1782 * S-1-x-y-z, and is used directly. The <sid or name>
1783 * associated with the ACL: attribute should be provided
1786 * @param size The number of the bytes of data in the value buffer
1788 * @param flags A bit-wise OR of zero or more of the following:
1789 * SMBC_XATTR_FLAG_CREATE -
1790 * fail if the named attribute already exists
1791 * SMBC_XATTR_FLAG_REPLACE -
1792 * fail if the attribute does not already exist
1794 * If neither flag is specified, the specified attributes
1795 * will be added or replace existing attributes of the same
1796 * name, as necessary.
1798 * @return 0 on success, < 0 on error with errno set:
1799 * - EINVAL The client library is not properly initialized
1800 * or one of the parameters is not of a correct
1802 * - ENOMEM No memory was available for internal needs
1803 * - EEXIST If the attribute already exists and the flag
1804 * SMBC_XATTR_FLAG_CREAT was specified
1805 * - ENOATTR If the attribute does not exist and the flag
1806 * SMBC_XATTR_FLAG_REPLACE was specified
1807 * - EPERM Permission was denied.
1808 * - ENOTSUP The referenced file system does not support
1809 * extended attributes
1811 * @note Attribute names are compared in a case-insensitive
1812 * fashion. All of the following are equivalent, although
1813 * the all-lower-case name is the preferred format:
1814 * system.nt_sec_desc.owner
1815 * SYSTEM.NT_SEC_DESC.OWNER
1816 * sYsTeM.nt_sEc_desc.owNER
1819 int smbc_setxattr(const char *url
,
1826 /**@ingroup attribute
1827 * Set extended attributes for a file. This is used for modifying a file's
1828 * security descriptor (i.e. owner, group, and access control list). The
1829 * POSIX function which this maps to would act on a symbolic link rather than
1830 * acting on what the symbolic link points to, but with no symbolic links in
1831 * SMB file systems, this function is functionally identical to
1834 * @param url The smb url of the file or directory to set extended
1837 * @param name The name of an attribute to be changed. Names are of
1838 * one of the following forms:
1840 * system.nt_sec_desc.<attribute name>
1841 * system.nt_sec_desc.*
1842 * system.nt_sec_desc.*+
1844 * where <attribute name> is one of:
1852 * acl+:<name or sid>
1854 * In the forms "system.nt_sec_desc.*" and
1855 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1856 * literal, i.e. the string is provided exactly as shown, and
1857 * the value parameter should contain a complete security
1858 * descriptor with name:value pairs separated by tabs,
1859 * commas, or newlines (not spaces!).
1861 * The plus sign ('+') indicates that SIDs should be mapped
1862 * to names. Without the plus sign, SIDs are not mapped;
1863 * rather they are simply converted to a string format.
1865 * @param value The value to be assigned to the specified attribute name.
1866 * This buffer should contain only the attribute value if the
1867 * name was of the "system.nt_sec_desc.<attribute_name>"
1868 * form. If the name was of the "system.nt_sec_desc.*" form
1869 * then a complete security descriptor, with name:value pairs
1870 * separated by tabs, commas, or newlines (not spaces!),
1871 * should be provided in this value buffer. A complete
1872 * security descriptor will contain one or more entries
1873 * selected from the following:
1875 * REVISION:<revision number>
1876 * OWNER:<sid or name>
1877 * GROUP:<sid or name>
1878 * ACL:<sid or name>:<type>/<flags>/<mask>
1880 * The revision of the ACL specifies the internal Windows NT
1881 * ACL revision for the security descriptor. If not specified
1882 * it defaults to 1. Using values other than 1 may cause
1883 * strange behaviour.
1885 * The owner and group specify the owner and group sids for
1886 * the object. If the attribute name (either '*+' with a
1887 * complete security descriptor, or individual 'owner+' or
1888 * 'group+' attribute names) ended with a plus sign, the
1889 * specified name is resolved to a SID value, using the
1890 * server on which the file or directory resides. Otherwise,
1891 * the value should be provided in SID-printable format as
1892 * S-1-x-y-z, and is used directly. The <sid or name>
1893 * associated with the ACL: attribute should be provided
1896 * @param size The number of the bytes of data in the value buffer
1898 * @param flags A bit-wise OR of zero or more of the following:
1899 * SMBC_XATTR_FLAG_CREATE -
1900 * fail if the named attribute already exists
1901 * SMBC_XATTR_FLAG_REPLACE -
1902 * fail if the attribute does not already exist
1904 * If neither flag is specified, the specified attributes
1905 * will be added or replace existing attributes of the same
1906 * name, as necessary.
1908 * @return 0 on success, < 0 on error with errno set:
1909 * - EINVAL The client library is not properly initialized
1910 * or one of the parameters is not of a correct
1912 * - ENOMEM No memory was available for internal needs
1913 * - EEXIST If the attribute already exists and the flag
1914 * SMBC_XATTR_FLAG_CREAT was specified
1915 * - ENOATTR If the attribute does not exist and the flag
1916 * SMBC_XATTR_FLAG_REPLACE was specified
1917 * - EPERM Permission was denied.
1918 * - ENOTSUP The referenced file system does not support
1919 * extended attributes
1921 * @note Attribute names are compared in a case-insensitive
1922 * fashion. All of the following are equivalent, although
1923 * the all-lower-case name is the preferred format:
1924 * system.nt_sec_desc.owner
1925 * SYSTEM.NT_SEC_DESC.OWNER
1926 * sYsTeM.nt_sEc_desc.owNER
1929 int smbc_lsetxattr(const char *url
,
1936 /**@ingroup attribute
1937 * Set extended attributes for a file. This is used for modifying a file's
1938 * security descriptor (i.e. owner, group, and access control list)
1940 * @param fd A file descriptor associated with an open file (as
1941 * previously returned by smbc_open(), to get extended
1944 * @param name The name of an attribute to be changed. Names are of
1945 * one of the following forms:
1947 * system.nt_sec_desc.<attribute name>
1948 * system.nt_sec_desc.*
1949 * system.nt_sec_desc.*+
1951 * where <attribute name> is one of:
1959 * acl+:<name or sid>
1961 * In the forms "system.nt_sec_desc.*" and
1962 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1963 * literal, i.e. the string is provided exactly as shown, and
1964 * the value parameter should contain a complete security
1965 * descriptor with name:value pairs separated by tabs,
1966 * commas, or newlines (not spaces!).
1968 * The plus sign ('+') indicates that SIDs should be mapped
1969 * to names. Without the plus sign, SIDs are not mapped;
1970 * rather they are simply converted to a string format.
1972 * @param value The value to be assigned to the specified attribute name.
1973 * This buffer should contain only the attribute value if the
1974 * name was of the "system.nt_sec_desc.<attribute_name>"
1975 * form. If the name was of the "system.nt_sec_desc.*" form
1976 * then a complete security descriptor, with name:value pairs
1977 * separated by tabs, commas, or newlines (not spaces!),
1978 * should be provided in this value buffer. A complete
1979 * security descriptor will contain one or more entries
1980 * selected from the following:
1982 * REVISION:<revision number>
1983 * OWNER:<sid or name>
1984 * GROUP:<sid or name>
1985 * ACL:<sid or name>:<type>/<flags>/<mask>
1987 * The revision of the ACL specifies the internal Windows NT
1988 * ACL revision for the security descriptor. If not specified
1989 * it defaults to 1. Using values other than 1 may cause
1990 * strange behaviour.
1992 * The owner and group specify the owner and group sids for
1993 * the object. If the attribute name (either '*+' with a
1994 * complete security descriptor, or individual 'owner+' or
1995 * 'group+' attribute names) ended with a plus sign, the
1996 * specified name is resolved to a SID value, using the
1997 * server on which the file or directory resides. Otherwise,
1998 * the value should be provided in SID-printable format as
1999 * S-1-x-y-z, and is used directly. The <sid or name>
2000 * associated with the ACL: attribute should be provided
2003 * @param size The number of the bytes of data in the value buffer
2005 * @param flags A bit-wise OR of zero or more of the following:
2006 * SMBC_XATTR_FLAG_CREATE -
2007 * fail if the named attribute already exists
2008 * SMBC_XATTR_FLAG_REPLACE -
2009 * fail if the attribute does not already exist
2011 * If neither flag is specified, the specified attributes
2012 * will be added or replace existing attributes of the same
2013 * name, as necessary.
2015 * @return 0 on success, < 0 on error with errno set:
2016 * - EINVAL The client library is not properly initialized
2017 * or one of the parameters is not of a correct
2019 * - ENOMEM No memory was available for internal needs
2020 * - EEXIST If the attribute already exists and the flag
2021 * SMBC_XATTR_FLAG_CREAT was specified
2022 * - ENOATTR If the attribute does not exist and the flag
2023 * SMBC_XATTR_FLAG_REPLACE was specified
2024 * - EPERM Permission was denied.
2025 * - ENOTSUP The referenced file system does not support
2026 * extended attributes
2028 * @note Attribute names are compared in a case-insensitive
2029 * fashion. All of the following are equivalent, although
2030 * the all-lower-case name is the preferred format:
2031 * system.nt_sec_desc.owner
2032 * SYSTEM.NT_SEC_DESC.OWNER
2033 * sYsTeM.nt_sEc_desc.owNER
2036 int smbc_fsetxattr(int fd
,
2043 /**@ingroup attribute
2044 * Get extended attributes for a file.
2046 * @param url The smb url of the file or directory to get extended
2049 * @param name The name of an attribute to be retrieved. Names are of
2050 * one of the following forms:
2052 * system.nt_sec_desc.<attribute name>
2053 * system.nt_sec_desc.*
2054 * system.nt_sec_desc.*+
2056 * where <attribute name> is one of:
2064 * acl+:<name or sid>
2066 * In the forms "system.nt_sec_desc.*" and
2067 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2068 * literal, i.e. the string is provided exactly as shown, and
2069 * the value parameter will return a complete security
2070 * descriptor with name:value pairs separated by tabs,
2071 * commas, or newlines (not spaces!).
2073 * The plus sign ('+') indicates that SIDs should be mapped
2074 * to names. Without the plus sign, SIDs are not mapped;
2075 * rather they are simply converted to a string format.
2077 * @param value A pointer to a buffer in which the value of the specified
2078 * attribute will be placed (unless size is zero).
2080 * @param size The size of the buffer pointed to by value. This parameter
2081 * may also be zero, in which case the size of the buffer
2082 * required to hold the attribute value will be returned,
2083 * but nothing will be placed into the value buffer.
2085 * @return 0 on success, < 0 on error with errno set:
2086 * - EINVAL The client library is not properly initialized
2087 * or one of the parameters is not of a correct
2089 * - ENOMEM No memory was available for internal needs
2090 * - EEXIST If the attribute already exists and the flag
2091 * SMBC_XATTR_FLAG_CREAT was specified
2092 * - ENOATTR If the attribute does not exist and the flag
2093 * SMBC_XATTR_FLAG_REPLACE was specified
2094 * - EPERM Permission was denied.
2095 * - ENOTSUP The referenced file system does not support
2096 * extended attributes
2099 int smbc_getxattr(const char *url
,
2105 /**@ingroup attribute
2106 * Get extended attributes for a file. The POSIX function which this maps to
2107 * would act on a symbolic link rather than acting on what the symbolic link
2108 * points to, but with no symbolic links in SMB file systems, this function
2109 * is functionally identical to smbc_getxattr().
2111 * @param url The smb url of the file or directory to get extended
2114 * @param name The name of an attribute to be retrieved. Names are of
2115 * one of the following forms:
2117 * system.nt_sec_desc.<attribute name>
2118 * system.nt_sec_desc.*
2119 * system.nt_sec_desc.*+
2121 * where <attribute name> is one of:
2129 * acl+:<name or sid>
2131 * In the forms "system.nt_sec_desc.*" and
2132 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2133 * literal, i.e. the string is provided exactly as shown, and
2134 * the value parameter will return a complete security
2135 * descriptor with name:value pairs separated by tabs,
2136 * commas, or newlines (not spaces!).
2138 * The plus sign ('+') indicates that SIDs should be mapped
2139 * to names. Without the plus sign, SIDs are not mapped;
2140 * rather they are simply converted to a string format.
2142 * @param value A pointer to a buffer in which the value of the specified
2143 * attribute will be placed (unless size is zero).
2145 * @param size The size of the buffer pointed to by value. This parameter
2146 * may also be zero, in which case the size of the buffer
2147 * required to hold the attribute value will be returned,
2148 * but nothing will be placed into the value buffer.
2150 * @return 0 on success, < 0 on error with errno set:
2151 * - EINVAL The client library is not properly initialized
2152 * or one of the parameters is not of a correct
2154 * - ENOMEM No memory was available for internal needs
2155 * - EEXIST If the attribute already exists and the flag
2156 * SMBC_XATTR_FLAG_CREAT was specified
2157 * - ENOATTR If the attribute does not exist and the flag
2158 * SMBC_XATTR_FLAG_REPLACE was specified
2159 * - EPERM Permission was denied.
2160 * - ENOTSUP The referenced file system does not support
2161 * extended attributes
2164 int smbc_lgetxattr(const char *url
,
2170 /**@ingroup attribute
2171 * Get extended attributes for a file.
2173 * @param fd A file descriptor associated with an open file (as
2174 * previously returned by smbc_open(), to get extended
2177 * @param name The name of an attribute to be retrieved. Names are of
2178 * one of the following forms:
2180 * system.nt_sec_desc.<attribute name>
2181 * system.nt_sec_desc.*
2182 * system.nt_sec_desc.*+
2184 * where <attribute name> is one of:
2192 * acl+:<name or sid>
2194 * In the forms "system.nt_sec_desc.*" and
2195 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2196 * literal, i.e. the string is provided exactly as shown, and
2197 * the value parameter will return a complete security
2198 * descriptor with name:value pairs separated by tabs,
2199 * commas, or newlines (not spaces!).
2201 * The plus sign ('+') indicates that SIDs should be mapped
2202 * to names. Without the plus sign, SIDs are not mapped;
2203 * rather they are simply converted to a string format.
2205 * @param value A pointer to a buffer in which the value of the specified
2206 * attribute will be placed (unless size is zero).
2208 * @param size The size of the buffer pointed to by value. This parameter
2209 * may also be zero, in which case the size of the buffer
2210 * required to hold the attribute value will be returned,
2211 * but nothing will be placed into the value buffer.
2213 * @return 0 on success, < 0 on error with errno set:
2214 * - EINVAL The client library is not properly initialized
2215 * or one of the parameters is not of a correct
2217 * - ENOMEM No memory was available for internal needs
2218 * - EEXIST If the attribute already exists and the flag
2219 * SMBC_XATTR_FLAG_CREAT was specified
2220 * - ENOATTR If the attribute does not exist and the flag
2221 * SMBC_XATTR_FLAG_REPLACE was specified
2222 * - EPERM Permission was denied.
2223 * - ENOTSUP The referenced file system does not support
2224 * extended attributes
2227 int smbc_fgetxattr(int fd
,
2233 /**@ingroup attribute
2234 * Remove extended attributes for a file. This is used for modifying a file's
2235 * security descriptor (i.e. owner, group, and access control list)
2237 * @param url The smb url of the file or directory to remove the extended
2240 * @param name The name of an attribute to be removed. Names are of
2241 * one of the following forms:
2243 * system.nt_sec_desc.<attribute name>
2244 * system.nt_sec_desc.*
2245 * system.nt_sec_desc.*+
2247 * where <attribute name> is one of:
2255 * acl+:<name or sid>
2257 * In the forms "system.nt_sec_desc.*" and
2258 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2259 * literal, i.e. the string is provided exactly as shown, and
2260 * the value parameter will return a complete security
2261 * descriptor with name:value pairs separated by tabs,
2262 * commas, or newlines (not spaces!).
2264 * The plus sign ('+') indicates that SIDs should be mapped
2265 * to names. Without the plus sign, SIDs are not mapped;
2266 * rather they are simply converted to a string format.
2268 * @return 0 on success, < 0 on error with errno set:
2269 * - EINVAL The client library is not properly initialized
2270 * - ENOMEM No memory was available for internal needs
2271 * - EPERM Permission was denied.
2272 * - ENOTSUP The referenced file system does not support
2273 * extended attributes
2276 int smbc_removexattr(const char *url
,
2280 /**@ingroup attribute
2281 * Remove extended attributes for a file. This is used for modifying a file's
2282 * security descriptor (i.e. owner, group, and access control list) The POSIX
2283 * function which this maps to would act on a symbolic link rather than acting
2284 * on what the symbolic link points to, but with no symbolic links in SMB file
2285 * systems, this function is functionally identical to smbc_removexattr().
2287 * @param url The smb url of the file or directory to remove the extended
2290 * @param name The name of an attribute to be removed. Names are of
2291 * one of the following forms:
2293 * system.nt_sec_desc.<attribute name>
2294 * system.nt_sec_desc.*
2295 * system.nt_sec_desc.*+
2297 * where <attribute name> is one of:
2305 * acl+:<name or sid>
2307 * In the forms "system.nt_sec_desc.*" and
2308 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2309 * literal, i.e. the string is provided exactly as shown, and
2310 * the value parameter will return a complete security
2311 * descriptor with name:value pairs separated by tabs,
2312 * commas, or newlines (not spaces!).
2314 * The plus sign ('+') indicates that SIDs should be mapped
2315 * to names. Without the plus sign, SIDs are not mapped;
2316 * rather they are simply converted to a string format.
2318 * @return 0 on success, < 0 on error with errno set:
2319 * - EINVAL The client library is not properly initialized
2320 * - ENOMEM No memory was available for internal needs
2321 * - EPERM Permission was denied.
2322 * - ENOTSUP The referenced file system does not support
2323 * extended attributes
2326 int smbc_lremovexattr(const char *url
,
2330 /**@ingroup attribute
2331 * Remove extended attributes for a file. This is used for modifying a file's
2332 * security descriptor (i.e. owner, group, and access control list)
2334 * @param fd A file descriptor associated with an open file (as
2335 * previously returned by smbc_open(), to get extended
2338 * @param name The name of an attribute to be removed. Names are of
2339 * one of the following forms:
2341 * system.nt_sec_desc.<attribute name>
2342 * system.nt_sec_desc.*
2343 * system.nt_sec_desc.*+
2345 * where <attribute name> is one of:
2353 * acl+:<name or sid>
2355 * In the forms "system.nt_sec_desc.*" and
2356 * "system.nt_sec_desc.*+", the asterisk and plus signs are
2357 * literal, i.e. the string is provided exactly as shown, and
2358 * the value parameter will return a complete security
2359 * descriptor with name:value pairs separated by tabs,
2360 * commas, or newlines (not spaces!).
2362 * The plus sign ('+') indicates that SIDs should be mapped
2363 * to names. Without the plus sign, SIDs are not mapped;
2364 * rather they are simply converted to a string format.
2366 * @return 0 on success, < 0 on error with errno set:
2367 * - EINVAL The client library is not properly initialized
2368 * - ENOMEM No memory was available for internal needs
2369 * - EPERM Permission was denied.
2370 * - ENOTSUP The referenced file system does not support
2371 * extended attributes
2374 int smbc_fremovexattr(int fd
,
2378 /**@ingroup attribute
2379 * List the supported extended attribute names associated with a file
2381 * @param url The smb url of the file or directory to list the extended
2384 * @param list A pointer to a buffer in which the list of attributes for
2385 * the specified file or directory will be placed (unless
2388 * @param size The size of the buffer pointed to by list. This parameter
2389 * may also be zero, in which case the size of the buffer
2390 * required to hold all of the attribute names will be
2391 * returned, but nothing will be placed into the list buffer.
2393 * @return 0 on success, < 0 on error with errno set:
2394 * - EINVAL The client library is not properly initialized
2395 * - ENOMEM No memory was available for internal needs
2396 * - EPERM Permission was denied.
2397 * - ENOTSUP The referenced file system does not support
2398 * extended attributes
2400 * @note This function always returns all attribute names supported
2401 * by NT file systems, regardless of whether the referenced
2402 * file system supports extended attributes (e.g. a Windows
2403 * 2000 machine supports extended attributes if NTFS is used,
2404 * but not if FAT is used, and Windows 98 doesn't support
2405 * extended attributes at all. Whether this is a feature or
2406 * a bug is yet to be decided.
2408 int smbc_listxattr(const char *url
,
2412 /**@ingroup attribute
2413 * List the supported extended attribute names associated with a file The
2414 * POSIX function which this maps to would act on a symbolic link rather than
2415 * acting on what the symbolic link points to, but with no symbolic links in
2416 * SMB file systems, this function is functionally identical to
2419 * @param url The smb url of the file or directory to list the extended
2422 * @param list A pointer to a buffer in which the list of attributes for
2423 * the specified file or directory will be placed (unless
2426 * @param size The size of the buffer pointed to by list. This parameter
2427 * may also be zero, in which case the size of the buffer
2428 * required to hold all of the attribute names will be
2429 * returned, but nothing will be placed into the list buffer.
2431 * @return 0 on success, < 0 on error with errno set:
2432 * - EINVAL The client library is not properly initialized
2433 * - ENOMEM No memory was available for internal needs
2434 * - EPERM Permission was denied.
2435 * - ENOTSUP The referenced file system does not support
2436 * extended attributes
2438 * @note This function always returns all attribute names supported
2439 * by NT file systems, regardless of wether the referenced
2440 * file system supports extended attributes (e.g. a Windows
2441 * 2000 machine supports extended attributes if NTFS is used,
2442 * but not if FAT is used, and Windows 98 doesn't support
2443 * extended attributes at all. Whether this is a feature or
2444 * a bug is yet to be decided.
2446 int smbc_llistxattr(const char *url
,
2450 /**@ingroup attribute
2451 * List the supported extended attribute names associated with a file
2453 * @param fd A file descriptor associated with an open file (as
2454 * previously returned by smbc_open(), to get extended
2457 * @param list A pointer to a buffer in which the list of attributes for
2458 * the specified file or directory will be placed (unless
2461 * @param size The size of the buffer pointed to by list. This parameter
2462 * may also be zero, in which case the size of the buffer
2463 * required to hold all of the attribute names will be
2464 * returned, but nothing will be placed into the list buffer.
2466 * @return 0 on success, < 0 on error with errno set:
2467 * - EINVAL The client library is not properly initialized
2468 * - ENOMEM No memory was available for internal needs
2469 * - EPERM Permission was denied.
2470 * - ENOTSUP The referenced file system does not support
2471 * extended attributes
2473 * @note This function always returns all attribute names supported
2474 * by NT file systems, regardless of wether the referenced
2475 * file system supports extended attributes (e.g. a Windows
2476 * 2000 machine supports extended attributes if NTFS is used,
2477 * but not if FAT is used, and Windows 98 doesn't support
2478 * extended attributes at all. Whether this is a feature or
2479 * a bug is yet to be decided.
2481 int smbc_flistxattr(int fd
,
2486 * Print a file given the name in fname. It would be a URL ...
2488 * @param fname The URL of a file on a remote SMB server that the
2489 * caller wants printed
2491 * @param printq The URL of the print share to print the file to.
2493 * @return 0 on success, < 0 on error with errno set:
2495 * - EINVAL fname or printq was NULL or smbc_init not
2497 * and errors returned by smbc_open
2500 int smbc_print_file(const char *fname
, const char *printq
);
2503 * Open a print file that can be written to by other calls. This simply
2504 * does an smbc_open call after checking if there is a file name on the
2505 * URI. If not, a temporary name is added ...
2507 * @param fname The URL of the print share to print to?
2509 * @returns A file handle for the print file if successful.
2510 * Returns -1 if an error ocurred and errno has the values
2511 * - EINVAL fname was NULL or smbc_init not called.
2512 * - all errors returned by smbc_open
2515 int smbc_open_print_job(const char *fname
);
2518 * List the print jobs on a print share, for the moment, pass a callback
2520 * @param purl The url of the print share to list the jobs of
2522 * @param fn Callback function the receives printjob info
2524 * @return 0 on success, < 0 on error with errno set:
2525 * - EINVAL fname was NULL or smbc_init not called
2528 int smbc_list_print_jobs(const char *purl
, smbc_list_print_job_fn fn
);
2531 * Delete a print job
2533 * @param purl Url of the print share
2535 * @param id The id of the job to delete
2537 * @return 0 on success, < 0 on error with errno set:
2538 * - EINVAL fname was NULL or smbc_init not called
2540 * @todo what errno values are possible here?
2542 int smbc_unlink_print_job(const char *purl
, int id
);
2544 /**@ingroup callback
2545 * Remove a server from the cached server list it's unused.
2547 * @param context pointer to smb context
2549 * @param srv pointer to server to remove
2551 * @return On success, 0 is returned. 1 is returned if the server could not
2552 * be removed. Also useable outside libsmbclient.
2554 int smbc_remove_unused_server(SMBCCTX
* context
, SMBCSRV
* srv
);
2560 /**@ingroup directory
2561 * Convert strings of %xx to their single character equivalent.
2563 * @param dest A pointer to a buffer in which the resulting decoded
2564 * string should be placed. This may be a pointer to the
2565 * same buffer as src_segment.
2567 * @param src A pointer to the buffer containing the URL to be decoded.
2568 * Any %xx sequences herein are converted to their single
2569 * character equivalent. Each 'x' must be a valid hexadecimal
2570 * digit, or that % sequence is left undecoded.
2572 * @param max_dest_len
2573 * The size of the buffer pointed to by dest_segment.
2575 * @return The number of % sequences which could not be converted
2576 * due to lack of two following hexadecimal digits.
2582 smbc_urldecode(char *dest
, char * src
, size_t max_dest_len
);
2589 * Convert any characters not specifically allowed in a URL into their %xx
2592 * @param dest A pointer to a buffer in which the resulting encoded
2593 * string should be placed. Unlike smbc_urldecode(), this
2594 * must be a buffer unique from src.
2596 * @param src A pointer to the buffer containing the string to be encoded.
2597 * Any character not specifically allowed in a URL is converted
2598 * into its hexadecimal value and encoded as %xx.
2600 * @param max_dest_len
2601 * The size of the buffer pointed to by dest_segment.
2603 * @returns The remaining buffer length.
2609 smbc_urlencode(char * dest
, char * src
, int max_dest_len
);
2615 /**@ingroup directory
2616 * Return the version of the linked Samba code, and thus the version of the
2617 * libsmbclient code.
2619 * @return The version string.
2631 * Set the users credentials globally so they can be used for DFS
2632 * referrals. Probably best to use this function in the smbc_get_auth_data_fn
2635 * @param workgroup Workgroup of the user.
2637 * @param user Username of user.
2639 * @param password Password of user.
2641 * @param use_kerberos Whether to use Kerberos
2643 * @param signing_state One of these strings (all equivalents on same line):
2644 * "off", "no", "false"
2645 * "on", "yes", "true", "auto"
2646 * "force", "required", "forced"
2650 smbc_set_credentials(char *workgroup
,
2653 smbc_bool use_kerberos
,
2654 char *signing_state
);
2658 * @ingroup structure
2659 * Structure that contains a client context information
2660 * This structure is known as SMBCCTX
2662 * DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
2663 * structure should all be considered private to the library. It remains here
2664 * only for backward compatibility.
2666 * See the comments herein for use of the setter and getter functions which
2667 * should now be used for manipulating these values. New features, functions,
2668 * etc., are not added here but rather in _internal where they are not
2669 * directly visible to applications. This makes it much easier to maintain
2670 * ABI compatibility.
2678 * Use smbc_getDebug() and smbc_setDebug()
2680 int debug DEPRECATED_SMBC_INTERFACE
;
2683 * netbios name used for making connections
2686 * Use smbc_getNetbiosName() and smbc_setNetbiosName()
2688 char * netbios_name DEPRECATED_SMBC_INTERFACE
;
2691 * workgroup name used for making connections
2694 * Use smbc_getWorkgroup() and smbc_setWorkgroup()
2696 char * workgroup DEPRECATED_SMBC_INTERFACE
;
2699 * username used for making connections
2702 * Use smbc_getUser() and smbc_setUser()
2704 char * user DEPRECATED_SMBC_INTERFACE
;
2707 * timeout used for waiting on connections / response data (in
2711 * Use smbc_getTimeout() and smbc_setTimeout()
2713 int timeout DEPRECATED_SMBC_INTERFACE
;
2716 * callable functions for files:
2717 * For usage and return values see the SMBC_* functions
2721 * Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2722 * smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2724 smbc_open_fn open DEPRECATED_SMBC_INTERFACE
;
2725 smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE
;
2726 smbc_read_fn read DEPRECATED_SMBC_INTERFACE
;
2727 smbc_write_fn write DEPRECATED_SMBC_INTERFACE
;
2728 smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE
;
2729 smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE
;
2730 smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE
;
2731 smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE
;
2732 smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE
;
2733 #if 0 /* internal */
2734 smbc_ftruncate_fn ftruncate_fn
;
2736 smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE
;
2737 smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE
;
2738 smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE
;
2739 smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE
;
2740 smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE
;
2741 smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE
;
2742 smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE
;
2743 smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE
;
2744 smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE
;
2745 smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE
;
2746 smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE
;
2747 smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE
;
2748 smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE
;
2749 smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE
;
2750 smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE
;
2751 smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE
;
2753 /* Printing-related functions */
2754 smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE
;
2755 smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE
;
2756 smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE
;
2757 smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE
;
2764 * See the comment above each field, for the getter and setter
2765 * functions that should now be used.
2767 struct _smbc_callbacks
2770 * authentication function callback: called upon auth requests
2773 * Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2775 smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE
;
2778 * check if a server is still good
2781 * Use smbc_getFunctionCheckServer(),
2782 * smbc_setFunctionCheckServer()
2784 smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE
;
2787 * remove a server if unused
2790 * Use smbc_getFunctionRemoveUnusedServer(),
2791 * smbc_setFunctionCheckServer()
2793 smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE
;
2797 * For an example cache system see
2798 * samba/source/libsmb/libsmb_cache.c
2800 * Cache subsystem * functions follow.
2804 * server cache addition
2807 * Use smbc_getFunctionAddCachedServer(),
2808 * smbc_setFunctionAddCachedServer()
2810 smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
2813 * server cache lookup
2816 * Use smbc_getFunctionGetCachedServer(),
2817 * smbc_setFunctionGetCachedServer()
2819 smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
2822 * server cache removal
2825 * Use smbc_getFunctionRemoveCachedServer(),
2826 * smbc_setFunctionRemoveCachedServer()
2828 smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE
;
2831 * server cache purging, try to remove all cached servers
2835 * Use smbc_getFunctionPurgeCachedServers(),
2836 * smbc_setFunctionPurgeCachedServers()
2838 smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE
;
2842 * Space where the private data of the server cache used to be
2845 * Use smbc_getServerCacheData(), smbc_setServerCacheData()
2847 void * reserved DEPRECATED_SMBC_INTERFACE
;
2850 * Very old configuration options.
2853 * Use one of the following functions instead:
2854 * smbc_setOptionUseKerberos()
2855 * smbc_getOptionUseKerberos()
2856 * smbc_setOptionFallbackAfterKerberos()
2857 * smbc_getOptionFallbackAfterKerberos()
2858 * smbc_setOptionNoAutoAnonymousLogin()
2859 * smbc_getOptionNoAutoAnonymousLogin()
2861 int flags DEPRECATED_SMBC_INTERFACE
;
2864 * user options selections that apply to this session
2866 * NEW OPTIONS ARE NOT ADDED HERE!
2869 * To set and retrieve options, use the smbc_setOption*() and
2870 * smbc_getOption*() functions.
2872 struct _smbc_options
{
2873 int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE
;
2874 int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE
;
2875 int one_share_per_server DEPRECATED_SMBC_INTERFACE
;
2876 } options DEPRECATED_SMBC_INTERFACE
;
2879 * do _NOT_ touch this from your program !
2881 struct SMBC_internal_data
* internal
;
2885 #endif /* SMBCLIENT_H_INCLUDED */