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>
78
#include <sys/statvfs.h>
82
#define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
84
#define SMBC_WORKGROUP 1
86
#define SMBC_FILE_SHARE 3
87
#define SMBC_PRINTER_SHARE 4
88
#define SMBC_COMMS_SHARE 5
89
#define SMBC_IPC_SHARE 6
95
* Structure that represents a directory entry.
104
SMBC_PRINTER_SHARE=4,
110
unsigned int smbc_type;
112
/** Length of this smbc_dirent in bytes
115
/** The length of the comment string in bytes (does not include
118
unsigned int commentlen;
119
/** Points to the null terminated comment string
122
/** The length of the name string in bytes (does not include
125
unsigned int namelen;
126
/** Points to the null terminated name string
132
* Flags for smbc_setxattr()
133
* Specify a bitwise OR of these, or 0 to add or replace as necessary
135
#define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
136
#define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
140
* Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
141
* attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
142
* "system.*") is specified.
144
#define SMBC_DOS_MODE_READONLY 0x01
145
#define SMBC_DOS_MODE_HIDDEN 0x02
146
#define SMBC_DOS_MODE_SYSTEM 0x04
147
#define SMBC_DOS_MODE_VOLUME_ID 0x08
148
#define SMBC_DOS_MODE_DIRECTORY 0x10
149
#define SMBC_DOS_MODE_ARCHIVE 0x20
152
* Valid values for the option "open_share_mode", when calling
153
* smbc_setOptionOpenShareMode()
155
typedef enum smbc_share_mode
157
SMBC_SHAREMODE_DENY_DOS = 0,
158
SMBC_SHAREMODE_DENY_ALL = 1,
159
SMBC_SHAREMODE_DENY_WRITE = 2,
160
SMBC_SHAREMODE_DENY_READ = 3,
161
SMBC_SHAREMODE_DENY_NONE = 4,
162
SMBC_SHAREMODE_DENY_FCB = 7
167
* Values for option SMB Encryption Level, as set and retrieved with
168
* smbc_setOptionSmbEncryptionLevel() and smbc_getOptionSmbEncryptionLevel()
170
typedef enum smbc_smb_encrypt_level
172
SMBC_ENCRYPTLEVEL_NONE = 0,
173
SMBC_ENCRYPTLEVEL_REQUEST = 1,
174
SMBC_ENCRYPTLEVEL_REQUIRE = 2
175
} smbc_smb_encrypt_level;
179
* Capabilities set in the f_flag field of struct statvfs, from
180
* smbc_statvfs(). These may be OR-ed together to reflect a full set of
181
* available capabilities.
183
typedef enum smbc_vfs_feature
185
/* Defined by POSIX or in Linux include files (low-order bits) */
186
SMBC_VFS_FEATURE_RDONLY = (1 << 0),
188
/* Specific to libsmbclient (high-order bits) */
189
SMBC_VFS_FEATURE_DFS = (1 << 28),
190
SMBC_VFS_FEATURE_CASE_INSENSITIVE = (1 << 29),
191
SMBC_VFS_FEATURE_NO_UNIXCIFS = (1 << 30)
194
typedef int smbc_bool;
198
# define ENOATTR ENOENT /* No such attribute */
204
/**@ingroup structure
205
* Structure that represents a print job.
209
struct print_job_info
211
/** numeric ID of the print job
215
/** represents print job priority (lower numbers mean higher priority)
217
unsigned short priority;
219
/** Size of the print job
223
/** Name of the user that owns the print job
227
/** Name of the print job. This will have no name if an anonymous print
228
* file was opened. Ie smb://server/printer
232
/** Time the print job was spooled
236
#endif /* _CLIENT_H */
239
/**@ingroup structure
242
typedef struct _SMBCSRV SMBCSRV;
244
/**@ingroup structure
245
* File or directory handle
247
typedef struct _SMBCFILE SMBCFILE;
249
/**@ingroup structure
250
* File or directory handle
252
typedef struct _SMBCCTX SMBCCTX;
256
* Flags for SMBCCTX->flags
258
* NEW CODE SHOULD NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE.
260
* smbc_setOptionUseKerberos()
261
* smbc_getOptionUseKerberos()
262
* smbc_setOptionFallbackAfterKerberos()
263
* smbc_getOptionFallbackAFterKerberos()
264
* smbc_setOptionNoAutoAnonymousLogin()
265
* smbc_getOptionNoAutoAnonymousLogin()
267
# define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
268
# define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
269
# define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2)
274
* Authentication callback function type (traditional method)
276
* Type for the the authentication function called by the library to
277
* obtain authentication credentals
279
* For kerberos support the function should just be called without
280
* prompting the user for credentials. Which means a simple 'return'
281
* should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
282
* and examples/libsmbclient/testbrowse.c.
284
* @param srv Server being authenticated to
286
* @param shr Share being authenticated to
288
* @param wg Pointer to buffer containing a "hint" for the
289
* workgroup to be authenticated. Should be filled in
290
* with the correct workgroup if the hint is wrong.
292
* @param wglen The size of the workgroup buffer in bytes
294
* @param un Pointer to buffer containing a "hint" for the
295
* user name to be use for authentication. Should be
296
* filled in with the correct workgroup if the hint is
299
* @param unlen The size of the username buffer in bytes
301
* @param pw Pointer to buffer containing to which password
304
* @param pwlen The size of the password buffer in bytes
307
typedef void (*smbc_get_auth_data_fn)(const char *srv,
311
char *pw, int pwlen);
313
* Authentication callback function type (method that includes context)
315
* Type for the the authentication function called by the library to
316
* obtain authentication credentals
318
* For kerberos support the function should just be called without
319
* prompting the user for credentials. Which means a simple 'return'
320
* should work. Take a look at examples/libsmbclient/get_auth_data_fn.h
321
* and examples/libsmbclient/testbrowse.c.
323
* @param c Pointer to the smb context
325
* @param srv Server being authenticated to
327
* @param shr Share being authenticated to
329
* @param wg Pointer to buffer containing a "hint" for the
330
* workgroup to be authenticated. Should be filled in
331
* with the correct workgroup if the hint is wrong.
333
* @param wglen The size of the workgroup buffer in bytes
335
* @param un Pointer to buffer containing a "hint" for the
336
* user name to be use for authentication. Should be
337
* filled in with the correct workgroup if the hint is
340
* @param unlen The size of the username buffer in bytes
342
* @param pw Pointer to buffer containing to which password
345
* @param pwlen The size of the password buffer in bytes
348
typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
353
char *pw, int pwlen);
357
* Print job info callback function type.
359
* @param i pointer to print job information structure
362
typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
366
* Check if a server is still good
368
* @param c pointer to smb context
370
* @param srv pointer to server to check
372
* @return 0 when connection is good. 1 on error.
375
typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
378
* Remove a server if unused
380
* @param c pointer to smb context
382
* @param srv pointer to server to remove
384
* @return 0 on success. 1 on failure.
387
typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
391
* Add a server to the cache system
393
* @param c pointer to smb context
395
* @param srv pointer to server to add
397
* @param server server name
399
* @param share share name
401
* @param workgroup workgroup used to connect
403
* @param username username used to connect
405
* @return 0 on success. 1 on failure.
408
typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
409
const char * server, const char * share,
410
const char * workgroup, const char * username);
413
* Look up a server in the cache system
415
* @param c pointer to smb context
417
* @param server server name to match
419
* @param share share name to match
421
* @param workgroup workgroup to match
423
* @param username username to match
425
* @return pointer to SMBCSRV on success. NULL on failure.
428
typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
429
const char * share, const char * workgroup,
430
const char * username);
433
* Check if a server is still good
435
* @param c pointer to smb context
437
* @param srv pointer to server to remove
439
* @return 0 when found and removed. 1 on failure.
442
typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
446
* Try to remove all servers from the cache system and disconnect
448
* @param c pointer to smb context
450
* @return 0 when found and removed. 1 on failure.
453
typedef int (*smbc_purge_cached_fn) (SMBCCTX * c);
457
/*****************************************
458
* Getters and setters for CONFIGURATION *
459
*****************************************/
461
/** Get the debug level */
463
smbc_getDebug(SMBCCTX *c);
465
/** Set the debug level */
467
smbc_setDebug(SMBCCTX *c, int debug);
469
/** Get the netbios name used for making connections */
471
smbc_getNetbiosName(SMBCCTX *c);
473
/** Set the netbios name used for making connections */
475
smbc_setNetbiosName(SMBCCTX *c, char * netbios_name);
477
/** Get the workgroup used for making connections */
479
smbc_getWorkgroup(SMBCCTX *c);
481
/** Set the workgroup used for making connections */
482
void smbc_setWorkgroup(SMBCCTX *c, char * workgroup);
484
/** Get the username used for making connections */
486
smbc_getUser(SMBCCTX *c);
488
/** Set the username used for making connections */
490
smbc_setUser(SMBCCTX *c, char * user);
493
* Get the timeout used for waiting on connections and response data
497
smbc_getTimeout(SMBCCTX *c);
500
* Set the timeout used for waiting on connections and response data
504
smbc_setTimeout(SMBCCTX *c, int timeout);
508
/***********************************
509
* Getters and setters for OPTIONS *
510
***********************************/
512
/** Get whether to log to standard error instead of standard output */
514
smbc_getOptionDebugToStderr(SMBCCTX *c);
516
/** Set whether to log to standard error instead of standard output */
518
smbc_setOptionDebugToStderr(SMBCCTX *c, smbc_bool b);
521
* Get whether to use new-style time attribute names, e.g. WRITE_TIME rather
522
* than the old-style names such as M_TIME. This allows also setting/getting
523
* CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
524
* was supposed to be CHANGE_TIME but was confused and sometimes referred to
528
smbc_getOptionFullTimeNames(SMBCCTX *c);
531
* Set whether to use new-style time attribute names, e.g. WRITE_TIME rather
532
* than the old-style names such as M_TIME. This allows also setting/getting
533
* CREATE_TIME which was previously unimplemented. (Note that the old C_TIME
534
* was supposed to be CHANGE_TIME but was confused and sometimes referred to
538
smbc_setOptionFullTimeNames(SMBCCTX *c, smbc_bool b);
541
* Get the share mode to use for files opened with SMBC_open_ctx(). The
542
* default is SMBC_SHAREMODE_DENY_NONE.
545
smbc_getOptionOpenShareMode(SMBCCTX *c);
548
* Set the share mode to use for files opened with SMBC_open_ctx(). The
549
* default is SMBC_SHAREMODE_DENY_NONE.
552
smbc_setOptionOpenShareMode(SMBCCTX *c, smbc_share_mode share_mode);
554
/** Retrieve a previously saved user data handle */
556
smbc_getOptionUserData(SMBCCTX *c);
558
/** Save a user data handle */
560
smbc_setOptionUserData(SMBCCTX *c, void *user_data);
562
/** Get the encoded value for encryption level. */
563
smbc_smb_encrypt_level
564
smbc_getOptionSmbEncryptionLevel(SMBCCTX *c);
566
/** Set the encoded value for encryption level. */
568
smbc_setOptionSmbEncryptionLevel(SMBCCTX *c, smbc_smb_encrypt_level level);
571
* Get whether to treat file names as case-sensitive if we can't determine
572
* when connecting to the remote share whether the file system is case
573
* sensitive. This defaults to FALSE since it's most likely that if we can't
574
* retrieve the file system attributes, it's a very old file system that does
575
* not support case sensitivity.
578
smbc_getOptionCaseSensitive(SMBCCTX *c);
581
* Set whether to treat file names as case-sensitive if we can't determine
582
* when connecting to the remote share whether the file system is case
583
* sensitive. This defaults to FALSE since it's most likely that if we can't
584
* retrieve the file system attributes, it's a very old file system that does
585
* not support case sensitivity.
588
smbc_setOptionCaseSensitive(SMBCCTX *c, smbc_bool b);
592
* Get from how many local master browsers should the list of workgroups be
593
* retrieved. It can take up to 12 minutes or longer after a server becomes a
594
* local master browser, for it to have the entire browse list (the list of
595
* workgroups/domains) from an entire network. Since a client never knows
596
* which local master browser will be found first, the one which is found
597
* first and used to retrieve a browse list may have an incomplete or empty
598
* browse list. By requesting the browse list from multiple local master
599
* browsers, a more complete list can be generated. For small networks (few
600
* workgroups), it is recommended that this value be set to 0, causing the
601
* browse lists from all found local master browsers to be retrieved and
602
* merged. For networks with many workgroups, a suitable value for this
603
* variable is probably somewhere around 3. (Default: 3).
606
smbc_getOptionBrowseMaxLmbCount(SMBCCTX *c);
609
* Set from how many local master browsers should the list of workgroups be
610
* retrieved. It can take up to 12 minutes or longer after a server becomes a
611
* local master browser, for it to have the entire browse list (the list of
612
* workgroups/domains) from an entire network. Since a client never knows
613
* which local master browser will be found first, the one which is found
614
* first and used to retrieve a browse list may have an incomplete or empty
615
* browse list. By requesting the browse list from multiple local master
616
* browsers, a more complete list can be generated. For small networks (few
617
* workgroups), it is recommended that this value be set to 0, causing the
618
* browse lists from all found local master browsers to be retrieved and
619
* merged. For networks with many workgroups, a suitable value for this
620
* variable is probably somewhere around 3. (Default: 3).
623
smbc_setOptionBrowseMaxLmbCount(SMBCCTX *c, int count);
626
* Get whether to url-encode readdir entries.
628
* There is a difference in the desired return strings from
629
* smbc_readdir() depending upon whether the filenames are to
630
* be displayed to the user, or whether they are to be
631
* appended to the path name passed to smbc_opendir() to call
632
* a further smbc_ function (e.g. open the file with
633
* smbc_open()). In the former case, the filename should be
634
* in "human readable" form. In the latter case, the smbc_
635
* functions expect a URL which must be url-encoded. Those
636
* functions decode the URL. If, for example, smbc_readdir()
637
* returned a file name of "abc%20def.txt", passing a path
638
* with this file name attached to smbc_open() would cause
639
* smbc_open to attempt to open the file "abc def.txt" since
640
* the %20 is decoded into a space.
642
* Set this option to True if the names returned by
643
* smbc_readdir() should be url-encoded such that they can be
644
* passed back to another smbc_ call. Set it to False if the
645
* names returned by smbc_readdir() are to be presented to the
648
* For backwards compatibility, this option defaults to False.
651
smbc_getOptionUrlEncodeReaddirEntries(SMBCCTX *c);
654
* Set whether to url-encode readdir entries.
656
* There is a difference in the desired return strings from
657
* smbc_readdir() depending upon whether the filenames are to
658
* be displayed to the user, or whether they are to be
659
* appended to the path name passed to smbc_opendir() to call
660
* a further smbc_ function (e.g. open the file with
661
* smbc_open()). In the former case, the filename should be
662
* in "human readable" form. In the latter case, the smbc_
663
* functions expect a URL which must be url-encoded. Those
664
* functions decode the URL. If, for example, smbc_readdir()
665
* returned a file name of "abc%20def.txt", passing a path
666
* with this file name attached to smbc_open() would cause
667
* smbc_open to attempt to open the file "abc def.txt" since
668
* the %20 is decoded into a space.
670
* Set this option to True if the names returned by
671
* smbc_readdir() should be url-encoded such that they can be
672
* passed back to another smbc_ call. Set it to False if the
673
* names returned by smbc_readdir() are to be presented to the
676
* For backwards compatibility, this option defaults to False.
679
smbc_setOptionUrlEncodeReaddirEntries(SMBCCTX *c, smbc_bool b);
682
* Get whether to use the same connection for all shares on a server.
684
* Some Windows versions appear to have a limit to the number
685
* of concurrent SESSIONs and/or TREE CONNECTions. In
686
* one-shot programs (i.e. the program runs and then quickly
687
* ends, thereby shutting down all connections), it is
688
* probably reasonable to establish a new connection for each
689
* share. In long-running applications, the limitation can be
690
* avoided by using only a single connection to each server,
691
* and issuing a new TREE CONNECT when the share is accessed.
694
smbc_getOptionOneSharePerServer(SMBCCTX *c);
697
* Set whether to use the same connection for all shares on a server.
699
* Some Windows versions appear to have a limit to the number
700
* of concurrent SESSIONs and/or TREE CONNECTions. In
701
* one-shot programs (i.e. the program runs and then quickly
702
* ends, thereby shutting down all connections), it is
703
* probably reasonable to establish a new connection for each
704
* share. In long-running applications, the limitation can be
705
* avoided by using only a single connection to each server,
706
* and issuing a new TREE CONNECT when the share is accessed.
709
smbc_setOptionOneSharePerServer(SMBCCTX *c, smbc_bool b);
711
/** Get whether to enable use of kerberos */
713
smbc_getOptionUseKerberos(SMBCCTX *c);
715
/** Set whether to enable use of kerberos */
717
smbc_setOptionUseKerberos(SMBCCTX *c, smbc_bool b);
719
/** Get whether to fallback after kerberos */
721
smbc_getOptionFallbackAfterKerberos(SMBCCTX *c);
723
/** Set whether to fallback after kerberos */
725
smbc_setOptionFallbackAfterKerberos(SMBCCTX *c, smbc_bool b);
727
/** Get whether to automatically select anonymous login */
729
smbc_getOptionNoAutoAnonymousLogin(SMBCCTX *c);
731
/** Set whether to automatically select anonymous login */
733
smbc_setOptionNoAutoAnonymousLogin(SMBCCTX *c, smbc_bool b);
737
/*************************************
738
* Getters and setters for FUNCTIONS *
739
*************************************/
741
/** Get the function for obtaining authentication data */
742
smbc_get_auth_data_fn smbc_getFunctionAuthData(SMBCCTX *c);
744
/** Set the function for obtaining authentication data */
745
void smbc_setFunctionAuthData(SMBCCTX *c, smbc_get_auth_data_fn fn);
747
/** Get the new-style authentication function which includes the context. */
748
smbc_get_auth_data_with_context_fn
749
smbc_getFunctionAuthDataWithContext(SMBCCTX *c);
751
/** Set the new-style authentication function which includes the context. */
753
smbc_setFunctionAuthDataWithContext(SMBCCTX *c,
754
smbc_get_auth_data_with_context_fn fn);
756
/** Get the function for checking if a server is still good */
757
smbc_check_server_fn smbc_getFunctionCheckServer(SMBCCTX *c);
759
/** Set the function for checking if a server is still good */
760
void smbc_setFunctionCheckServer(SMBCCTX *c, smbc_check_server_fn fn);
762
/** Get the function for removing a server if unused */
763
smbc_remove_unused_server_fn smbc_getFunctionRemoveUnusedServer(SMBCCTX *c);
765
/** Set the function for removing a server if unused */
766
void smbc_setFunctionRemoveUnusedServer(SMBCCTX *c,
767
smbc_remove_unused_server_fn fn);
769
/** Get the function for adding a cached server */
770
smbc_add_cached_srv_fn smbc_getFunctionAddCachedServer(SMBCCTX *c);
772
/** Set the function for adding a cached server */
773
void smbc_setFunctionAddCachedServer(SMBCCTX *c, smbc_add_cached_srv_fn fn);
775
/** Get the function for server cache lookup */
776
smbc_get_cached_srv_fn smbc_getFunctionGetCachedServer(SMBCCTX *c);
778
/** Set the function for server cache lookup */
779
void smbc_setFunctionGetCachedServer(SMBCCTX *c, smbc_get_cached_srv_fn fn);
781
/** Get the function for server cache removal */
782
smbc_remove_cached_srv_fn smbc_getFunctionRemoveCachedServer(SMBCCTX *c);
784
/** Set the function for server cache removal */
785
void smbc_setFunctionRemoveCachedServer(SMBCCTX *c,
786
smbc_remove_cached_srv_fn fn);
789
* Get the function for server cache purging. This function tries to
790
* remove all cached servers (e.g. on disconnect)
792
smbc_purge_cached_fn smbc_getFunctionPurgeCachedServers(SMBCCTX *c);
795
* Set the function for server cache purging. This function tries to
796
* remove all cached servers (e.g. on disconnect)
798
void smbc_setFunctionPurgeCachedServers(SMBCCTX *c,
799
smbc_purge_cached_fn fn);
801
/** Get the function to store private data of the server cache */
802
struct smbc_server_cache * smbc_getServerCacheData(SMBCCTX *c);
804
/** Set the function to store private data of the server cache */
805
void smbc_setServerCacheData(SMBCCTX *c, struct smbc_server_cache * cache);
809
/*****************************************************************
810
* Callable functions for files. *
811
* Each callable has a function signature typedef, a declaration *
812
* for the getter, and a declaration for the setter. *
813
*****************************************************************/
815
typedef SMBCFILE * (*smbc_open_fn)(SMBCCTX *c,
819
smbc_open_fn smbc_getFunctionOpen(SMBCCTX *c);
820
void smbc_setFunctionOpen(SMBCCTX *c, smbc_open_fn fn);
822
typedef SMBCFILE * (*smbc_creat_fn)(SMBCCTX *c,
825
smbc_creat_fn smbc_getFunctionCreat(SMBCCTX *c);
826
void smbc_setFunctionCreat(SMBCCTX *c, smbc_creat_fn);
828
typedef ssize_t (*smbc_read_fn)(SMBCCTX *c,
832
smbc_read_fn smbc_getFunctionRead(SMBCCTX *c);
833
void smbc_setFunctionRead(SMBCCTX *c, smbc_read_fn fn);
835
typedef ssize_t (*smbc_write_fn)(SMBCCTX *c,
839
smbc_write_fn smbc_getFunctionWrite(SMBCCTX *c);
840
void smbc_setFunctionWrite(SMBCCTX *c, smbc_write_fn fn);
842
typedef int (*smbc_unlink_fn)(SMBCCTX *c,
844
smbc_unlink_fn smbc_getFunctionUnlink(SMBCCTX *c);
845
void smbc_setFunctionUnlink(SMBCCTX *c, smbc_unlink_fn fn);
847
typedef int (*smbc_rename_fn)(SMBCCTX *ocontext,
851
smbc_rename_fn smbc_getFunctionRename(SMBCCTX *c);
852
void smbc_setFunctionRename(SMBCCTX *c, smbc_rename_fn fn);
854
typedef off_t (*smbc_lseek_fn)(SMBCCTX *c,
858
smbc_lseek_fn smbc_getFunctionLseek(SMBCCTX *c);
859
void smbc_setFunctionLseek(SMBCCTX *c, smbc_lseek_fn fn);
861
typedef int (*smbc_stat_fn)(SMBCCTX *c,
864
smbc_stat_fn smbc_getFunctionStat(SMBCCTX *c);
865
void smbc_setFunctionStat(SMBCCTX *c, smbc_stat_fn fn);
867
typedef int (*smbc_fstat_fn)(SMBCCTX *c,
870
smbc_fstat_fn smbc_getFunctionFstat(SMBCCTX *c);
871
void smbc_setFunctionFstat(SMBCCTX *c, smbc_fstat_fn fn);
873
typedef int (*smbc_statvfs_fn)(SMBCCTX *c,
876
smbc_statvfs_fn smbc_getFunctionStatVFS(SMBCCTX *c);
877
void smbc_setFunctionStatVFS(SMBCCTX *c, smbc_statvfs_fn fn);
879
typedef int (*smbc_fstatvfs_fn)(SMBCCTX *c,
882
smbc_fstatvfs_fn smbc_getFunctionFstatVFS(SMBCCTX *c);
883
void smbc_setFunctionFstatVFS(SMBCCTX *c, smbc_fstatvfs_fn fn);
885
typedef int (*smbc_ftruncate_fn)(SMBCCTX *c,
888
smbc_ftruncate_fn smbc_getFunctionFtruncate(SMBCCTX *c);
889
void smbc_setFunctionFtruncate(SMBCCTX *c, smbc_ftruncate_fn fn);
891
typedef int (*smbc_close_fn)(SMBCCTX *c,
893
smbc_close_fn smbc_getFunctionClose(SMBCCTX *c);
894
void smbc_setFunctionClose(SMBCCTX *c, smbc_close_fn fn);
898
/*****************************************************************
899
* Callable functions for directories. *
900
* Each callable has a function signature typedef, a declaration *
901
* for the getter, and a declaration for the setter. *
902
*****************************************************************/
904
typedef SMBCFILE * (*smbc_opendir_fn)(SMBCCTX *c,
906
smbc_opendir_fn smbc_getFunctionOpendir(SMBCCTX *c);
907
void smbc_setFunctionOpendir(SMBCCTX *c, smbc_opendir_fn fn);
909
typedef int (*smbc_closedir_fn)(SMBCCTX *c,
911
smbc_closedir_fn smbc_getFunctionClosedir(SMBCCTX *c);
912
void smbc_setFunctionClosedir(SMBCCTX *c, smbc_closedir_fn fn);
914
typedef struct smbc_dirent * (*smbc_readdir_fn)(SMBCCTX *c,
916
smbc_readdir_fn smbc_getFunctionReaddir(SMBCCTX *c);
917
void smbc_setFunctionReaddir(SMBCCTX *c, smbc_readdir_fn fn);
919
typedef int (*smbc_getdents_fn)(SMBCCTX *c,
921
struct smbc_dirent *dirp,
923
smbc_getdents_fn smbc_getFunctionGetdents(SMBCCTX *c);
924
void smbc_setFunctionGetdents(SMBCCTX *c, smbc_getdents_fn fn);
926
typedef int (*smbc_mkdir_fn)(SMBCCTX *c,
929
smbc_mkdir_fn smbc_getFunctionMkdir(SMBCCTX *c);
930
void smbc_setFunctionMkdir(SMBCCTX *c, smbc_mkdir_fn fn);
932
typedef int (*smbc_rmdir_fn)(SMBCCTX *c,
934
smbc_rmdir_fn smbc_getFunctionRmdir(SMBCCTX *c);
935
void smbc_setFunctionRmdir(SMBCCTX *c, smbc_rmdir_fn fn);
937
typedef off_t (*smbc_telldir_fn)(SMBCCTX *c,
939
smbc_telldir_fn smbc_getFunctionTelldir(SMBCCTX *c);
940
void smbc_setFunctionTelldir(SMBCCTX *c, smbc_telldir_fn fn);
942
typedef int (*smbc_lseekdir_fn)(SMBCCTX *c,
945
smbc_lseekdir_fn smbc_getFunctionLseekdir(SMBCCTX *c);
946
void smbc_setFunctionLseekdir(SMBCCTX *c, smbc_lseekdir_fn fn);
948
typedef int (*smbc_fstatdir_fn)(SMBCCTX *c,
951
smbc_fstatdir_fn smbc_getFunctionFstatdir(SMBCCTX *c);
952
void smbc_setFunctionFstatdir(SMBCCTX *c, smbc_fstatdir_fn fn);
956
/*****************************************************************
957
* Callable functions applicable to both files and directories. *
958
* Each callable has a function signature typedef, a declaration *
959
* for the getter, and a declaration for the setter. *
960
*****************************************************************/
962
typedef int (*smbc_chmod_fn)(SMBCCTX *c,
965
smbc_chmod_fn smbc_getFunctionChmod(SMBCCTX *c);
966
void smbc_setFunctionChmod(SMBCCTX *c, smbc_chmod_fn fn);
968
typedef int (*smbc_utimes_fn)(SMBCCTX *c,
970
struct timeval *tbuf);
971
smbc_utimes_fn smbc_getFunctionUtimes(SMBCCTX *c);
972
void smbc_setFunctionUtimes(SMBCCTX *c, smbc_utimes_fn fn);
974
typedef int (*smbc_setxattr_fn)(SMBCCTX *context,
980
smbc_setxattr_fn smbc_getFunctionSetxattr(SMBCCTX *c);
981
void smbc_setFunctionSetxattr(SMBCCTX *c, smbc_setxattr_fn fn);
983
typedef int (*smbc_getxattr_fn)(SMBCCTX *context,
988
smbc_getxattr_fn smbc_getFunctionGetxattr(SMBCCTX *c);
989
void smbc_setFunctionGetxattr(SMBCCTX *c, smbc_getxattr_fn fn);
991
typedef int (*smbc_removexattr_fn)(SMBCCTX *context,
994
smbc_removexattr_fn smbc_getFunctionRemovexattr(SMBCCTX *c);
995
void smbc_setFunctionRemovexattr(SMBCCTX *c, smbc_removexattr_fn fn);
997
typedef int (*smbc_listxattr_fn)(SMBCCTX *context,
1001
smbc_listxattr_fn smbc_getFunctionListxattr(SMBCCTX *c);
1002
void smbc_setFunctionListxattr(SMBCCTX *c, smbc_listxattr_fn fn);
1006
/*****************************************************************
1007
* Callable functions for printing. *
1008
* Each callable has a function signature typedef, a declaration *
1009
* for the getter, and a declaration for the setter. *
1010
*****************************************************************/
1012
typedef int (*smbc_print_file_fn)(SMBCCTX *c_file,
1015
const char *printq);
1016
smbc_print_file_fn smbc_getFunctionPrintFile(SMBCCTX *c);
1017
void smbc_setFunctionPrintFile(SMBCCTX *c, smbc_print_file_fn fn);
1019
typedef SMBCFILE * (*smbc_open_print_job_fn)(SMBCCTX *c,
1021
smbc_open_print_job_fn smbc_getFunctionOpenPrintJob(SMBCCTX *c);
1022
void smbc_setFunctionOpenPrintJob(SMBCCTX *c,
1023
smbc_open_print_job_fn fn);
1025
typedef int (*smbc_list_print_jobs_fn)(SMBCCTX *c,
1027
smbc_list_print_job_fn fn);
1028
smbc_list_print_jobs_fn smbc_getFunctionListPrintJobs(SMBCCTX *c);
1029
void smbc_setFunctionListPrintJobs(SMBCCTX *c,
1030
smbc_list_print_jobs_fn fn);
1032
typedef int (*smbc_unlink_print_job_fn)(SMBCCTX *c,
1035
smbc_unlink_print_job_fn smbc_getFunctionUnlinkPrintJob(SMBCCTX *c);
1036
void smbc_setFunctionUnlinkPrintJob(SMBCCTX *c,
1037
smbc_unlink_print_job_fn fn);
1041
* Create a new SBMCCTX (a context).
1043
* Must be called before the context is passed to smbc_context_init()
1045
* @return The given SMBCCTX pointer on success, NULL on error with errno set:
1046
* - ENOMEM Out of memory
1048
* @see smbc_free_context(), smbc_init_context()
1050
* @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
1052
SMBCCTX * smbc_new_context(void);
1055
* Delete a SBMCCTX (a context) acquired from smbc_new_context().
1057
* The context will be deleted if possible.
1059
* @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1061
* @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
1064
* @return Returns 0 on succes. Returns 1 on failure with errno set:
1065
* - EBUSY Server connections are still used, Files are open or cache
1066
* could not be purged
1067
* - EBADF context == NULL
1069
* @see smbc_new_context()
1071
* @note It is advised to clean up all the contexts with shutdown_ctx set to 1
1072
* just before exit()'ing. When shutdown_ctx is 0, this function can be
1073
* use in periodical cleanup functions for example.
1075
int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
1080
* @deprecated. Use smbc_setOption*() functions instead.
1083
smbc_option_set(SMBCCTX *context,
1085
... /* option_value */);
1088
* @deprecated. Use smbc_getOption*() functions instead.
1091
smbc_option_get(SMBCCTX *context,
1095
* Initialize a SBMCCTX (a context).
1097
* Must be called before using any SMBCCTX API function
1099
* @param context A pointer to a SMBCCTX obtained from smbc_new_context()
1101
* @return A pointer to the given SMBCCTX on success,
1102
* NULL on error with errno set:
1103
* - EBADF NULL context given
1104
* - ENOMEM Out of memory
1105
* - ENOENT The smb.conf file would not load
1107
* @see smbc_new_context()
1109
* @note my_context = smbc_init_context(smbc_new_context())
1110
* is perfectly safe, but it might leak memory on
1111
* smbc_context_init() failure. Avoid this.
1112
* You'll have to call smbc_free_context() yourself
1116
SMBCCTX * smbc_init_context(SMBCCTX * context);
1119
* Initialize the samba client library.
1121
* Must be called before using any of the smbclient API function
1123
* @param fn The function that will be called to obtaion
1124
* authentication credentials.
1126
* @param debug Allows caller to set the debug level. Can be
1127
* changed in smb.conf file. Allows caller to set
1128
* debugging if no smb.conf.
1130
* @return 0 on success, < 0 on error with errno set:
1131
* - ENOMEM Out of memory
1132
* - ENOENT The smb.conf file would not load
1136
int smbc_init(smbc_get_auth_data_fn fn, int debug);
1139
* Set or retrieve the compatibility library's context pointer
1141
* @param context New context to use, or NULL. If a new context is provided,
1142
* it must have allocated with smbc_new_context() and
1143
* initialized with smbc_init_context(), followed, optionally,
1144
* by some manual changes to some of the non-internal fields.
1146
* @return The old context.
1148
* @see smbc_new_context(), smbc_init_context(), smbc_init()
1150
* @note This function may be called prior to smbc_init() to force
1151
* use of the next context without any internal calls to
1152
* smbc_new_context() or smbc_init_context(). It may also
1153
* be called after smbc_init() has already called those two
1154
* functions, to replace the existing context with a new one.
1155
* Care should be taken, in this latter case, to ensure that
1156
* the server cache and any data allocated by the
1157
* authentication functions have been freed, if necessary.
1160
SMBCCTX * smbc_set_context(SMBCCTX * new_context);
1163
* Open a file on an SMB server.
1165
* @param furl The smb url of the file to be opened.
1167
* @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
1168
* request opening the file read-only,write-only
1169
* or read/write. flags may also be bitwise-or'd with
1170
* one or more of the following:
1171
* O_CREAT - If the file does not exist it will be
1173
* O_EXCL - When used with O_CREAT, if the file
1174
* already exists it is an error and the open will
1176
* O_TRUNC - If the file already exists it will be
1178
* O_APPEND The file is opened in append mode
1180
* @param mode mode specifies the permissions to use if a new
1181
* file is created. It is modified by the
1182
* process's umask in the usual way: the permissions
1183
* of the created file are (mode & ~umask)
1185
* Not currently use, but there for future use.
1186
* We will map this to SYSTEM, HIDDEN, etc bits
1187
* that reverses the mapping that smbc_fstat does.
1189
* @return Valid file handle, < 0 on error with errno set:
1190
* - ENOMEM Out of memory
1191
* - EINVAL if an invalid parameter passed, like no
1192
* file, or smbc_init not called.
1193
* - EEXIST pathname already exists and O_CREAT and
1195
* - EISDIR pathname refers to a directory and
1196
* the access requested involved writing.
1197
* - EACCES The requested access to the file is not
1199
* - ENODEV The requested share does not exist
1200
* - ENOTDIR A file on the path is not a directory
1201
* - ENOENT A directory component in pathname does
1206
* @note This call uses an underlying routine that may create
1207
* a new connection to the server specified in the URL.
1208
* If the credentials supplied in the URL, or via the
1209
* auth_fn in the smbc_init call, fail, this call will
1210
* try again with an empty username and password. This
1211
* often gets mapped to the guest account on some machines.
1214
int smbc_open(const char *furl, int flags, mode_t mode);
1217
* Create a file on an SMB server.
1219
* Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
1221
* @param furl The smb url of the file to be created
1223
* @param mode mode specifies the permissions to use if a new
1224
* file is created. It is modified by the
1225
* process's umask in the usual way: the permissions
1226
* of the created file are (mode & ~umask)
1228
* NOTE, the above is not true. We are dealing with
1229
* an SMB server, which has no concept of a umask!
1231
* @return Valid file handle, < 0 on error with errno set:
1232
* - ENOMEM Out of memory
1233
* - EINVAL if an invalid parameter passed, like no
1234
* file, or smbc_init not called.
1235
* - EEXIST pathname already exists and O_CREAT and
1237
* - EISDIR pathname refers to a directory and
1238
* the access requested involved writing.
1239
* - EACCES The requested access to the file is not
1241
* - ENOENT A directory component in pathname does
1243
* - ENODEV The requested share does not exist.
1248
int smbc_creat(const char *furl, mode_t mode);
1251
* Read from a file using an opened file handle.
1253
* @param fd Open file handle from smbc_open() or smbc_creat()
1255
* @param buf Pointer to buffer to recieve read data
1257
* @param bufsize Size of buf in bytes
1259
* @return Number of bytes read;
1261
* < 0 on error, with errno set:
1262
* - EISDIR fd refers to a directory
1263
* - EBADF fd is not a valid file descriptor or
1264
* is not open for reading.
1265
* - EINVAL fd is attached to an object which is
1266
* unsuitable for reading, or no buffer passed or
1267
* smbc_init not called.
1269
* @see smbc_open(), smbc_write()
1272
ssize_t smbc_read(int fd, void *buf, size_t bufsize);
1276
* Write to a file using an opened file handle.
1278
* @param fd Open file handle from smbc_open() or smbc_creat()
1280
* @param buf Pointer to buffer to recieve read data
1282
* @param bufsize Size of buf in bytes
1284
* @return Number of bytes written, < 0 on error with errno set:
1285
* - EISDIR fd refers to a directory.
1286
* - EBADF fd is not a valid file descriptor or
1287
* is not open for reading.
1288
* - EINVAL fd is attached to an object which is
1289
* unsuitable for reading, or no buffer passed or
1290
* smbc_init not called.
1292
* @see smbc_open(), smbc_read()
1295
ssize_t smbc_write(int fd, const void *buf, size_t bufsize);
1299
* Seek to a specific location in a file.
1301
* @param fd Open file handle from smbc_open() or smbc_creat()
1303
* @param offset Offset in bytes from whence
1305
* @param whence A location in the file:
1306
* - SEEK_SET The offset is set to offset bytes from
1307
* the beginning of the file
1308
* - SEEK_CUR The offset is set to current location
1309
* plus offset bytes.
1310
* - SEEK_END The offset is set to the size of the
1311
* file plus offset bytes.
1313
* @return Upon successful completion, lseek returns the
1314
* resulting offset location as measured in bytes
1315
* from the beginning of the file. Otherwise, a value
1316
* of (off_t)-1 is returned and errno is set to
1317
* indicate the error:
1318
* - EBADF Fildes is not an open file descriptor.
1319
* - EINVAL Whence is not a proper value or smbc_init
1322
* @todo Are all the whence values really supported?
1324
* @todo Are errno values complete and correct?
1326
off_t smbc_lseek(int fd, off_t offset, int whence);
1330
* Close an open file handle.
1332
* @param fd The file handle to close
1334
* @return 0 on success, < 0 on error with errno set:
1335
* - EBADF fd isn't a valid open file descriptor
1336
* - EINVAL smbc_init() failed or has not been called
1338
* @see smbc_open(), smbc_creat()
1340
int smbc_close(int fd);
1343
/**@ingroup directory
1344
* Unlink (delete) a file or directory.
1346
* @param furl The smb url of the file to delete
1348
* @return 0 on success, < 0 on error with errno set:
1349
* - EACCES or EPERM Write access to the directory
1350
* containing pathname is not allowed or one
1351
* of the directories in pathname did not allow
1352
* search (execute) permission
1353
* - ENOENT A directory component in pathname does
1355
* - EINVAL NULL was passed in the file param or
1356
* smbc_init not called.
1357
* - EACCES You do not have access to the file
1358
* - ENOMEM Insufficient kernel memory was available
1360
* @see smbc_rmdir()s
1362
* @todo Are errno values complete and correct?
1364
int smbc_unlink(const char *furl);
1367
/**@ingroup directory
1368
* Rename or move a file or directory.
1370
* @param ourl The original smb url (source url) of file or
1371
* directory to be moved
1373
* @param nurl The new smb url (destination url) of the file
1374
* or directory after the move. Currently nurl must
1375
* be on the same share as ourl.
1377
* @return 0 on success, < 0 on error with errno set:
1378
* - EISDIR nurl is an existing directory, but ourl is
1380
* - EEXIST nurl is a non-empty directory,
1381
* i.e., contains entries other than "." and ".."
1382
* - EINVAL The new url contained a path prefix
1383
* of the old, or, more generally, an attempt was
1384
* made to make a directory a subdirectory of itself
1385
* or smbc_init not called.
1386
* - ENOTDIR A component used as a directory in ourl
1387
* or nurl path is not, in fact, a directory. Or,
1388
* ourl is a directory, and newpath exists but is not
1390
* - EACCES or EPERM Write access to the directory
1391
* containing ourl or nurl is not allowed for the
1392
* process's effective uid, or one of the
1393
* directories in ourl or nurl did not allow search
1394
* (execute) permission, or ourl was a directory
1395
* and did not allow write permission.
1396
* - ENOENT A directory component in ourl or nurl
1398
* - EXDEV Rename across shares not supported.
1399
* - ENOMEM Insufficient kernel memory was available.
1400
* - EEXIST The target file, nurl, already exists.
1403
* @todo Are we going to support copying when urls are not on the same
1404
* share? I say no... NOTE. I agree for the moment.
1407
int smbc_rename(const char *ourl, const char *nurl);
1410
/**@ingroup directory
1411
* Open a directory used to obtain directory entries.
1413
* @param durl The smb url of the directory to open
1415
* @return Valid directory handle. < 0 on error with errno set:
1416
* - EACCES Permission denied.
1417
* - EINVAL A NULL file/URL was passed, or the URL would
1418
* not parse, or was of incorrect form or smbc_init not
1420
* - ENOENT durl does not exist, or name is an
1421
* - ENOMEM Insufficient memory to complete the
1423
* - ENOTDIR name is not a directory.
1424
* - EPERM the workgroup could not be found.
1425
* - ENODEV the workgroup or server could not be found.
1427
* @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1430
int smbc_opendir(const char *durl);
1433
/**@ingroup directory
1434
* Close a directory handle opened by smbc_opendir().
1436
* @param dh Directory handle to close
1438
* @return 0 on success, < 0 on error with errno set:
1439
* - EBADF dh is an invalid directory handle
1441
* @see smbc_opendir()
1443
int smbc_closedir(int dh);
1446
/**@ingroup directory
1447
* Get multiple directory entries.
1449
* smbc_getdents() reads as many dirent structures from the an open
1450
* directory handle into a specified memory area as will fit.
1452
* @param dh Valid directory as returned by smbc_opendir()
1454
* @param dirp pointer to buffer that will receive the directory
1457
* @param count The size of the dirp buffer in bytes
1459
* @returns If any dirents returned, return will indicate the
1460
* total size. If there were no more dirents available,
1461
* 0 is returned. < 0 indicates an error.
1462
* - EBADF Invalid directory handle
1463
* - EINVAL Result buffer is too small or smbc_init
1465
* - ENOENT No such directory.
1466
* @see , smbc_dirent, smbc_readdir(), smbc_open()
1468
* @todo Are errno values complete and correct?
1470
* @todo Add example code so people know how to parse buffers.
1472
int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
1475
/**@ingroup directory
1476
* Get a single directory entry.
1478
* @param dh Valid directory as returned by smbc_opendir()
1480
* @return A pointer to a smbc_dirent structure, or NULL if an
1481
* error occurs or end-of-directory is reached:
1482
* - EBADF Invalid directory handle
1483
* - EINVAL smbc_init() failed or has not been called
1485
* @see smbc_dirent, smbc_getdents(), smbc_open()
1487
struct smbc_dirent* smbc_readdir(unsigned int dh);
1490
/**@ingroup directory
1491
* Get the current directory offset.
1493
* smbc_telldir() may be used in conjunction with smbc_readdir() and
1496
* @param dh Valid directory as returned by smbc_opendir()
1498
* @return The current location in the directory stream or -1
1499
* if an error occur. The current location is not
1500
* an offset. Becuase of the implementation, it is a
1501
* handle that allows the library to find the entry
1503
* - EBADF dh is not a valid directory handle
1504
* - EINVAL smbc_init() failed or has not been called
1505
* - ENOTDIR if dh is not a directory
1507
* @see smbc_readdir()
1510
off_t smbc_telldir(int dh);
1513
/**@ingroup directory
1514
* lseek on directories.
1516
* smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1517
* smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1519
* @param fd Valid directory as returned by smbc_opendir()
1521
* @param offset The offset (as returned by smbc_telldir). Can be
1522
* NULL, in which case we will rewind
1524
* @return 0 on success, -1 on failure
1525
* - EBADF dh is not a valid directory handle
1526
* - ENOTDIR if dh is not a directory
1527
* - EINVAL offset did not refer to a valid dirent or
1528
* smbc_init not called.
1530
* @see smbc_telldir()
1533
* @todo In what does the reture and errno values mean?
1535
int smbc_lseekdir(int fd, off_t offset);
1537
/**@ingroup directory
1538
* Create a directory.
1540
* @param durl The url of the directory to create
1542
* @param mode Specifies the permissions to use. It is modified
1543
* by the process's umask in the usual way: the
1544
* permissions of the created file are (mode & ~umask).
1546
* @return 0 on success, < 0 on error with errno set:
1547
* - EEXIST directory url already exists
1548
* - EACCES The parent directory does not allow write
1549
* permission to the process, or one of the directories
1550
* - ENOENT A directory component in pathname does not
1552
* - EINVAL NULL durl passed or smbc_init not called.
1553
* - ENOMEM Insufficient memory was available.
1558
int smbc_mkdir(const char *durl, mode_t mode);
1561
/**@ingroup directory
1562
* Remove a directory.
1564
* @param durl The smb url of the directory to remove
1566
* @return 0 on success, < 0 on error with errno set:
1567
* - EACCES or EPERM Write access to the directory
1568
* containing pathname was not allowed.
1569
* - EINVAL durl is NULL or smbc_init not called.
1570
* - ENOENT A directory component in pathname does not
1572
* - ENOTEMPTY directory contains entries.
1573
* - ENOMEM Insufficient kernel memory was available.
1575
* @see smbc_mkdir(), smbc_unlink()
1577
* @todo Are errno values complete and correct?
1579
int smbc_rmdir(const char *durl);
1582
/**@ingroup attribute
1583
* Get information about a file or directory.
1585
* @param url The smb url to get information for
1587
* @param st pointer to a buffer that will be filled with
1588
* standard Unix struct stat information.
1590
* @return 0 on success, < 0 on error with errno set:
1591
* - ENOENT A component of the path file_name does not
1593
* - EINVAL a NULL url was passed or smbc_init not called.
1594
* - EACCES Permission denied.
1595
* - ENOMEM Out of memory
1596
* - ENOTDIR The target dir, url, is not a directory.
1601
int smbc_stat(const char *url, struct stat *st);
1604
/**@ingroup attribute
1605
* Get file information via an file descriptor.
1607
* @param fd Open file handle from smbc_open() or smbc_creat()
1609
* @param st pointer to a buffer that will be filled with
1610
* standard Unix struct stat information.
1612
* @return 0 on success, < 0 on error with errno set:
1613
* - EBADF filedes is bad.
1614
* - EACCES Permission denied.
1615
* - EBADF fd is not a valid file descriptor
1616
* - EINVAL Problems occurred in the underlying routines
1617
* or smbc_init not called.
1618
* - ENOMEM Out of memory
1620
* @see smbc_stat(), Unix stat()
1623
int smbc_fstat(int fd, struct stat *st);
1626
/**@ingroup attribute
1627
* Get file system information for a specified path.
1629
* @param url The smb url to get information for
1631
* @param st pointer to a buffer that will be filled with
1632
* standard Unix struct statvfs information.
1634
* @return 0 on success, < 0 on error with errno set:
1635
* - EBADF filedes is bad.
1636
* - EACCES Permission denied.
1637
* - EBADF fd is not a valid file descriptor
1638
* - EINVAL Problems occurred in the underlying routines
1639
* or smbc_init not called.
1640
* - ENOMEM Out of memory
1642
* @see Unix fstatvfs()
1646
smbc_statvfs(char *url,
1647
struct statvfs *st);
1649
/**@ingroup attribute
1650
* Get file system information via an file descriptor.
1652
* @param fd Open file handle from smbc_open(), smbc_creat(),
1655
* @param st pointer to a buffer that will be filled with
1656
* standard Unix struct statvfs information.
1658
* @return 0 on success, < 0 on error with errno set:
1659
* - EBADF filedes is bad.
1660
* - EACCES Permission denied.
1661
* - EBADF fd is not a valid file descriptor
1662
* - EINVAL Problems occurred in the underlying routines
1663
* or smbc_init not called.
1664
* - ENOMEM Out of memory
1666
* @see Unix fstatvfs()
1670
smbc_fstatvfs(int fd,
1671
struct statvfs *st);
1674
/**@ingroup attribute
1675
* Truncate a file given a file descriptor
1677
* @param fd Open file handle from smbc_open() or smbc_creat()
1679
* @param size size to truncate the file to
1681
* @return 0 on success, < 0 on error with errno set:
1682
* - EBADF filedes is bad.
1683
* - EACCES Permission denied.
1684
* - EBADF fd is not a valid file descriptor
1685
* - EINVAL Problems occurred in the underlying routines
1686
* or smbc_init not called.
1687
* - ENOMEM Out of memory
1689
* @see , Unix ftruncate()
1692
int smbc_ftruncate(int fd, off_t size);
1695
/**@ingroup attribute
1696
* Change the permissions of a file.
1698
* @param url The smb url of the file or directory to change
1701
* @param mode The permissions to set:
1702
* - Put good explaination of permissions here!
1704
* @return 0 on success, < 0 on error with errno set:
1705
* - EPERM The effective UID does not match the owner
1706
* of the file, and is not zero
1707
* - ENOENT The file does not exist.
1708
* - ENOMEM Insufficient was available.
1709
* - ENOENT file or directory does not exist
1711
* @todo Actually implement this fuction?
1713
* @todo Are errno values complete and correct?
1715
int smbc_chmod(const char *url, mode_t mode);
1718
* @ingroup attribute
1719
* Change the last modification time on a file
1721
* @param url The smb url of the file or directory to change
1722
* the modification time of
1724
* @param tbuf An array of two timeval structures which contains,
1725
* respectively, the desired access and modification times.
1726
* NOTE: Only the tv_sec field off each timeval structure is
1727
* used. The tv_usec (microseconds) portion is ignored.
1729
* @return 0 on success, < 0 on error with errno set:
1730
* - EINVAL The client library is not properly initialized
1731
* - EPERM Permission was denied.
1734
int smbc_utimes(const char *url, struct timeval *tbuf);
1738
* @ingroup attribute
1739
* Change the last modification time on a file
1741
* @param url The smb url of the file or directory to change
1742
* the modification time of
1744
* @param utbuf A pointer to a utimebuf structure which contains the
1745
* desired access and modification times.
1747
* @return 0 on success, < 0 on error with errno set:
1748
* - EINVAL The client library is not properly initialized
1749
* - ENOMEM No memory was available for internal needs
1750
* - EPERM Permission was denied.
1753
int smbc_utime(const char *fname, struct utimbuf *utbuf);
1756
/**@ingroup attribute
1757
* Set extended attributes for a file. This is used for modifying a file's
1758
* security descriptor (i.e. owner, group, and access control list)
1760
* @param url The smb url of the file or directory to set extended
1763
* @param name The name of an attribute to be changed. Names are of
1764
* one of the following forms:
1766
* system.nt_sec_desc.<attribute name>
1767
* system.nt_sec_desc.*
1768
* system.nt_sec_desc.*+
1770
* where <attribute name> is one of:
1778
* acl+:<name or sid>
1780
* In the forms "system.nt_sec_desc.*" and
1781
* "system.nt_sec_desc.*+", the asterisk and plus signs are
1782
* literal, i.e. the string is provided exactly as shown, and
1783
* the value parameter should contain a complete security
1784
* descriptor with name:value pairs separated by tabs,
1785
* commas, or newlines (not spaces!).
1787
* The plus sign ('+') indicates that SIDs should be mapped
1788
* to names. Without the plus sign, SIDs are not mapped;
1789
* rather they are simply converted to a string format.
1791
* @param value The value to be assigned to the specified attribute name.
1792
* This buffer should contain only the attribute value if the
1793
* name was of the "system.nt_sec_desc.<attribute_name>"
1794
* form. If the name was of the "system.nt_sec_desc.*" form
1795
* then a complete security descriptor, with name:value pairs
1796
* separated by tabs, commas, or newlines (not spaces!),
1797
* should be provided in this value buffer. A complete
1798
* security descriptor will contain one or more entries
1799
* selected from the following:
1801
* REVISION:<revision number>
1802
* OWNER:<sid or name>
1803
* GROUP:<sid or name>
1804
* ACL:<sid or name>:<type>/<flags>/<mask>
1806
* The revision of the ACL specifies the internal Windows NT
1807
* ACL revision for the security descriptor. If not specified
1808
* it defaults to 1. Using values other than 1 may cause
1809
* strange behaviour.
1811
* The owner and group specify the owner and group sids for
1812
* the object. If the attribute name (either '*+' with a
1813
* complete security descriptor, or individual 'owner+' or
1814
* 'group+' attribute names) ended with a plus sign, the
1815
* specified name is resolved to a SID value, using the
1816
* server on which the file or directory resides. Otherwise,
1817
* the value should be provided in SID-printable format as
1818
* S-1-x-y-z, and is used directly. The <sid or name>
1819
* associated with the ACL: attribute should be provided
1822
* @param size The number of the bytes of data in the value buffer
1824
* @param flags A bit-wise OR of zero or more of the following:
1825
* SMBC_XATTR_FLAG_CREATE -
1826
* fail if the named attribute already exists
1827
* SMBC_XATTR_FLAG_REPLACE -
1828
* fail if the attribute does not already exist
1830
* If neither flag is specified, the specified attributes
1831
* will be added or replace existing attributes of the same
1832
* name, as necessary.
1834
* @return 0 on success, < 0 on error with errno set:
1835
* - EINVAL The client library is not properly initialized
1836
* or one of the parameters is not of a correct
1838
* - ENOMEM No memory was available for internal needs
1839
* - EEXIST If the attribute already exists and the flag
1840
* SMBC_XATTR_FLAG_CREAT was specified
1841
* - ENOATTR If the attribute does not exist and the flag
1842
* SMBC_XATTR_FLAG_REPLACE was specified
1843
* - EPERM Permission was denied.
1844
* - ENOTSUP The referenced file system does not support
1845
* extended attributes
1847
* @note Attribute names are compared in a case-insensitive
1848
* fashion. All of the following are equivalent, although
1849
* the all-lower-case name is the preferred format:
1850
* system.nt_sec_desc.owner
1851
* SYSTEM.NT_SEC_DESC.OWNER
1852
* sYsTeM.nt_sEc_desc.owNER
1855
int smbc_setxattr(const char *url,
1862
/**@ingroup attribute
1863
* Set extended attributes for a file. This is used for modifying a file's
1864
* security descriptor (i.e. owner, group, and access control list). The
1865
* POSIX function which this maps to would act on a symbolic link rather than
1866
* acting on what the symbolic link points to, but with no symbolic links in
1867
* SMB file systems, this function is functionally identical to
1870
* @param url The smb url of the file or directory to set extended
1873
* @param name The name of an attribute to be changed. Names are of
1874
* one of the following forms:
1876
* system.nt_sec_desc.<attribute name>
1877
* system.nt_sec_desc.*
1878
* system.nt_sec_desc.*+
1880
* where <attribute name> is one of:
1888
* acl+:<name or sid>
1890
* In the forms "system.nt_sec_desc.*" and
1891
* "system.nt_sec_desc.*+", the asterisk and plus signs are
1892
* literal, i.e. the string is provided exactly as shown, and
1893
* the value parameter should contain a complete security
1894
* descriptor with name:value pairs separated by tabs,
1895
* commas, or newlines (not spaces!).
1897
* The plus sign ('+') indicates that SIDs should be mapped
1898
* to names. Without the plus sign, SIDs are not mapped;
1899
* rather they are simply converted to a string format.
1901
* @param value The value to be assigned to the specified attribute name.
1902
* This buffer should contain only the attribute value if the
1903
* name was of the "system.nt_sec_desc.<attribute_name>"
1904
* form. If the name was of the "system.nt_sec_desc.*" form
1905
* then a complete security descriptor, with name:value pairs
1906
* separated by tabs, commas, or newlines (not spaces!),
1907
* should be provided in this value buffer. A complete
1908
* security descriptor will contain one or more entries
1909
* selected from the following:
1911
* REVISION:<revision number>
1912
* OWNER:<sid or name>
1913
* GROUP:<sid or name>
1914
* ACL:<sid or name>:<type>/<flags>/<mask>
1916
* The revision of the ACL specifies the internal Windows NT
1917
* ACL revision for the security descriptor. If not specified
1918
* it defaults to 1. Using values other than 1 may cause
1919
* strange behaviour.
1921
* The owner and group specify the owner and group sids for
1922
* the object. If the attribute name (either '*+' with a
1923
* complete security descriptor, or individual 'owner+' or
1924
* 'group+' attribute names) ended with a plus sign, the
1925
* specified name is resolved to a SID value, using the
1926
* server on which the file or directory resides. Otherwise,
1927
* the value should be provided in SID-printable format as
1928
* S-1-x-y-z, and is used directly. The <sid or name>
1929
* associated with the ACL: attribute should be provided
1932
* @param size The number of the bytes of data in the value buffer
1934
* @param flags A bit-wise OR of zero or more of the following:
1935
* SMBC_XATTR_FLAG_CREATE -
1936
* fail if the named attribute already exists
1937
* SMBC_XATTR_FLAG_REPLACE -
1938
* fail if the attribute does not already exist
1940
* If neither flag is specified, the specified attributes
1941
* will be added or replace existing attributes of the same
1942
* name, as necessary.
1944
* @return 0 on success, < 0 on error with errno set:
1945
* - EINVAL The client library is not properly initialized
1946
* or one of the parameters is not of a correct
1948
* - ENOMEM No memory was available for internal needs
1949
* - EEXIST If the attribute already exists and the flag
1950
* SMBC_XATTR_FLAG_CREAT was specified
1951
* - ENOATTR If the attribute does not exist and the flag
1952
* SMBC_XATTR_FLAG_REPLACE was specified
1953
* - EPERM Permission was denied.
1954
* - ENOTSUP The referenced file system does not support
1955
* extended attributes
1957
* @note Attribute names are compared in a case-insensitive
1958
* fashion. All of the following are equivalent, although
1959
* the all-lower-case name is the preferred format:
1960
* system.nt_sec_desc.owner
1961
* SYSTEM.NT_SEC_DESC.OWNER
1962
* sYsTeM.nt_sEc_desc.owNER
1965
int smbc_lsetxattr(const char *url,
1972
/**@ingroup attribute
1973
* Set extended attributes for a file. This is used for modifying a file's
1974
* security descriptor (i.e. owner, group, and access control list)
1976
* @param fd A file descriptor associated with an open file (as
1977
* previously returned by smbc_open(), to get extended
1980
* @param name The name of an attribute to be changed. Names are of
1981
* one of the following forms:
1983
* system.nt_sec_desc.<attribute name>
1984
* system.nt_sec_desc.*
1985
* system.nt_sec_desc.*+
1987
* where <attribute name> is one of:
1995
* acl+:<name or sid>
1997
* In the forms "system.nt_sec_desc.*" and
1998
* "system.nt_sec_desc.*+", the asterisk and plus signs are
1999
* literal, i.e. the string is provided exactly as shown, and
2000
* the value parameter should contain a complete security
2001
* descriptor with name:value pairs separated by tabs,
2002
* commas, or newlines (not spaces!).
2004
* The plus sign ('+') indicates that SIDs should be mapped
2005
* to names. Without the plus sign, SIDs are not mapped;
2006
* rather they are simply converted to a string format.
2008
* @param value The value to be assigned to the specified attribute name.
2009
* This buffer should contain only the attribute value if the
2010
* name was of the "system.nt_sec_desc.<attribute_name>"
2011
* form. If the name was of the "system.nt_sec_desc.*" form
2012
* then a complete security descriptor, with name:value pairs
2013
* separated by tabs, commas, or newlines (not spaces!),
2014
* should be provided in this value buffer. A complete
2015
* security descriptor will contain one or more entries
2016
* selected from the following:
2018
* REVISION:<revision number>
2019
* OWNER:<sid or name>
2020
* GROUP:<sid or name>
2021
* ACL:<sid or name>:<type>/<flags>/<mask>
2023
* The revision of the ACL specifies the internal Windows NT
2024
* ACL revision for the security descriptor. If not specified
2025
* it defaults to 1. Using values other than 1 may cause
2026
* strange behaviour.
2028
* The owner and group specify the owner and group sids for
2029
* the object. If the attribute name (either '*+' with a
2030
* complete security descriptor, or individual 'owner+' or
2031
* 'group+' attribute names) ended with a plus sign, the
2032
* specified name is resolved to a SID value, using the
2033
* server on which the file or directory resides. Otherwise,
2034
* the value should be provided in SID-printable format as
2035
* S-1-x-y-z, and is used directly. The <sid or name>
2036
* associated with the ACL: attribute should be provided
2039
* @param size The number of the bytes of data in the value buffer
2041
* @param flags A bit-wise OR of zero or more of the following:
2042
* SMBC_XATTR_FLAG_CREATE -
2043
* fail if the named attribute already exists
2044
* SMBC_XATTR_FLAG_REPLACE -
2045
* fail if the attribute does not already exist
2047
* If neither flag is specified, the specified attributes
2048
* will be added or replace existing attributes of the same
2049
* name, as necessary.
2051
* @return 0 on success, < 0 on error with errno set:
2052
* - EINVAL The client library is not properly initialized
2053
* or one of the parameters is not of a correct
2055
* - ENOMEM No memory was available for internal needs
2056
* - EEXIST If the attribute already exists and the flag
2057
* SMBC_XATTR_FLAG_CREAT was specified
2058
* - ENOATTR If the attribute does not exist and the flag
2059
* SMBC_XATTR_FLAG_REPLACE was specified
2060
* - EPERM Permission was denied.
2061
* - ENOTSUP The referenced file system does not support
2062
* extended attributes
2064
* @note Attribute names are compared in a case-insensitive
2065
* fashion. All of the following are equivalent, although
2066
* the all-lower-case name is the preferred format:
2067
* system.nt_sec_desc.owner
2068
* SYSTEM.NT_SEC_DESC.OWNER
2069
* sYsTeM.nt_sEc_desc.owNER
2072
int smbc_fsetxattr(int fd,
2079
/**@ingroup attribute
2080
* Get extended attributes for a file.
2082
* @param url The smb url of the file or directory to get extended
2085
* @param name The name of an attribute to be retrieved. Names are of
2086
* one of the following forms:
2088
* system.nt_sec_desc.<attribute name>
2089
* system.nt_sec_desc.*
2090
* system.nt_sec_desc.*+
2092
* where <attribute name> is one of:
2100
* acl+:<name or sid>
2102
* In the forms "system.nt_sec_desc.*" and
2103
* "system.nt_sec_desc.*+", the asterisk and plus signs are
2104
* literal, i.e. the string is provided exactly as shown, and
2105
* the value parameter will return a complete security
2106
* descriptor with name:value pairs separated by tabs,
2107
* commas, or newlines (not spaces!).
2109
* The plus sign ('+') indicates that SIDs should be mapped
2110
* to names. Without the plus sign, SIDs are not mapped;
2111
* rather they are simply converted to a string format.
2113
* @param value A pointer to a buffer in which the value of the specified
2114
* attribute will be placed (unless size is zero).
2116
* @param size The size of the buffer pointed to by value. This parameter
2117
* may also be zero, in which case the size of the buffer
2118
* required to hold the attribute value will be returned,
2119
* but nothing will be placed into the value buffer.
2121
* @return 0 on success, < 0 on error with errno set:
2122
* - EINVAL The client library is not properly initialized
2123
* or one of the parameters is not of a correct
2125
* - ENOMEM No memory was available for internal needs
2126
* - EEXIST If the attribute already exists and the flag
2127
* SMBC_XATTR_FLAG_CREAT was specified
2128
* - ENOATTR If the attribute does not exist and the flag
2129
* SMBC_XATTR_FLAG_REPLACE was specified
2130
* - EPERM Permission was denied.
2131
* - ENOTSUP The referenced file system does not support
2132
* extended attributes
2135
int smbc_getxattr(const char *url,
2141
/**@ingroup attribute
2142
* Get extended attributes for a file. The POSIX function which this maps to
2143
* would act on a symbolic link rather than acting on what the symbolic link
2144
* points to, but with no symbolic links in SMB file systems, this function
2145
* is functionally identical to smbc_getxattr().
2147
* @param url The smb url of the file or directory to get extended
2150
* @param name The name of an attribute to be retrieved. Names are of
2151
* one of the following forms:
2153
* system.nt_sec_desc.<attribute name>
2154
* system.nt_sec_desc.*
2155
* system.nt_sec_desc.*+
2157
* where <attribute name> is one of:
2165
* acl+:<name or sid>
2167
* In the forms "system.nt_sec_desc.*" and
2168
* "system.nt_sec_desc.*+", the asterisk and plus signs are
2169
* literal, i.e. the string is provided exactly as shown, and
2170
* the value parameter will return a complete security
2171
* descriptor with name:value pairs separated by tabs,
2172
* commas, or newlines (not spaces!).
2174
* The plus sign ('+') indicates that SIDs should be mapped
2175
* to names. Without the plus sign, SIDs are not mapped;
2176
* rather they are simply converted to a string format.
2178
* @param value A pointer to a buffer in which the value of the specified
2179
* attribute will be placed (unless size is zero).
2181
* @param size The size of the buffer pointed to by value. This parameter
2182
* may also be zero, in which case the size of the buffer
2183
* required to hold the attribute value will be returned,
2184
* but nothing will be placed into the value buffer.
2186
* @return 0 on success, < 0 on error with errno set:
2187
* - EINVAL The client library is not properly initialized
2188
* or one of the parameters is not of a correct
2190
* - ENOMEM No memory was available for internal needs
2191
* - EEXIST If the attribute already exists and the flag
2192
* SMBC_XATTR_FLAG_CREAT was specified
2193
* - ENOATTR If the attribute does not exist and the flag
2194
* SMBC_XATTR_FLAG_REPLACE was specified
2195
* - EPERM Permission was denied.
2196
* - ENOTSUP The referenced file system does not support
2197
* extended attributes
2200
int smbc_lgetxattr(const char *url,
2206
/**@ingroup attribute
2207
* Get extended attributes for a file.
2209
* @param fd A file descriptor associated with an open file (as
2210
* previously returned by smbc_open(), to get extended
2213
* @param name The name of an attribute to be retrieved. Names are of
2214
* one of the following forms:
2216
* system.nt_sec_desc.<attribute name>
2217
* system.nt_sec_desc.*
2218
* system.nt_sec_desc.*+
2220
* where <attribute name> is one of:
2228
* acl+:<name or sid>
2230
* In the forms "system.nt_sec_desc.*" and
2231
* "system.nt_sec_desc.*+", the asterisk and plus signs are
2232
* literal, i.e. the string is provided exactly as shown, and
2233
* the value parameter will return a complete security
2234
* descriptor with name:value pairs separated by tabs,
2235
* commas, or newlines (not spaces!).
2237
* The plus sign ('+') indicates that SIDs should be mapped
2238
* to names. Without the plus sign, SIDs are not mapped;
2239
* rather they are simply converted to a string format.
2241
* @param value A pointer to a buffer in which the value of the specified
2242
* attribute will be placed (unless size is zero).
2244
* @param size The size of the buffer pointed to by value. This parameter
2245
* may also be zero, in which case the size of the buffer
2246
* required to hold the attribute value will be returned,
2247
* but nothing will be placed into the value buffer.
2249
* @return 0 on success, < 0 on error with errno set:
2250
* - EINVAL The client library is not properly initialized
2251
* or one of the parameters is not of a correct
2253
* - ENOMEM No memory was available for internal needs
2254
* - EEXIST If the attribute already exists and the flag
2255
* SMBC_XATTR_FLAG_CREAT was specified
2256
* - ENOATTR If the attribute does not exist and the flag
2257
* SMBC_XATTR_FLAG_REPLACE was specified
2258
* - EPERM Permission was denied.
2259
* - ENOTSUP The referenced file system does not support
2260
* extended attributes
2263
int smbc_fgetxattr(int fd,
2269
/**@ingroup attribute
2270
* Remove extended attributes for a file. This is used for modifying a file's
2271
* security descriptor (i.e. owner, group, and access control list)
2273
* @param url The smb url of the file or directory to remove the extended
2276
* @param name The name of an attribute to be removed. Names are of
2277
* one of the following forms:
2279
* system.nt_sec_desc.<attribute name>
2280
* system.nt_sec_desc.*
2281
* system.nt_sec_desc.*+
2283
* where <attribute name> is one of:
2291
* acl+:<name or sid>
2293
* In the forms "system.nt_sec_desc.*" and
2294
* "system.nt_sec_desc.*+", the asterisk and plus signs are
2295
* literal, i.e. the string is provided exactly as shown, and
2296
* the value parameter will return a complete security
2297
* descriptor with name:value pairs separated by tabs,
2298
* commas, or newlines (not spaces!).
2300
* The plus sign ('+') indicates that SIDs should be mapped
2301
* to names. Without the plus sign, SIDs are not mapped;
2302
* rather they are simply converted to a string format.
2304
* @return 0 on success, < 0 on error with errno set:
2305
* - EINVAL The client library is not properly initialized
2306
* - ENOMEM No memory was available for internal needs
2307
* - EPERM Permission was denied.
2308
* - ENOTSUP The referenced file system does not support
2309
* extended attributes
2312
int smbc_removexattr(const char *url,
2316
/**@ingroup attribute
2317
* Remove extended attributes for a file. This is used for modifying a file's
2318
* security descriptor (i.e. owner, group, and access control list) The POSIX
2319
* function which this maps to would act on a symbolic link rather than acting
2320
* on what the symbolic link points to, but with no symbolic links in SMB file
2321
* systems, this function is functionally identical to smbc_removexattr().
2323
* @param url The smb url of the file or directory to remove the extended
2326
* @param name The name of an attribute to be removed. Names are of
2327
* one of the following forms:
2329
* system.nt_sec_desc.<attribute name>
2330
* system.nt_sec_desc.*
2331
* system.nt_sec_desc.*+
2333
* where <attribute name> is one of:
2341
* acl+:<name or sid>
2343
* In the forms "system.nt_sec_desc.*" and
2344
* "system.nt_sec_desc.*+", the asterisk and plus signs are
2345
* literal, i.e. the string is provided exactly as shown, and
2346
* the value parameter will return a complete security
2347
* descriptor with name:value pairs separated by tabs,
2348
* commas, or newlines (not spaces!).
2350
* The plus sign ('+') indicates that SIDs should be mapped
2351
* to names. Without the plus sign, SIDs are not mapped;
2352
* rather they are simply converted to a string format.
2354
* @return 0 on success, < 0 on error with errno set:
2355
* - EINVAL The client library is not properly initialized
2356
* - ENOMEM No memory was available for internal needs
2357
* - EPERM Permission was denied.
2358
* - ENOTSUP The referenced file system does not support
2359
* extended attributes
2362
int smbc_lremovexattr(const char *url,
2366
/**@ingroup attribute
2367
* Remove extended attributes for a file. This is used for modifying a file's
2368
* security descriptor (i.e. owner, group, and access control list)
2370
* @param fd A file descriptor associated with an open file (as
2371
* previously returned by smbc_open(), to get extended
2374
* @param name The name of an attribute to be removed. Names are of
2375
* one of the following forms:
2377
* system.nt_sec_desc.<attribute name>
2378
* system.nt_sec_desc.*
2379
* system.nt_sec_desc.*+
2381
* where <attribute name> is one of:
2389
* acl+:<name or sid>
2391
* In the forms "system.nt_sec_desc.*" and
2392
* "system.nt_sec_desc.*+", the asterisk and plus signs are
2393
* literal, i.e. the string is provided exactly as shown, and
2394
* the value parameter will return a complete security
2395
* descriptor with name:value pairs separated by tabs,
2396
* commas, or newlines (not spaces!).
2398
* The plus sign ('+') indicates that SIDs should be mapped
2399
* to names. Without the plus sign, SIDs are not mapped;
2400
* rather they are simply converted to a string format.
2402
* @return 0 on success, < 0 on error with errno set:
2403
* - EINVAL The client library is not properly initialized
2404
* - ENOMEM No memory was available for internal needs
2405
* - EPERM Permission was denied.
2406
* - ENOTSUP The referenced file system does not support
2407
* extended attributes
2410
int smbc_fremovexattr(int fd,
2414
/**@ingroup attribute
2415
* List the supported extended attribute names associated with a file
2417
* @param url The smb url of the file or directory to list the extended
2420
* @param list A pointer to a buffer in which the list of attributes for
2421
* the specified file or directory will be placed (unless
2424
* @param size The size of the buffer pointed to by list. This parameter
2425
* may also be zero, in which case the size of the buffer
2426
* required to hold all of the attribute names will be
2427
* returned, but nothing will be placed into the list buffer.
2429
* @return 0 on success, < 0 on error with errno set:
2430
* - EINVAL The client library is not properly initialized
2431
* - ENOMEM No memory was available for internal needs
2432
* - EPERM Permission was denied.
2433
* - ENOTSUP The referenced file system does not support
2434
* extended attributes
2436
* @note This function always returns all attribute names supported
2437
* by NT file systems, regardless of whether the referenced
2438
* file system supports extended attributes (e.g. a Windows
2439
* 2000 machine supports extended attributes if NTFS is used,
2440
* but not if FAT is used, and Windows 98 doesn't support
2441
* extended attributes at all. Whether this is a feature or
2442
* a bug is yet to be decided.
2444
int smbc_listxattr(const char *url,
2448
/**@ingroup attribute
2449
* List the supported extended attribute names associated with a file The
2450
* POSIX function which this maps to would act on a symbolic link rather than
2451
* acting on what the symbolic link points to, but with no symbolic links in
2452
* SMB file systems, this function is functionally identical to
2455
* @param url The smb url of the file or directory to list the extended
2458
* @param list A pointer to a buffer in which the list of attributes for
2459
* the specified file or directory will be placed (unless
2462
* @param size The size of the buffer pointed to by list. This parameter
2463
* may also be zero, in which case the size of the buffer
2464
* required to hold all of the attribute names will be
2465
* returned, but nothing will be placed into the list buffer.
2467
* @return 0 on success, < 0 on error with errno set:
2468
* - EINVAL The client library is not properly initialized
2469
* - ENOMEM No memory was available for internal needs
2470
* - EPERM Permission was denied.
2471
* - ENOTSUP The referenced file system does not support
2472
* extended attributes
2474
* @note This function always returns all attribute names supported
2475
* by NT file systems, regardless of wether the referenced
2476
* file system supports extended attributes (e.g. a Windows
2477
* 2000 machine supports extended attributes if NTFS is used,
2478
* but not if FAT is used, and Windows 98 doesn't support
2479
* extended attributes at all. Whether this is a feature or
2480
* a bug is yet to be decided.
2482
int smbc_llistxattr(const char *url,
2486
/**@ingroup attribute
2487
* List the supported extended attribute names associated with a file
2489
* @param fd A file descriptor associated with an open file (as
2490
* previously returned by smbc_open(), to get extended
2493
* @param list A pointer to a buffer in which the list of attributes for
2494
* the specified file or directory will be placed (unless
2497
* @param size The size of the buffer pointed to by list. This parameter
2498
* may also be zero, in which case the size of the buffer
2499
* required to hold all of the attribute names will be
2500
* returned, but nothing will be placed into the list buffer.
2502
* @return 0 on success, < 0 on error with errno set:
2503
* - EINVAL The client library is not properly initialized
2504
* - ENOMEM No memory was available for internal needs
2505
* - EPERM Permission was denied.
2506
* - ENOTSUP The referenced file system does not support
2507
* extended attributes
2509
* @note This function always returns all attribute names supported
2510
* by NT file systems, regardless of wether the referenced
2511
* file system supports extended attributes (e.g. a Windows
2512
* 2000 machine supports extended attributes if NTFS is used,
2513
* but not if FAT is used, and Windows 98 doesn't support
2514
* extended attributes at all. Whether this is a feature or
2515
* a bug is yet to be decided.
2517
int smbc_flistxattr(int fd,
2522
* Print a file given the name in fname. It would be a URL ...
2524
* @param fname The URL of a file on a remote SMB server that the
2525
* caller wants printed
2527
* @param printq The URL of the print share to print the file to.
2529
* @return 0 on success, < 0 on error with errno set:
2531
* - EINVAL fname or printq was NULL or smbc_init not
2533
* and errors returned by smbc_open
2536
int smbc_print_file(const char *fname, const char *printq);
2539
* Open a print file that can be written to by other calls. This simply
2540
* does an smbc_open call after checking if there is a file name on the
2541
* URI. If not, a temporary name is added ...
2543
* @param fname The URL of the print share to print to?
2545
* @returns A file handle for the print file if successful.
2546
* Returns -1 if an error ocurred and errno has the values
2547
* - EINVAL fname was NULL or smbc_init not called.
2548
* - all errors returned by smbc_open
2551
int smbc_open_print_job(const char *fname);
2554
* List the print jobs on a print share, for the moment, pass a callback
2556
* @param purl The url of the print share to list the jobs of
2558
* @param fn Callback function the receives printjob info
2560
* @return 0 on success, < 0 on error with errno set:
2561
* - EINVAL fname was NULL or smbc_init not called
2564
int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2567
* Delete a print job
2569
* @param purl Url of the print share
2571
* @param id The id of the job to delete
2573
* @return 0 on success, < 0 on error with errno set:
2574
* - EINVAL fname was NULL or smbc_init not called
2576
* @todo what errno values are possible here?
2578
int smbc_unlink_print_job(const char *purl, int id);
2580
/**@ingroup callback
2581
* Remove a server from the cached server list it's unused.
2583
* @param context pointer to smb context
2585
* @param srv pointer to server to remove
2587
* @return On success, 0 is returned. 1 is returned if the server could not
2588
* be removed. Also useable outside libsmbclient.
2590
int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2596
/**@ingroup directory
2597
* Convert strings of %xx to their single character equivalent.
2599
* @param dest A pointer to a buffer in which the resulting decoded
2600
* string should be placed. This may be a pointer to the
2601
* same buffer as src_segment.
2603
* @param src A pointer to the buffer containing the URL to be decoded.
2604
* Any %xx sequences herein are converted to their single
2605
* character equivalent. Each 'x' must be a valid hexadecimal
2606
* digit, or that % sequence is left undecoded.
2608
* @param max_dest_len
2609
* The size of the buffer pointed to by dest_segment.
2611
* @return The number of % sequences which could not be converted
2612
* due to lack of two following hexadecimal digits.
2618
smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2625
* Convert any characters not specifically allowed in a URL into their %xx
2628
* @param dest A pointer to a buffer in which the resulting encoded
2629
* string should be placed. Unlike smbc_urldecode(), this
2630
* must be a buffer unique from src.
2632
* @param src A pointer to the buffer containing the string to be encoded.
2633
* Any character not specifically allowed in a URL is converted
2634
* into its hexadecimal value and encoded as %xx.
2636
* @param max_dest_len
2637
* The size of the buffer pointed to by dest_segment.
2639
* @returns The remaining buffer length.
2645
smbc_urlencode(char * dest, char * src, int max_dest_len);
2651
/**@ingroup directory
2652
* Return the version of the linked Samba code, and thus the version of the
2653
* libsmbclient code.
2655
* @return The version string.
2667
* Set the users credentials globally so they can be used for DFS
2668
* referrals. Probably best to use this function in the smbc_get_auth_data_fn
2671
* @param workgroup Workgroup of the user.
2673
* @param user Username of user.
2675
* @param password Password of user.
2677
* @param use_kerberos Whether to use Kerberos
2679
* @param signing_state One of these strings (all equivalents on same line):
2680
* "off", "no", "false"
2681
* "on", "yes", "true", "auto"
2682
* "force", "required", "forced"
2686
smbc_set_credentials(const char *workgroup,
2688
const char *password,
2689
smbc_bool use_kerberos,
2690
const char *signing_state);
2693
* Wrapper around smbc_set_credentials.
2694
* Used to set correct credentials that will
2695
* be used to connect to DFS target share
2700
smbc_set_credentials_with_fallback(SMBCCTX *ctx,
2701
const char *workgroup,
2703
const char *password);
2706
* @ingroup structure
2707
* Structure that contains a client context information
2708
* This structure is known as SMBCCTX
2710
* DO NOT DIRECTLY MANIPULATE THE CONTEXT STRUCTURE! The data in the context
2711
* structure should all be considered private to the library. It remains here
2712
* only for backward compatibility.
2714
* See the comments herein for use of the setter and getter functions which
2715
* should now be used for manipulating these values. New features, functions,
2716
* etc., are not added here but rather in _internal where they are not
2717
* directly visible to applications. This makes it much easier to maintain
2718
* ABI compatibility.
2726
* Use smbc_getDebug() and smbc_setDebug()
2728
int debug DEPRECATED_SMBC_INTERFACE;
2731
* netbios name used for making connections
2734
* Use smbc_getNetbiosName() and smbc_setNetbiosName()
2736
char * netbios_name DEPRECATED_SMBC_INTERFACE;
2739
* workgroup name used for making connections
2742
* Use smbc_getWorkgroup() and smbc_setWorkgroup()
2744
char * workgroup DEPRECATED_SMBC_INTERFACE;
2747
* username used for making connections
2750
* Use smbc_getUser() and smbc_setUser()
2752
char * user DEPRECATED_SMBC_INTERFACE;
2755
* timeout used for waiting on connections / response data (in
2759
* Use smbc_getTimeout() and smbc_setTimeout()
2761
int timeout DEPRECATED_SMBC_INTERFACE;
2764
* callable functions for files:
2765
* For usage and return values see the SMBC_* functions
2769
* Use smbc_getFunction*() and smbc_setFunction*(), e.g.
2770
* smbc_getFunctionOpen(), smbc_setFunctionUnlink(), etc.
2772
smbc_open_fn open DEPRECATED_SMBC_INTERFACE;
2773
smbc_creat_fn creat DEPRECATED_SMBC_INTERFACE;
2774
smbc_read_fn read DEPRECATED_SMBC_INTERFACE;
2775
smbc_write_fn write DEPRECATED_SMBC_INTERFACE;
2776
smbc_unlink_fn unlink DEPRECATED_SMBC_INTERFACE;
2777
smbc_rename_fn rename DEPRECATED_SMBC_INTERFACE;
2778
smbc_lseek_fn lseek DEPRECATED_SMBC_INTERFACE;
2779
smbc_stat_fn stat DEPRECATED_SMBC_INTERFACE;
2780
smbc_fstat_fn fstat DEPRECATED_SMBC_INTERFACE;
2781
#if 0 /* internal */
2782
smbc_ftruncate_fn ftruncate_fn;
2784
smbc_close_fn close_fn DEPRECATED_SMBC_INTERFACE;
2785
smbc_opendir_fn opendir DEPRECATED_SMBC_INTERFACE;
2786
smbc_closedir_fn closedir DEPRECATED_SMBC_INTERFACE;
2787
smbc_readdir_fn readdir DEPRECATED_SMBC_INTERFACE;
2788
smbc_getdents_fn getdents DEPRECATED_SMBC_INTERFACE;
2789
smbc_mkdir_fn mkdir DEPRECATED_SMBC_INTERFACE;
2790
smbc_rmdir_fn rmdir DEPRECATED_SMBC_INTERFACE;
2791
smbc_telldir_fn telldir DEPRECATED_SMBC_INTERFACE;
2792
smbc_lseekdir_fn lseekdir DEPRECATED_SMBC_INTERFACE;
2793
smbc_fstatdir_fn fstatdir DEPRECATED_SMBC_INTERFACE;
2794
smbc_chmod_fn chmod DEPRECATED_SMBC_INTERFACE;
2795
smbc_utimes_fn utimes DEPRECATED_SMBC_INTERFACE;
2796
smbc_setxattr_fn setxattr DEPRECATED_SMBC_INTERFACE;
2797
smbc_getxattr_fn getxattr DEPRECATED_SMBC_INTERFACE;
2798
smbc_removexattr_fn removexattr DEPRECATED_SMBC_INTERFACE;
2799
smbc_listxattr_fn listxattr DEPRECATED_SMBC_INTERFACE;
2801
/* Printing-related functions */
2802
smbc_print_file_fn print_file DEPRECATED_SMBC_INTERFACE;
2803
smbc_open_print_job_fn open_print_job DEPRECATED_SMBC_INTERFACE;
2804
smbc_list_print_jobs_fn list_print_jobs DEPRECATED_SMBC_INTERFACE;
2805
smbc_unlink_print_job_fn unlink_print_job DEPRECATED_SMBC_INTERFACE;
2812
* See the comment above each field, for the getter and setter
2813
* functions that should now be used.
2815
struct _smbc_callbacks
2818
* authentication function callback: called upon auth requests
2821
* Use smbc_getFunctionAuthData(), smbc_setFunctionAuthData()
2823
smbc_get_auth_data_fn auth_fn DEPRECATED_SMBC_INTERFACE;
2826
* check if a server is still good
2829
* Use smbc_getFunctionCheckServer(),
2830
* smbc_setFunctionCheckServer()
2832
smbc_check_server_fn check_server_fn DEPRECATED_SMBC_INTERFACE;
2835
* remove a server if unused
2838
* Use smbc_getFunctionRemoveUnusedServer(),
2839
* smbc_setFunctionCheckServer()
2841
smbc_remove_unused_server_fn remove_unused_server_fn DEPRECATED_SMBC_INTERFACE;
2845
* For an example cache system see
2846
* samba/source/libsmb/libsmb_cache.c
2848
* Cache subsystem * functions follow.
2852
* server cache addition
2855
* Use smbc_getFunctionAddCachedServer(),
2856
* smbc_setFunctionAddCachedServer()
2858
smbc_add_cached_srv_fn add_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2861
* server cache lookup
2864
* Use smbc_getFunctionGetCachedServer(),
2865
* smbc_setFunctionGetCachedServer()
2867
smbc_get_cached_srv_fn get_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2870
* server cache removal
2873
* Use smbc_getFunctionRemoveCachedServer(),
2874
* smbc_setFunctionRemoveCachedServer()
2876
smbc_remove_cached_srv_fn remove_cached_srv_fn DEPRECATED_SMBC_INTERFACE;
2879
* server cache purging, try to remove all cached servers
2883
* Use smbc_getFunctionPurgeCachedServers(),
2884
* smbc_setFunctionPurgeCachedServers()
2886
smbc_purge_cached_fn purge_cached_fn DEPRECATED_SMBC_INTERFACE;
2890
* Space where the private data of the server cache used to be
2893
* Use smbc_getServerCacheData(), smbc_setServerCacheData()
2895
void * reserved DEPRECATED_SMBC_INTERFACE;
2898
* Very old configuration options.
2901
* Use one of the following functions instead:
2902
* smbc_setOptionUseKerberos()
2903
* smbc_getOptionUseKerberos()
2904
* smbc_setOptionFallbackAfterKerberos()
2905
* smbc_getOptionFallbackAfterKerberos()
2906
* smbc_setOptionNoAutoAnonymousLogin()
2907
* smbc_getOptionNoAutoAnonymousLogin()
2909
int flags DEPRECATED_SMBC_INTERFACE;
2912
* user options selections that apply to this session
2914
* NEW OPTIONS ARE NOT ADDED HERE!
2917
* To set and retrieve options, use the smbc_setOption*() and
2918
* smbc_getOption*() functions.
2920
struct _smbc_options {
2921
int browse_max_lmb_count DEPRECATED_SMBC_INTERFACE;
2922
int urlencode_readdir_entries DEPRECATED_SMBC_INTERFACE;
2923
int one_share_per_server DEPRECATED_SMBC_INTERFACE;
2924
} options DEPRECATED_SMBC_INTERFACE;
2927
* do _NOT_ touch this from your program !
2929
struct SMBC_internal_data * internal;
2933
#endif /* SMBCLIENT_H_INCLUDED */
added
removed
source3/include/libsmbclient.h
