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
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
32 /*-------------------------------------------------------------------*/
33 /* The following are special comments to instruct DOXYGEN (automated
36 /** \defgroup libsmbclient
38 /** \defgroup structure Data Structures Type and Constants
39 * \ingroup libsmbclient
40 * Data structures, types, and constants
42 /** \defgroup callback Callback function types
43 * \ingroup libsmbclient
46 /** \defgroup file File Functions
47 * \ingroup libsmbclient
48 * Functions used to access individual file contents
50 /** \defgroup directory Directory Functions
51 * \ingroup libsmbclient
52 * Functions used to access directory entries
54 /** \defgroup attribute Attributes Functions
55 * \ingroup libsmbclient
56 * Functions used to view or change file and directory attributes
58 /** \defgroup print Print Functions
59 * \ingroup libsmbclient
60 * Functions used to access printing functionality
62 /** \defgroup misc Miscellaneous Functions
63 * \ingroup libsmbclient
64 * Functions that don't fit in to other categories
66 /*-------------------------------------------------------------------*/
68 /* Make sure we have the following includes for now ... */
69 #include <sys/types.h>
74 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
76 #define SMBC_WORKGROUP 1
78 #define SMBC_FILE_SHARE 3
79 #define SMBC_PRINTER_SHARE 4
80 #define SMBC_COMMS_SHARE 5
81 #define SMBC_IPC_SHARE 6
87 * Structure that represents a directory entry.
102 unsigned int smbc_type
;
104 /** Length of this smbc_dirent in bytes
107 /** The length of the comment string in bytes (does not include
110 unsigned int commentlen
;
111 /** Points to the null terminated comment string
114 /** The length of the name string in bytes (does not include
117 unsigned int namelen
;
118 /** Points to the null terminated name string
124 * Flags for smbc_setxattr()
125 * Specify a bitwise OR of these, or 0 to add or replace as necessary
127 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
128 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
132 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
133 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
134 * "system.*") is specified.
136 #define SMBC_DOS_MODE_READONLY 0x01
137 #define SMBC_DOS_MODE_HIDDEN 0x02
138 #define SMBC_DOS_MODE_SYSTEM 0x04
139 #define SMBC_DOS_MODE_VOLUME_ID 0x08
140 #define SMBC_DOS_MODE_DIRECTORY 0x10
141 #define SMBC_DOS_MODE_ARCHIVE 0x20
144 * Valid values for the option "open_share_mode", when calling
147 typedef enum smbc_share_mode
149 SMBC_SHAREMODE_DENY_DOS
= 0,
150 SMBC_SHAREMODE_DENY_ALL
= 1,
151 SMBC_SHAREMODE_DENY_WRITE
= 2,
152 SMBC_SHAREMODE_DENY_READ
= 3,
153 SMBC_SHAREMODE_DENY_NONE
= 4,
154 SMBC_SHAREMODE_DENY_FCB
= 7
159 # define ENOATTR ENOENT /* No such attribute */
165 /**@ingroup structure
166 * Structure that represents a print job.
170 struct print_job_info
172 /** numeric ID of the print job
176 /** represents print job priority (lower numbers mean higher priority)
178 unsigned short priority
;
180 /** Size of the print job
184 /** Name of the user that owns the print job
188 /** Name of the print job. This will have no name if an anonymous print
189 * file was opened. Ie smb://server/printer
193 /** Time the print job was spooled
197 #endif /* _CLIENT_H */
200 /**@ingroup structure
203 typedef struct _SMBCSRV SMBCSRV
;
205 /**@ingroup structure
206 * File or directory handle
208 typedef struct _SMBCFILE SMBCFILE
;
210 /**@ingroup structure
211 * File or directory handle
213 typedef struct _SMBCCTX SMBCCTX
;
220 * Authentication callback function type (traditional method)
222 * Type for the the authentication function called by the library to
223 * obtain authentication credentals
225 * @param srv Server being authenticated to
227 * @param shr Share being authenticated to
229 * @param wg Pointer to buffer containing a "hint" for the
230 * workgroup to be authenticated. Should be filled in
231 * with the correct workgroup if the hint is wrong.
233 * @param wglen The size of the workgroup buffer in bytes
235 * @param un Pointer to buffer containing a "hint" for the
236 * user name to be use for authentication. Should be
237 * filled in with the correct workgroup if the hint is
240 * @param unlen The size of the username buffer in bytes
242 * @param pw Pointer to buffer containing to which password
245 * @param pwlen The size of the password buffer in bytes
248 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
252 char *pw
, int pwlen
);
254 * Authentication callback function type (method that includes context)
256 * Type for the the authentication function called by the library to
257 * obtain authentication credentals
259 * @param c Pointer to the smb context
261 * @param srv Server being authenticated to
263 * @param shr Share being authenticated to
265 * @param wg Pointer to buffer containing a "hint" for the
266 * workgroup to be authenticated. Should be filled in
267 * with the correct workgroup if the hint is wrong.
269 * @param wglen The size of the workgroup buffer in bytes
271 * @param un Pointer to buffer containing a "hint" for the
272 * user name to be use for authentication. Should be
273 * filled in with the correct workgroup if the hint is
276 * @param unlen The size of the username buffer in bytes
278 * @param pw Pointer to buffer containing to which password
281 * @param pwlen The size of the password buffer in bytes
284 typedef void (*smbc_get_auth_data_with_context_fn
)(SMBCCTX
*c
,
289 char *pw
, int pwlen
);
293 * Print job info callback function type.
295 * @param i pointer to print job information structure
298 typedef void (*smbc_list_print_job_fn
)(struct print_job_info
*i
);
302 * Check if a server is still good
304 * @param c pointer to smb context
306 * @param srv pointer to server to check
308 * @return 0 when connection is good. 1 on error.
311 typedef int (*smbc_check_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
314 * Remove a server if unused
316 * @param c pointer to smb context
318 * @param srv pointer to server to remove
320 * @return 0 on success. 1 on failure.
323 typedef int (*smbc_remove_unused_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
327 * Add a server to the cache system
329 * @param c pointer to smb context
331 * @param srv pointer to server to add
333 * @param server server name
335 * @param share share name
337 * @param workgroup workgroup used to connect
339 * @param username username used to connect
341 * @return 0 on success. 1 on failure.
344 typedef int (*smbc_add_cached_srv_fn
) (SMBCCTX
* c
, SMBCSRV
*srv
,
345 const char * server
, const char * share
,
346 const char * workgroup
, const char * username
);
349 * Look up a server in the cache system
351 * @param c pointer to smb context
353 * @param server server name to match
355 * @param share share name to match
357 * @param workgroup workgroup to match
359 * @param username username to match
361 * @return pointer to SMBCSRV on success. NULL on failure.
364 typedef SMBCSRV
* (*smbc_get_cached_srv_fn
) (SMBCCTX
* c
, const char * server
,
365 const char * share
, const char * workgroup
,
366 const char * username
);
369 * Check if a server is still good
371 * @param c pointer to smb context
373 * @param srv pointer to server to remove
375 * @return 0 when found and removed. 1 on failure.
378 typedef int (*smbc_remove_cached_srv_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
382 * Try to remove all servers from the cache system and disconnect
384 * @param c pointer to smb context
386 * @return 0 when found and removed. 1 on failure.
389 typedef int (*smbc_purge_cached_fn
) (SMBCCTX
* c
);
392 /**@ingroup structure
393 * Structure that contains a client context information
394 * This structure is know as SMBCCTX
401 /** netbios name used for making connections
405 /** workgroup name used for making connections
409 /** username used for making connections
413 /** timeout used for waiting on connections / response data (in milliseconds)
417 /** callable functions for files:
418 * For usage and return values see the smbc_* functions
420 SMBCFILE
* (*open
) (SMBCCTX
*c
, const char *fname
, int flags
, mode_t mode
);
421 SMBCFILE
* (*creat
) (SMBCCTX
*c
, const char *path
, mode_t mode
);
422 ssize_t (*read
) (SMBCCTX
*c
, SMBCFILE
*file
, void *buf
, size_t count
);
423 ssize_t (*write
) (SMBCCTX
*c
, SMBCFILE
*file
, void *buf
, size_t count
);
424 int (*unlink
) (SMBCCTX
*c
, const char *fname
);
425 int (*rename
) (SMBCCTX
*ocontext
, const char *oname
,
426 SMBCCTX
*ncontext
, const char *nname
);
427 off_t (*lseek
) (SMBCCTX
*c
, SMBCFILE
* file
, off_t offset
, int whence
);
428 int (*stat
) (SMBCCTX
*c
, const char *fname
, struct stat
*st
);
429 int (*fstat
) (SMBCCTX
*c
, SMBCFILE
*file
, struct stat
*st
);
430 int (*close_fn
) (SMBCCTX
*c
, SMBCFILE
*file
);
432 /** callable functions for dirs
434 SMBCFILE
* (*opendir
) (SMBCCTX
*c
, const char *fname
);
435 int (*closedir
)(SMBCCTX
*c
, SMBCFILE
*dir
);
436 struct smbc_dirent
* (*readdir
)(SMBCCTX
*c
, SMBCFILE
*dir
);
437 int (*getdents
)(SMBCCTX
*c
, SMBCFILE
*dir
,
438 struct smbc_dirent
*dirp
, int count
);
439 int (*mkdir
) (SMBCCTX
*c
, const char *fname
, mode_t mode
);
440 int (*rmdir
) (SMBCCTX
*c
, const char *fname
);
441 off_t (*telldir
) (SMBCCTX
*c
, SMBCFILE
*dir
);
442 int (*lseekdir
)(SMBCCTX
*c
, SMBCFILE
*dir
, off_t offset
);
443 int (*fstatdir
)(SMBCCTX
*c
, SMBCFILE
*dir
, struct stat
*st
);
444 int (*chmod
)(SMBCCTX
*c
, const char *fname
, mode_t mode
);
445 int (*utimes
)(SMBCCTX
*c
,
446 const char *fname
, struct timeval
*tbuf
);
447 int (*setxattr
)(SMBCCTX
*context
,
453 int (*getxattr
)(SMBCCTX
*context
,
458 int (*removexattr
)(SMBCCTX
*context
,
461 int (*listxattr
)(SMBCCTX
*context
,
466 /** callable functions for printing
468 int (*print_file
)(SMBCCTX
*c_file
, const char *fname
,
469 SMBCCTX
*c_print
, const char *printq
);
470 SMBCFILE
* (*open_print_job
)(SMBCCTX
*c
, const char *fname
);
471 int (*list_print_jobs
)(SMBCCTX
*c
, const char *fname
, smbc_list_print_job_fn fn
);
472 int (*unlink_print_job
)(SMBCCTX
*c
, const char *fname
, int id
);
477 * These callbacks _always_ have to be initialized because they will
478 * not be checked at dereference for increased speed.
480 struct _smbc_callbacks
{
481 /** authentication function callback: called upon auth requests
483 smbc_get_auth_data_fn auth_fn
;
485 /** check if a server is still good
487 smbc_check_server_fn check_server_fn
;
489 /** remove a server if unused
491 smbc_remove_unused_server_fn remove_unused_server_fn
;
494 * For an example cache system see samba/source/libsmb/libsmb_cache.c
495 * Cache subsystem functions follow.
498 /** server cache addition
500 smbc_add_cached_srv_fn add_cached_srv_fn
;
502 /** server cache lookup
504 smbc_get_cached_srv_fn get_cached_srv_fn
;
506 /** server cache removal
508 smbc_remove_cached_srv_fn remove_cached_srv_fn
;
510 /** server cache purging, try to remove all cached servers (disconnect)
512 smbc_purge_cached_fn purge_cached_fn
;
516 /** Space to store private data of the server cache.
518 struct smbc_server_cache
* server_cache
;
522 /** user options selections that apply to this session
524 struct _smbc_options
{
527 * From how many local master browsers should the list of
528 * workgroups be retrieved? It can take up to 12 minutes or
529 * longer after a server becomes a local master browser, for
530 * it to have the entire browse list (the list of
531 * workgroups/domains) from an entire network. Since a client
532 * never knows which local master browser will be found first,
533 * the one which is found first and used to retrieve a browse
534 * list may have an incomplete or empty browse list. By
535 * requesting the browse list from multiple local master
536 * browsers, a more complete list can be generated. For small
537 * networks (few workgroups), it is recommended that this
538 * value be set to 0, causing the browse lists from all found
539 * local master browsers to be retrieved and merged. For
540 * networks with many workgroups, a suitable value for this
541 * variable is probably somewhere around 3. (Default: 3).
543 int browse_max_lmb_count
;
546 * There is a difference in the desired return strings from
547 * smbc_readdir() depending upon whether the filenames are to
548 * be displayed to the user, or whether they are to be
549 * appended to the path name passed to smbc_opendir() to call
550 * a further smbc_ function (e.g. open the file with
551 * smbc_open()). In the former case, the filename should be
552 * in "human readable" form. In the latter case, the smbc_
553 * functions expect a URL which must be url-encoded. Those
554 * functions decode the URL. If, for example, smbc_readdir()
555 * returned a file name of "abc%20def.txt", passing a path
556 * with this file name attached to smbc_open() would cause
557 * smbc_open to attempt to open the file "abc def.txt" since
558 * the %20 is decoded into a space.
560 * Set this option to True if the names returned by
561 * smbc_readdir() should be url-encoded such that they can be
562 * passed back to another smbc_ call. Set it to False if the
563 * names returned by smbc_readdir() are to be presented to the
566 * For backwards compatibility, this option defaults to False.
568 int urlencode_readdir_entries
;
571 * Some Windows versions appear to have a limit to the number
572 * of concurrent SESSIONs and/or TREE CONNECTions. In
573 * one-shot programs (i.e. the program runs and then quickly
574 * ends, thereby shutting down all connections), it is
575 * probably reasonable to establish a new connection for each
576 * share. In long-running applications, the limitation can be
577 * avoided by using only a single connection to each server,
578 * and issuing a new TREE CONNECT when the share is accessed.
580 int one_share_per_server
;
584 * do _NOT_ touch this from your program !
586 struct smbc_internal_data
* internal
;
589 /* Flags for SMBCCTX->flags */
590 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
591 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
592 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
595 * Create a new SBMCCTX (a context).
597 * Must be called before the context is passed to smbc_context_init()
599 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
600 * - ENOMEM Out of memory
602 * @see smbc_free_context(), smbc_init_context()
604 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
606 SMBCCTX
* smbc_new_context(void);
609 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
611 * The context will be deleted if possible.
613 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
615 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
618 * @return Returns 0 on succes. Returns 1 on failure with errno set:
619 * - EBUSY Server connections are still used, Files are open or cache
620 * could not be purged
621 * - EBADF context == NULL
623 * @see smbc_new_context()
625 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
626 * just before exit()'ing. When shutdown_ctx is 0, this function can be
627 * use in periodical cleanup functions for example.
629 int smbc_free_context(SMBCCTX
* context
, int shutdown_ctx
);
633 * Each time the context structure is changed, we have binary backward
634 * compatibility issues. Instead of modifying the public portions of the
635 * context structure to add new options, instead, we put them in the internal
636 * portion of the context structure and provide a set function for these new
639 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
642 * The name of the option for which the value is to be set
644 * @param option_value
645 * The new value of the option being set
649 smbc_option_set(SMBCCTX
*context
,
651 ... /* option_value */);
653 * Retrieve the current value of an option
655 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
658 * The name of the option for which the value is to be
661 * @return The value of the specified option.
664 smbc_option_get(SMBCCTX
*context
,
668 * Initialize a SBMCCTX (a context).
670 * Must be called before using any SMBCCTX API function
672 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
674 * @return A pointer to the given SMBCCTX on success,
675 * NULL on error with errno set:
676 * - EBADF NULL context given
677 * - ENOMEM Out of memory
678 * - ENOENT The smb.conf file would not load
680 * @see smbc_new_context()
682 * @note my_context = smbc_init_context(smbc_new_context())
683 * is perfectly safe, but it might leak memory on
684 * smbc_context_init() failure. Avoid this.
685 * You'll have to call smbc_free_context() yourself
689 SMBCCTX
* smbc_init_context(SMBCCTX
* context
);
692 * Initialize the samba client library.
694 * Must be called before using any of the smbclient API function
696 * @param fn The function that will be called to obtaion
697 * authentication credentials.
699 * @param debug Allows caller to set the debug level. Can be
700 * changed in smb.conf file. Allows caller to set
701 * debugging if no smb.conf.
703 * @return 0 on success, < 0 on error with errno set:
704 * - ENOMEM Out of memory
705 * - ENOENT The smb.conf file would not load
709 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
712 * Set or retrieve the compatibility library's context pointer
714 * @param context New context to use, or NULL. If a new context is provided,
715 * it must have allocated with smbc_new_context() and
716 * initialized with smbc_init_context(), followed, optionally,
717 * by some manual changes to some of the non-internal fields.
719 * @return The old context.
721 * @see smbc_new_context(), smbc_init_context(), smbc_init()
723 * @note This function may be called prior to smbc_init() to force
724 * use of the next context without any internal calls to
725 * smbc_new_context() or smbc_init_context(). It may also
726 * be called after smbc_init() has already called those two
727 * functions, to replace the existing context with a new one.
728 * Care should be taken, in this latter case, to ensure that
729 * the server cache and any data allocated by the
730 * authentication functions have been freed, if necessary.
733 SMBCCTX
* smbc_set_context(SMBCCTX
* new_context
);
736 * Open a file on an SMB server.
738 * @param furl The smb url of the file to be opened.
740 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
741 * request opening the file read-only,write-only
742 * or read/write. flags may also be bitwise-or'd with
743 * one or more of the following:
744 * O_CREAT - If the file does not exist it will be
746 * O_EXCL - When used with O_CREAT, if the file
747 * already exists it is an error and the open will
749 * O_TRUNC - If the file already exists it will be
751 * O_APPEND The file is opened in append mode
753 * @param mode mode specifies the permissions to use if a new
754 * file is created. It is modified by the
755 * process's umask in the usual way: the permissions
756 * of the created file are (mode & ~umask)
758 * Not currently use, but there for future use.
759 * We will map this to SYSTEM, HIDDEN, etc bits
760 * that reverses the mapping that smbc_fstat does.
762 * @return Valid file handle, < 0 on error with errno set:
763 * - ENOMEM Out of memory
764 * - EINVAL if an invalid parameter passed, like no
765 * file, or smbc_init not called.
766 * - EEXIST pathname already exists and O_CREAT and
768 * - EISDIR pathname refers to a directory and
769 * the access requested involved writing.
770 * - EACCES The requested access to the file is not
772 * - ENODEV The requested share does not exist
773 * - ENOTDIR A file on the path is not a directory
774 * - ENOENT A directory component in pathname does
779 * @note This call uses an underlying routine that may create
780 * a new connection to the server specified in the URL.
781 * If the credentials supplied in the URL, or via the
782 * auth_fn in the smbc_init call, fail, this call will
783 * try again with an empty username and password. This
784 * often gets mapped to the guest account on some machines.
787 int smbc_open(const char *furl
, int flags
, mode_t mode
);
790 * Create a file on an SMB server.
792 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
794 * @param furl The smb url of the file to be created
796 * @param mode mode specifies the permissions to use if a new
797 * file is created. It is modified by the
798 * process's umask in the usual way: the permissions
799 * of the created file are (mode & ~umask)
801 * NOTE, the above is not true. We are dealing with
802 * an SMB server, which has no concept of a umask!
804 * @return Valid file handle, < 0 on error with errno set:
805 * - ENOMEM Out of memory
806 * - EINVAL if an invalid parameter passed, like no
807 * file, or smbc_init not called.
808 * - EEXIST pathname already exists and O_CREAT and
810 * - EISDIR pathname refers to a directory and
811 * the access requested involved writing.
812 * - EACCES The requested access to the file is not
814 * - ENOENT A directory component in pathname does
816 * - ENODEV The requested share does not exist.
821 int smbc_creat(const char *furl
, mode_t mode
);
824 * Read from a file using an opened file handle.
826 * @param fd Open file handle from smbc_open() or smbc_creat()
828 * @param buf Pointer to buffer to recieve read data
830 * @param bufsize Size of buf in bytes
832 * @return Number of bytes read, < 0 on error with errno set:
833 * - EISDIR fd refers to a directory
834 * - EBADF fd is not a valid file descriptor or
835 * is not open for reading.
836 * - EINVAL fd is attached to an object which is
837 * unsuitable for reading, or no buffer passed or
838 * smbc_init not called.
840 * @see smbc_open(), smbc_write()
843 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
847 * Write to a file using an opened file handle.
849 * @param fd Open file handle from smbc_open() or smbc_creat()
851 * @param buf Pointer to buffer to recieve read data
853 * @param bufsize Size of buf in bytes
855 * @return Number of bytes written, < 0 on error with errno set:
856 * - EISDIR fd refers to a directory.
857 * - EBADF fd is not a valid file descriptor or
858 * is not open for reading.
859 * - EINVAL fd is attached to an object which is
860 * unsuitable for reading, or no buffer passed or
861 * smbc_init not called.
863 * @see smbc_open(), smbc_read()
866 ssize_t
smbc_write(int fd
, void *buf
, size_t bufsize
);
870 * Seek to a specific location in a file.
872 * @param fd Open file handle from smbc_open() or smbc_creat()
874 * @param offset Offset in bytes from whence
876 * @param whence A location in the file:
877 * - SEEK_SET The offset is set to offset bytes from
878 * the beginning of the file
879 * - SEEK_CUR The offset is set to current location
881 * - SEEK_END The offset is set to the size of the
882 * file plus offset bytes.
884 * @return Upon successful completion, lseek returns the
885 * resulting offset location as measured in bytes
886 * from the beginning of the file. Otherwise, a value
887 * of (off_t)-1 is returned and errno is set to
888 * indicate the error:
889 * - EBADF Fildes is not an open file descriptor.
890 * - EINVAL Whence is not a proper value or smbc_init
893 * @todo Are all the whence values really supported?
895 * @todo Are errno values complete and correct?
897 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
901 * Close an open file handle.
903 * @param fd The file handle to close
905 * @return 0 on success, < 0 on error with errno set:
906 * - EBADF fd isn't a valid open file descriptor
907 * - EINVAL smbc_init() failed or has not been called
909 * @see smbc_open(), smbc_creat()
911 int smbc_close(int fd
);
914 /**@ingroup directory
915 * Unlink (delete) a file or directory.
917 * @param furl The smb url of the file to delete
919 * @return 0 on success, < 0 on error with errno set:
920 * - EACCES or EPERM Write access to the directory
921 * containing pathname is not allowed or one
922 * of the directories in pathname did not allow
923 * search (execute) permission
924 * - ENOENT A directory component in pathname does
926 * - EINVAL NULL was passed in the file param or
927 * smbc_init not called.
928 * - EACCES You do not have access to the file
929 * - ENOMEM Insufficient kernel memory was available
933 * @todo Are errno values complete and correct?
935 int smbc_unlink(const char *furl
);
938 /**@ingroup directory
939 * Rename or move a file or directory.
941 * @param ourl The original smb url (source url) of file or
942 * directory to be moved
944 * @param nurl The new smb url (destination url) of the file
945 * or directory after the move. Currently nurl must
946 * be on the same share as ourl.
948 * @return 0 on success, < 0 on error with errno set:
949 * - EISDIR nurl is an existing directory, but ourl is
951 * - EEXIST nurl is a non-empty directory,
952 * i.e., contains entries other than "." and ".."
953 * - EINVAL The new url contained a path prefix
954 * of the old, or, more generally, an attempt was
955 * made to make a directory a subdirectory of itself
956 * or smbc_init not called.
957 * - ENOTDIR A component used as a directory in ourl
958 * or nurl path is not, in fact, a directory. Or,
959 * ourl is a directory, and newpath exists but is not
961 * - EACCES or EPERM Write access to the directory
962 * containing ourl or nurl is not allowed for the
963 * process's effective uid, or one of the
964 * directories in ourl or nurl did not allow search
965 * (execute) permission, or ourl was a directory
966 * and did not allow write permission.
967 * - ENOENT A directory component in ourl or nurl
969 * - EXDEV Rename across shares not supported.
970 * - ENOMEM Insufficient kernel memory was available.
971 * - EEXIST The target file, nurl, already exists.
974 * @todo Are we going to support copying when urls are not on the same
975 * share? I say no... NOTE. I agree for the moment.
978 int smbc_rename(const char *ourl
, const char *nurl
);
981 /**@ingroup directory
982 * Open a directory used to obtain directory entries.
984 * @param durl The smb url of the directory to open
986 * @return Valid directory handle. < 0 on error with errno set:
987 * - EACCES Permission denied.
988 * - EINVAL A NULL file/URL was passed, or the URL would
989 * not parse, or was of incorrect form or smbc_init not
991 * - ENOENT durl does not exist, or name is an
992 * - ENOMEM Insufficient memory to complete the
994 * - ENOTDIR name is not a directory.
995 * - EPERM the workgroup could not be found.
996 * - ENODEV the workgroup or server could not be found.
998 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
1001 int smbc_opendir(const char *durl
);
1004 /**@ingroup directory
1005 * Close a directory handle opened by smbc_opendir().
1007 * @param dh Directory handle to close
1009 * @return 0 on success, < 0 on error with errno set:
1010 * - EBADF dh is an invalid directory handle
1012 * @see smbc_opendir()
1014 int smbc_closedir(int dh
);
1017 /**@ingroup directory
1018 * Get multiple directory entries.
1020 * smbc_getdents() reads as many dirent structures from the an open
1021 * directory handle into a specified memory area as will fit.
1023 * @param dh Valid directory as returned by smbc_opendir()
1025 * @param dirp pointer to buffer that will receive the directory
1028 * @param count The size of the dirp buffer in bytes
1030 * @returns If any dirents returned, return will indicate the
1031 * total size. If there were no more dirents available,
1032 * 0 is returned. < 0 indicates an error.
1033 * - EBADF Invalid directory handle
1034 * - EINVAL Result buffer is too small or smbc_init
1036 * - ENOENT No such directory.
1037 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1039 * @todo Are errno values complete and correct?
1041 * @todo Add example code so people know how to parse buffers.
1043 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
1046 /**@ingroup directory
1047 * Get a single directory entry.
1049 * @param dh Valid directory as returned by smbc_opendir()
1051 * @return A pointer to a smbc_dirent structure, or NULL if an
1052 * error occurs or end-of-directory is reached:
1053 * - EBADF Invalid directory handle
1054 * - EINVAL smbc_init() failed or has not been called
1056 * @see smbc_dirent, smbc_getdents(), smbc_open()
1058 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
1061 /**@ingroup directory
1062 * Get the current directory offset.
1064 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1067 * @param dh Valid directory as returned by smbc_opendir()
1069 * @return The current location in the directory stream or -1
1070 * if an error occur. The current location is not
1071 * an offset. Becuase of the implementation, it is a
1072 * handle that allows the library to find the entry
1074 * - EBADF dh is not a valid directory handle
1075 * - EINVAL smbc_init() failed or has not been called
1076 * - ENOTDIR if dh is not a directory
1078 * @see smbc_readdir()
1081 off_t
smbc_telldir(int dh
);
1084 /**@ingroup directory
1085 * lseek on directories.
1087 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1088 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1090 * @param fd Valid directory as returned by smbc_opendir()
1092 * @param offset The offset (as returned by smbc_telldir). Can be
1093 * NULL, in which case we will rewind
1095 * @return 0 on success, -1 on failure
1096 * - EBADF dh is not a valid directory handle
1097 * - ENOTDIR if dh is not a directory
1098 * - EINVAL offset did not refer to a valid dirent or
1099 * smbc_init not called.
1101 * @see smbc_telldir()
1104 * @todo In what does the reture and errno values mean?
1106 int smbc_lseekdir(int fd
, off_t offset
);
1108 /**@ingroup directory
1109 * Create a directory.
1111 * @param durl The url of the directory to create
1113 * @param mode Specifies the permissions to use. It is modified
1114 * by the process's umask in the usual way: the
1115 * permissions of the created file are (mode & ~umask).
1117 * @return 0 on success, < 0 on error with errno set:
1118 * - EEXIST directory url already exists
1119 * - EACCES The parent directory does not allow write
1120 * permission to the process, or one of the directories
1121 * - ENOENT A directory component in pathname does not
1123 * - EINVAL NULL durl passed or smbc_init not called.
1124 * - ENOMEM Insufficient memory was available.
1129 int smbc_mkdir(const char *durl
, mode_t mode
);
1132 /**@ingroup directory
1133 * Remove a directory.
1135 * @param durl The smb url of the directory to remove
1137 * @return 0 on success, < 0 on error with errno set:
1138 * - EACCES or EPERM Write access to the directory
1139 * containing pathname was not allowed.
1140 * - EINVAL durl is NULL or smbc_init not called.
1141 * - ENOENT A directory component in pathname does not
1143 * - ENOTEMPTY directory contains entries.
1144 * - ENOMEM Insufficient kernel memory was available.
1146 * @see smbc_mkdir(), smbc_unlink()
1148 * @todo Are errno values complete and correct?
1150 int smbc_rmdir(const char *durl
);
1153 /**@ingroup attribute
1154 * Get information about a file or directory.
1156 * @param url The smb url to get information for
1158 * @param st pointer to a buffer that will be filled with
1159 * standard Unix struct stat information.
1161 * @return 0 on success, < 0 on error with errno set:
1162 * - ENOENT A component of the path file_name does not
1164 * - EINVAL a NULL url was passed or smbc_init not called.
1165 * - EACCES Permission denied.
1166 * - ENOMEM Out of memory
1167 * - ENOTDIR The target dir, url, is not a directory.
1172 int smbc_stat(const char *url
, struct stat
*st
);
1175 /**@ingroup attribute
1176 * Get file information via an file descriptor.
1178 * @param fd Open file handle from smbc_open() or smbc_creat()
1180 * @param st pointer to a buffer that will be filled with
1181 * standard Unix struct stat information.
1183 * @return EBADF filedes is bad.
1184 * - EACCES Permission denied.
1185 * - EBADF fd is not a valid file descriptor
1186 * - EINVAL Problems occurred in the underlying routines
1187 * or smbc_init not called.
1188 * - ENOMEM Out of memory
1190 * @see smbc_stat(), Unix stat()
1193 int smbc_fstat(int fd
, struct stat
*st
);
1196 /**@ingroup attribue
1197 * Change the ownership of a file or directory.
1199 * @param url The smb url of the file or directory to change
1202 * @param owner I have no idea?
1204 * @param group I have not idea?
1206 * @return 0 on success, < 0 on error with errno set:
1207 * - EPERM The effective UID does not match the owner
1208 * of the file, and is not zero; or the owner or group
1209 * were specified incorrectly.
1210 * - ENOENT The file does not exist.
1211 * - ENOMEM Insufficient was available.
1212 * - ENOENT file or directory does not exist
1214 * @todo Are we actually going to be able to implement this function
1216 * @todo How do we abstract owner and group uid and gid?
1219 int smbc_chown(const char *url
, uid_t owner
, gid_t group
);
1222 /**@ingroup attribute
1223 * Change the permissions of a file.
1225 * @param url The smb url of the file or directory to change
1228 * @param mode The permissions to set:
1229 * - Put good explaination of permissions here!
1231 * @return 0 on success, < 0 on error with errno set:
1232 * - EPERM The effective UID does not match the owner
1233 * of the file, and is not zero
1234 * - ENOENT The file does not exist.
1235 * - ENOMEM Insufficient was available.
1236 * - ENOENT file or directory does not exist
1238 * @todo Actually implement this fuction?
1240 * @todo Are errno values complete and correct?
1242 int smbc_chmod(const char *url
, mode_t mode
);
1245 * @ingroup attribute
1246 * Change the last modification time on a file
1248 * @param url The smb url of the file or directory to change
1249 * the modification time of
1251 * @param tbuf An array of two timeval structures which contains,
1252 * respectively, the desired access and modification times.
1253 * NOTE: Only the tv_sec field off each timeval structure is
1254 * used. The tv_usec (microseconds) portion is ignored.
1256 * @return 0 on success, < 0 on error with errno set:
1257 * - EINVAL The client library is not properly initialized
1258 * - EPERM Permission was denied.
1261 int smbc_utimes(const char *url
, struct timeval
*tbuf
);
1265 * @ingroup attribute
1266 * Change the last modification time on a file
1268 * @param url The smb url of the file or directory to change
1269 * the modification time of
1271 * @param utbuf A pointer to a utimebuf structure which contains the
1272 * desired access and modification times.
1274 * @return 0 on success, < 0 on error with errno set:
1275 * - EINVAL The client library is not properly initialized
1276 * - ENOMEM No memory was available for internal needs
1277 * - EPERM Permission was denied.
1280 int smbc_utime(const char *fname
, struct utimbuf
*utbuf
);
1283 /**@ingroup attribute
1284 * Set extended attributes for a file. This is used for modifying a file's
1285 * security descriptor (i.e. owner, group, and access control list)
1287 * @param url The smb url of the file or directory to set extended
1290 * @param name The name of an attribute to be changed. Names are of
1291 * one of the following forms:
1293 * system.nt_sec_desc.<attribute name>
1294 * system.nt_sec_desc.*
1295 * system.nt_sec_desc.*+
1297 * where <attribute name> is one of:
1305 * acl+:<name or sid>
1307 * In the forms "system.nt_sec_desc.*" and
1308 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1309 * literal, i.e. the string is provided exactly as shown, and
1310 * the value parameter should contain a complete security
1311 * descriptor with name:value pairs separated by tabs,
1312 * commas, or newlines (not spaces!).
1314 * The plus sign ('+') indicates that SIDs should be mapped
1315 * to names. Without the plus sign, SIDs are not mapped;
1316 * rather they are simply converted to a string format.
1318 * @param value The value to be assigned to the specified attribute name.
1319 * This buffer should contain only the attribute value if the
1320 * name was of the "system.nt_sec_desc.<attribute_name>"
1321 * form. If the name was of the "system.nt_sec_desc.*" form
1322 * then a complete security descriptor, with name:value pairs
1323 * separated by tabs, commas, or newlines (not spaces!),
1324 * should be provided in this value buffer. A complete
1325 * security descriptor will contain one or more entries
1326 * selected from the following:
1328 * REVISION:<revision number>
1329 * OWNER:<sid or name>
1330 * GROUP:<sid or name>
1331 * ACL:<sid or name>:<type>/<flags>/<mask>
1333 * The revision of the ACL specifies the internal Windows NT
1334 * ACL revision for the security descriptor. If not specified
1335 * it defaults to 1. Using values other than 1 may cause
1336 * strange behaviour.
1338 * The owner and group specify the owner and group sids for
1339 * the object. If the attribute name (either '*+' with a
1340 * complete security descriptor, or individual 'owner+' or
1341 * 'group+' attribute names) ended with a plus sign, the
1342 * specified name is resolved to a SID value, using the
1343 * server on which the file or directory resides. Otherwise,
1344 * the value should be provided in SID-printable format as
1345 * S-1-x-y-z, and is used directly. The <sid or name>
1346 * associated with the ACL: attribute should be provided
1349 * @param size The number of the bytes of data in the value buffer
1351 * @param flags A bit-wise OR of zero or more of the following:
1352 * SMBC_XATTR_FLAG_CREATE -
1353 * fail if the named attribute already exists
1354 * SMBC_XATTR_FLAG_REPLACE -
1355 * fail if the attribute does not already exist
1357 * If neither flag is specified, the specified attributes
1358 * will be added or replace existing attributes of the same
1359 * name, as necessary.
1361 * @return 0 on success, < 0 on error with errno set:
1362 * - EINVAL The client library is not properly initialized
1363 * or one of the parameters is not of a correct
1365 * - ENOMEM No memory was available for internal needs
1366 * - EEXIST If the attribute already exists and the flag
1367 * SMBC_XATTR_FLAG_CREAT was specified
1368 * - ENOATTR If the attribute does not exist and the flag
1369 * SMBC_XATTR_FLAG_REPLACE was specified
1370 * - EPERM Permission was denied.
1371 * - ENOTSUP The referenced file system does not support
1372 * extended attributes
1374 * @note Attribute names are compared in a case-insensitive
1375 * fashion. All of the following are equivalent, although
1376 * the all-lower-case name is the preferred format:
1377 * system.nt_sec_desc.owner
1378 * SYSTEM.NT_SEC_DESC.OWNER
1379 * sYsTeM.nt_sEc_desc.owNER
1382 int smbc_setxattr(const char *url
,
1389 /**@ingroup attribute
1390 * Set extended attributes for a file. This is used for modifying a file's
1391 * security descriptor (i.e. owner, group, and access control list). The
1392 * POSIX function which this maps to would act on a symbolic link rather than
1393 * acting on what the symbolic link points to, but with no symbolic links in
1394 * SMB file systems, this function is functionally identical to
1397 * @param url The smb url of the file or directory to set extended
1400 * @param name The name of an attribute to be changed. Names are of
1401 * one of the following forms:
1403 * system.nt_sec_desc.<attribute name>
1404 * system.nt_sec_desc.*
1405 * system.nt_sec_desc.*+
1407 * where <attribute name> is one of:
1415 * acl+:<name or sid>
1417 * In the forms "system.nt_sec_desc.*" and
1418 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1419 * literal, i.e. the string is provided exactly as shown, and
1420 * the value parameter should contain a complete security
1421 * descriptor with name:value pairs separated by tabs,
1422 * commas, or newlines (not spaces!).
1424 * The plus sign ('+') indicates that SIDs should be mapped
1425 * to names. Without the plus sign, SIDs are not mapped;
1426 * rather they are simply converted to a string format.
1428 * @param value The value to be assigned to the specified attribute name.
1429 * This buffer should contain only the attribute value if the
1430 * name was of the "system.nt_sec_desc.<attribute_name>"
1431 * form. If the name was of the "system.nt_sec_desc.*" form
1432 * then a complete security descriptor, with name:value pairs
1433 * separated by tabs, commas, or newlines (not spaces!),
1434 * should be provided in this value buffer. A complete
1435 * security descriptor will contain one or more entries
1436 * selected from the following:
1438 * REVISION:<revision number>
1439 * OWNER:<sid or name>
1440 * GROUP:<sid or name>
1441 * ACL:<sid or name>:<type>/<flags>/<mask>
1443 * The revision of the ACL specifies the internal Windows NT
1444 * ACL revision for the security descriptor. If not specified
1445 * it defaults to 1. Using values other than 1 may cause
1446 * strange behaviour.
1448 * The owner and group specify the owner and group sids for
1449 * the object. If the attribute name (either '*+' with a
1450 * complete security descriptor, or individual 'owner+' or
1451 * 'group+' attribute names) ended with a plus sign, the
1452 * specified name is resolved to a SID value, using the
1453 * server on which the file or directory resides. Otherwise,
1454 * the value should be provided in SID-printable format as
1455 * S-1-x-y-z, and is used directly. The <sid or name>
1456 * associated with the ACL: attribute should be provided
1459 * @param size The number of the bytes of data in the value buffer
1461 * @param flags A bit-wise OR of zero or more of the following:
1462 * SMBC_XATTR_FLAG_CREATE -
1463 * fail if the named attribute already exists
1464 * SMBC_XATTR_FLAG_REPLACE -
1465 * fail if the attribute does not already exist
1467 * If neither flag is specified, the specified attributes
1468 * will be added or replace existing attributes of the same
1469 * name, as necessary.
1471 * @return 0 on success, < 0 on error with errno set:
1472 * - EINVAL The client library is not properly initialized
1473 * or one of the parameters is not of a correct
1475 * - ENOMEM No memory was available for internal needs
1476 * - EEXIST If the attribute already exists and the flag
1477 * SMBC_XATTR_FLAG_CREAT was specified
1478 * - ENOATTR If the attribute does not exist and the flag
1479 * SMBC_XATTR_FLAG_REPLACE was specified
1480 * - EPERM Permission was denied.
1481 * - ENOTSUP The referenced file system does not support
1482 * extended attributes
1484 * @note Attribute names are compared in a case-insensitive
1485 * fashion. All of the following are equivalent, although
1486 * the all-lower-case name is the preferred format:
1487 * system.nt_sec_desc.owner
1488 * SYSTEM.NT_SEC_DESC.OWNER
1489 * sYsTeM.nt_sEc_desc.owNER
1492 int smbc_lsetxattr(const char *url
,
1499 /**@ingroup attribute
1500 * Set extended attributes for a file. This is used for modifying a file's
1501 * security descriptor (i.e. owner, group, and access control list)
1503 * @param fd A file descriptor associated with an open file (as
1504 * previously returned by smbc_open(), to get extended
1507 * @param name The name of an attribute to be changed. Names are of
1508 * one of the following forms:
1510 * system.nt_sec_desc.<attribute name>
1511 * system.nt_sec_desc.*
1512 * system.nt_sec_desc.*+
1514 * where <attribute name> is one of:
1522 * acl+:<name or sid>
1524 * In the forms "system.nt_sec_desc.*" and
1525 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1526 * literal, i.e. the string is provided exactly as shown, and
1527 * the value parameter should contain a complete security
1528 * descriptor with name:value pairs separated by tabs,
1529 * commas, or newlines (not spaces!).
1531 * The plus sign ('+') indicates that SIDs should be mapped
1532 * to names. Without the plus sign, SIDs are not mapped;
1533 * rather they are simply converted to a string format.
1535 * @param value The value to be assigned to the specified attribute name.
1536 * This buffer should contain only the attribute value if the
1537 * name was of the "system.nt_sec_desc.<attribute_name>"
1538 * form. If the name was of the "system.nt_sec_desc.*" form
1539 * then a complete security descriptor, with name:value pairs
1540 * separated by tabs, commas, or newlines (not spaces!),
1541 * should be provided in this value buffer. A complete
1542 * security descriptor will contain one or more entries
1543 * selected from the following:
1545 * REVISION:<revision number>
1546 * OWNER:<sid or name>
1547 * GROUP:<sid or name>
1548 * ACL:<sid or name>:<type>/<flags>/<mask>
1550 * The revision of the ACL specifies the internal Windows NT
1551 * ACL revision for the security descriptor. If not specified
1552 * it defaults to 1. Using values other than 1 may cause
1553 * strange behaviour.
1555 * The owner and group specify the owner and group sids for
1556 * the object. If the attribute name (either '*+' with a
1557 * complete security descriptor, or individual 'owner+' or
1558 * 'group+' attribute names) ended with a plus sign, the
1559 * specified name is resolved to a SID value, using the
1560 * server on which the file or directory resides. Otherwise,
1561 * the value should be provided in SID-printable format as
1562 * S-1-x-y-z, and is used directly. The <sid or name>
1563 * associated with the ACL: attribute should be provided
1566 * @param size The number of the bytes of data in the value buffer
1568 * @param flags A bit-wise OR of zero or more of the following:
1569 * SMBC_XATTR_FLAG_CREATE -
1570 * fail if the named attribute already exists
1571 * SMBC_XATTR_FLAG_REPLACE -
1572 * fail if the attribute does not already exist
1574 * If neither flag is specified, the specified attributes
1575 * will be added or replace existing attributes of the same
1576 * name, as necessary.
1578 * @return 0 on success, < 0 on error with errno set:
1579 * - EINVAL The client library is not properly initialized
1580 * or one of the parameters is not of a correct
1582 * - ENOMEM No memory was available for internal needs
1583 * - EEXIST If the attribute already exists and the flag
1584 * SMBC_XATTR_FLAG_CREAT was specified
1585 * - ENOATTR If the attribute does not exist and the flag
1586 * SMBC_XATTR_FLAG_REPLACE was specified
1587 * - EPERM Permission was denied.
1588 * - ENOTSUP The referenced file system does not support
1589 * extended attributes
1591 * @note Attribute names are compared in a case-insensitive
1592 * fashion. All of the following are equivalent, although
1593 * the all-lower-case name is the preferred format:
1594 * system.nt_sec_desc.owner
1595 * SYSTEM.NT_SEC_DESC.OWNER
1596 * sYsTeM.nt_sEc_desc.owNER
1599 int smbc_fsetxattr(int fd
,
1606 /**@ingroup attribute
1607 * Get extended attributes for a file.
1609 * @param url The smb url of the file or directory to get extended
1612 * @param name The name of an attribute to be retrieved. Names are of
1613 * one of the following forms:
1615 * system.nt_sec_desc.<attribute name>
1616 * system.nt_sec_desc.*
1617 * system.nt_sec_desc.*+
1619 * where <attribute name> is one of:
1627 * acl+:<name or sid>
1629 * In the forms "system.nt_sec_desc.*" and
1630 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1631 * literal, i.e. the string is provided exactly as shown, and
1632 * the value parameter will return a complete security
1633 * descriptor with name:value pairs separated by tabs,
1634 * commas, or newlines (not spaces!).
1636 * The plus sign ('+') indicates that SIDs should be mapped
1637 * to names. Without the plus sign, SIDs are not mapped;
1638 * rather they are simply converted to a string format.
1640 * @param value A pointer to a buffer in which the value of the specified
1641 * attribute will be placed (unless size is zero).
1643 * @param size The size of the buffer pointed to by value. This parameter
1644 * may also be zero, in which case the size of the buffer
1645 * required to hold the attribute value will be returned,
1646 * but nothing will be placed into the value buffer.
1648 * @return 0 on success, < 0 on error with errno set:
1649 * - EINVAL The client library is not properly initialized
1650 * or one of the parameters is not of a correct
1652 * - ENOMEM No memory was available for internal needs
1653 * - EEXIST If the attribute already exists and the flag
1654 * SMBC_XATTR_FLAG_CREAT was specified
1655 * - ENOATTR If the attribute does not exist and the flag
1656 * SMBC_XATTR_FLAG_REPLACE was specified
1657 * - EPERM Permission was denied.
1658 * - ENOTSUP The referenced file system does not support
1659 * extended attributes
1662 int smbc_getxattr(const char *url
,
1668 /**@ingroup attribute
1669 * Get extended attributes for a file. The POSIX function which this maps to
1670 * would act on a symbolic link rather than acting on what the symbolic link
1671 * points to, but with no symbolic links in SMB file systems, this function
1672 * is functionally identical to smbc_getxattr().
1674 * @param url The smb url of the file or directory to get extended
1677 * @param name The name of an attribute to be retrieved. Names are of
1678 * one of the following forms:
1680 * system.nt_sec_desc.<attribute name>
1681 * system.nt_sec_desc.*
1682 * system.nt_sec_desc.*+
1684 * where <attribute name> is one of:
1692 * acl+:<name or sid>
1694 * In the forms "system.nt_sec_desc.*" and
1695 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1696 * literal, i.e. the string is provided exactly as shown, and
1697 * the value parameter will return a complete security
1698 * descriptor with name:value pairs separated by tabs,
1699 * commas, or newlines (not spaces!).
1701 * The plus sign ('+') indicates that SIDs should be mapped
1702 * to names. Without the plus sign, SIDs are not mapped;
1703 * rather they are simply converted to a string format.
1705 * @param value A pointer to a buffer in which the value of the specified
1706 * attribute will be placed (unless size is zero).
1708 * @param size The size of the buffer pointed to by value. This parameter
1709 * may also be zero, in which case the size of the buffer
1710 * required to hold the attribute value will be returned,
1711 * but nothing will be placed into the value buffer.
1713 * @return 0 on success, < 0 on error with errno set:
1714 * - EINVAL The client library is not properly initialized
1715 * or one of the parameters is not of a correct
1717 * - ENOMEM No memory was available for internal needs
1718 * - EEXIST If the attribute already exists and the flag
1719 * SMBC_XATTR_FLAG_CREAT was specified
1720 * - ENOATTR If the attribute does not exist and the flag
1721 * SMBC_XATTR_FLAG_REPLACE was specified
1722 * - EPERM Permission was denied.
1723 * - ENOTSUP The referenced file system does not support
1724 * extended attributes
1727 int smbc_lgetxattr(const char *url
,
1733 /**@ingroup attribute
1734 * Get extended attributes for a file.
1736 * @param fd A file descriptor associated with an open file (as
1737 * previously returned by smbc_open(), to get extended
1740 * @param name The name of an attribute to be retrieved. Names are of
1741 * one of the following forms:
1743 * system.nt_sec_desc.<attribute name>
1744 * system.nt_sec_desc.*
1745 * system.nt_sec_desc.*+
1747 * where <attribute name> is one of:
1755 * acl+:<name or sid>
1757 * In the forms "system.nt_sec_desc.*" and
1758 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1759 * literal, i.e. the string is provided exactly as shown, and
1760 * the value parameter will return a complete security
1761 * descriptor with name:value pairs separated by tabs,
1762 * commas, or newlines (not spaces!).
1764 * The plus sign ('+') indicates that SIDs should be mapped
1765 * to names. Without the plus sign, SIDs are not mapped;
1766 * rather they are simply converted to a string format.
1768 * @param value A pointer to a buffer in which the value of the specified
1769 * attribute will be placed (unless size is zero).
1771 * @param size The size of the buffer pointed to by value. This parameter
1772 * may also be zero, in which case the size of the buffer
1773 * required to hold the attribute value will be returned,
1774 * but nothing will be placed into the value buffer.
1776 * @return 0 on success, < 0 on error with errno set:
1777 * - EINVAL The client library is not properly initialized
1778 * or one of the parameters is not of a correct
1780 * - ENOMEM No memory was available for internal needs
1781 * - EEXIST If the attribute already exists and the flag
1782 * SMBC_XATTR_FLAG_CREAT was specified
1783 * - ENOATTR If the attribute does not exist and the flag
1784 * SMBC_XATTR_FLAG_REPLACE was specified
1785 * - EPERM Permission was denied.
1786 * - ENOTSUP The referenced file system does not support
1787 * extended attributes
1790 int smbc_fgetxattr(int fd
,
1796 /**@ingroup attribute
1797 * Remove extended attributes for a file. This is used for modifying a file's
1798 * security descriptor (i.e. owner, group, and access control list)
1800 * @param url The smb url of the file or directory to remove the extended
1803 * @param name The name of an attribute to be removed. Names are of
1804 * one of the following forms:
1806 * system.nt_sec_desc.<attribute name>
1807 * system.nt_sec_desc.*
1808 * system.nt_sec_desc.*+
1810 * where <attribute name> is one of:
1818 * acl+:<name or sid>
1820 * In the forms "system.nt_sec_desc.*" and
1821 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1822 * literal, i.e. the string is provided exactly as shown, and
1823 * the value parameter will return a complete security
1824 * descriptor with name:value pairs separated by tabs,
1825 * commas, or newlines (not spaces!).
1827 * The plus sign ('+') indicates that SIDs should be mapped
1828 * to names. Without the plus sign, SIDs are not mapped;
1829 * rather they are simply converted to a string format.
1831 * @return 0 on success, < 0 on error with errno set:
1832 * - EINVAL The client library is not properly initialized
1833 * - ENOMEM No memory was available for internal needs
1834 * - EPERM Permission was denied.
1835 * - ENOTSUP The referenced file system does not support
1836 * extended attributes
1839 int smbc_removexattr(const char *url
,
1843 /**@ingroup attribute
1844 * Remove extended attributes for a file. This is used for modifying a file's
1845 * security descriptor (i.e. owner, group, and access control list) The POSIX
1846 * function which this maps to would act on a symbolic link rather than acting
1847 * on what the symbolic link points to, but with no symbolic links in SMB file
1848 * systems, this function is functionally identical to smbc_removexattr().
1850 * @param url The smb url of the file or directory to remove the extended
1853 * @param name The name of an attribute to be removed. Names are of
1854 * one of the following forms:
1856 * system.nt_sec_desc.<attribute name>
1857 * system.nt_sec_desc.*
1858 * system.nt_sec_desc.*+
1860 * where <attribute name> is one of:
1868 * acl+:<name or sid>
1870 * In the forms "system.nt_sec_desc.*" and
1871 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1872 * literal, i.e. the string is provided exactly as shown, and
1873 * the value parameter will return a complete security
1874 * descriptor with name:value pairs separated by tabs,
1875 * commas, or newlines (not spaces!).
1877 * The plus sign ('+') indicates that SIDs should be mapped
1878 * to names. Without the plus sign, SIDs are not mapped;
1879 * rather they are simply converted to a string format.
1881 * @return 0 on success, < 0 on error with errno set:
1882 * - EINVAL The client library is not properly initialized
1883 * - ENOMEM No memory was available for internal needs
1884 * - EPERM Permission was denied.
1885 * - ENOTSUP The referenced file system does not support
1886 * extended attributes
1889 int smbc_lremovexattr(const char *url
,
1893 /**@ingroup attribute
1894 * Remove extended attributes for a file. This is used for modifying a file's
1895 * security descriptor (i.e. owner, group, and access control list)
1897 * @param fd A file descriptor associated with an open file (as
1898 * previously returned by smbc_open(), to get extended
1901 * @param name The name of an attribute to be removed. Names are of
1902 * one of the following forms:
1904 * system.nt_sec_desc.<attribute name>
1905 * system.nt_sec_desc.*
1906 * system.nt_sec_desc.*+
1908 * where <attribute name> is one of:
1916 * acl+:<name or sid>
1918 * In the forms "system.nt_sec_desc.*" and
1919 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1920 * literal, i.e. the string is provided exactly as shown, and
1921 * the value parameter will return a complete security
1922 * descriptor with name:value pairs separated by tabs,
1923 * commas, or newlines (not spaces!).
1925 * The plus sign ('+') indicates that SIDs should be mapped
1926 * to names. Without the plus sign, SIDs are not mapped;
1927 * rather they are simply converted to a string format.
1929 * @return 0 on success, < 0 on error with errno set:
1930 * - EINVAL The client library is not properly initialized
1931 * - ENOMEM No memory was available for internal needs
1932 * - EPERM Permission was denied.
1933 * - ENOTSUP The referenced file system does not support
1934 * extended attributes
1937 int smbc_fremovexattr(int fd
,
1941 /**@ingroup attribute
1942 * List the supported extended attribute names associated with a file
1944 * @param url The smb url of the file or directory to list the extended
1947 * @param list A pointer to a buffer in which the list of attributes for
1948 * the specified file or directory will be placed (unless
1951 * @param size The size of the buffer pointed to by list. This parameter
1952 * may also be zero, in which case the size of the buffer
1953 * required to hold all of the attribute names will be
1954 * returned, but nothing will be placed into the list buffer.
1956 * @return 0 on success, < 0 on error with errno set:
1957 * - EINVAL The client library is not properly initialized
1958 * - ENOMEM No memory was available for internal needs
1959 * - EPERM Permission was denied.
1960 * - ENOTSUP The referenced file system does not support
1961 * extended attributes
1963 * @note This function always returns all attribute names supported
1964 * by NT file systems, regardless of whether the referenced
1965 * file system supports extended attributes (e.g. a Windows
1966 * 2000 machine supports extended attributes if NTFS is used,
1967 * but not if FAT is used, and Windows 98 doesn't support
1968 * extended attributes at all. Whether this is a feature or
1969 * a bug is yet to be decided.
1971 int smbc_listxattr(const char *url
,
1975 /**@ingroup attribute
1976 * List the supported extended attribute names associated with a file The
1977 * POSIX function which this maps to would act on a symbolic link rather than
1978 * acting on what the symbolic link points to, but with no symbolic links in
1979 * SMB file systems, this function is functionally identical to
1982 * @param url The smb url of the file or directory to list the extended
1985 * @param list A pointer to a buffer in which the list of attributes for
1986 * the specified file or directory will be placed (unless
1989 * @param size The size of the buffer pointed to by list. This parameter
1990 * may also be zero, in which case the size of the buffer
1991 * required to hold all of the attribute names will be
1992 * returned, but nothing will be placed into the list buffer.
1994 * @return 0 on success, < 0 on error with errno set:
1995 * - EINVAL The client library is not properly initialized
1996 * - ENOMEM No memory was available for internal needs
1997 * - EPERM Permission was denied.
1998 * - ENOTSUP The referenced file system does not support
1999 * extended attributes
2001 * @note This function always returns all attribute names supported
2002 * by NT file systems, regardless of wether the referenced
2003 * file system supports extended attributes (e.g. a Windows
2004 * 2000 machine supports extended attributes if NTFS is used,
2005 * but not if FAT is used, and Windows 98 doesn't support
2006 * extended attributes at all. Whether this is a feature or
2007 * a bug is yet to be decided.
2009 int smbc_llistxattr(const char *url
,
2013 /**@ingroup attribute
2014 * List the supported extended attribute names associated with a file
2016 * @param fd A file descriptor associated with an open file (as
2017 * previously returned by smbc_open(), to get extended
2020 * @param list A pointer to a buffer in which the list of attributes for
2021 * the specified file or directory will be placed (unless
2024 * @param size The size of the buffer pointed to by list. This parameter
2025 * may also be zero, in which case the size of the buffer
2026 * required to hold all of the attribute names will be
2027 * returned, but nothing will be placed into the list buffer.
2029 * @return 0 on success, < 0 on error with errno set:
2030 * - EINVAL The client library is not properly initialized
2031 * - ENOMEM No memory was available for internal needs
2032 * - EPERM Permission was denied.
2033 * - ENOTSUP The referenced file system does not support
2034 * extended attributes
2036 * @note This function always returns all attribute names supported
2037 * by NT file systems, regardless of wether the referenced
2038 * file system supports extended attributes (e.g. a Windows
2039 * 2000 machine supports extended attributes if NTFS is used,
2040 * but not if FAT is used, and Windows 98 doesn't support
2041 * extended attributes at all. Whether this is a feature or
2042 * a bug is yet to be decided.
2044 int smbc_flistxattr(int fd
,
2049 * Print a file given the name in fname. It would be a URL ...
2051 * @param fname The URL of a file on a remote SMB server that the
2052 * caller wants printed
2054 * @param printq The URL of the print share to print the file to.
2056 * @return 0 on success, < 0 on error with errno set:
2058 * - EINVAL fname or printq was NULL or smbc_init not
2060 * and errors returned by smbc_open
2063 int smbc_print_file(const char *fname
, const char *printq
);
2066 * Open a print file that can be written to by other calls. This simply
2067 * does an smbc_open call after checking if there is a file name on the
2068 * URI. If not, a temporary name is added ...
2070 * @param fname The URL of the print share to print to?
2072 * @returns A file handle for the print file if successful.
2073 * Returns -1 if an error ocurred and errno has the values
2074 * - EINVAL fname was NULL or smbc_init not called.
2075 * - all errors returned by smbc_open
2078 int smbc_open_print_job(const char *fname
);
2081 * List the print jobs on a print share, for the moment, pass a callback
2083 * @param purl The url of the print share to list the jobs of
2085 * @param fn Callback function the receives printjob info
2087 * @return 0 on success, < 0 on error with errno set:
2088 * - EINVAL fname was NULL or smbc_init not called
2091 int smbc_list_print_jobs(const char *purl
, smbc_list_print_job_fn fn
);
2094 * Delete a print job
2096 * @param purl Url of the print share
2098 * @param id The id of the job to delete
2100 * @return 0 on success, < 0 on error with errno set:
2101 * - EINVAL fname was NULL or smbc_init not called
2103 * @todo what errno values are possible here?
2105 int smbc_unlink_print_job(const char *purl
, int id
);
2107 /**@ingroup callback
2108 * Remove a server from the cached server list it's unused.
2110 * @param context pointer to smb context
2112 * @param srv pointer to server to remove
2114 * @return On success, 0 is returned. 1 is returned if the server could not
2115 * be removed. Also useable outside libsmbclient.
2117 int smbc_remove_unused_server(SMBCCTX
* context
, SMBCSRV
* srv
);
2123 /**@ingroup directory
2124 * Convert strings of %xx to their single character equivalent.
2126 * @param dest A pointer to a buffer in which the resulting decoded
2127 * string should be placed. This may be a pointer to the
2128 * same buffer as src_segment.
2130 * @param src A pointer to the buffer containing the URL to be decoded.
2131 * Any %xx sequences herein are converted to their single
2132 * character equivalent. Each 'x' must be a valid hexadecimal
2133 * digit, or that % sequence is left undecoded.
2135 * @param max_dest_len
2136 * The size of the buffer pointed to by dest_segment.
2138 * @return The number of % sequences which could not be converted
2139 * due to lack of two following hexadecimal digits.
2145 smbc_urldecode(char *dest
, char * src
, size_t max_dest_len
);
2152 * Convert any characters not specifically allowed in a URL into their %xx
2155 * @param dest A pointer to a buffer in which the resulting encoded
2156 * string should be placed. Unlike smbc_urldecode(), this
2157 * must be a buffer unique from src.
2159 * @param src A pointer to the buffer containing the string to be encoded.
2160 * Any character not specifically allowed in a URL is converted
2161 * into its hexadecimal value and encoded as %xx.
2163 * @param max_dest_len
2164 * The size of the buffer pointed to by dest_segment.
2166 * @returns The remaining buffer length.
2172 smbc_urlencode(char * dest
, char * src
, int max_dest_len
);
2178 /**@ingroup directory
2179 * Return the version of the linked Samba code, and thus the version of the
2180 * libsmbclient code.
2182 * @return The version string.
2194 #endif /* SMBCLIENT_H_INCLUDED */