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 2 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, write to the Free Software
23 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 =====================================================================*/
26 #ifndef SMBCLIENT_H_INCLUDED
27 #define SMBCLIENT_H_INCLUDED
33 /*-------------------------------------------------------------------*/
34 /* The following are special comments to instruct DOXYGEN (automated
37 /** \defgroup libsmbclient
39 /** \defgroup structure Data Structures Type and Constants
40 * \ingroup libsmbclient
41 * Data structures, types, and constants
43 /** \defgroup callback Callback function types
44 * \ingroup libsmbclient
47 /** \defgroup file File Functions
48 * \ingroup libsmbclient
49 * Functions used to access individual file contents
51 /** \defgroup directory Directory Functions
52 * \ingroup libsmbclient
53 * Functions used to access directory entries
55 /** \defgroup attribute Attributes Functions
56 * \ingroup libsmbclient
57 * Functions used to view or change file and directory attributes
59 /** \defgroup print Print Functions
60 * \ingroup libsmbclient
61 * Functions used to access printing functionality
63 /** \defgroup misc Miscellaneous Functions
64 * \ingroup libsmbclient
65 * Functions that don't fit in to other categories
67 /*-------------------------------------------------------------------*/
69 /* Make sure we have the following includes for now ... */
70 #include <sys/types.h>
75 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
77 #define SMBC_WORKGROUP 1
79 #define SMBC_FILE_SHARE 3
80 #define SMBC_PRINTER_SHARE 4
81 #define SMBC_COMMS_SHARE 5
82 #define SMBC_IPC_SHARE 6
88 * Structure that represents a directory entry.
103 unsigned int smbc_type
;
105 /** Length of this smbc_dirent in bytes
108 /** The length of the comment string in bytes (does not include
111 unsigned int commentlen
;
112 /** Points to the null terminated comment string
115 /** The length of the name string in bytes (does not include
118 unsigned int namelen
;
119 /** Points to the null terminated name string
125 * Flags for smbc_setxattr()
126 * Specify a bitwise OR of these, or 0 to add or replace as necessary
128 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
129 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
133 * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
134 * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
135 * "system.*") is specified.
137 #define SMBC_DOS_MODE_READONLY 0x01
138 #define SMBC_DOS_MODE_HIDDEN 0x02
139 #define SMBC_DOS_MODE_SYSTEM 0x04
140 #define SMBC_DOS_MODE_VOLUME_ID 0x08
141 #define SMBC_DOS_MODE_DIRECTORY 0x10
142 #define SMBC_DOS_MODE_ARCHIVE 0x20
146 # define ENOATTR ENOENT /* No such attribute */
152 /**@ingroup structure
153 * Structure that represents a print job.
157 struct print_job_info
159 /** numeric ID of the print job
163 /** represents print job priority (lower numbers mean higher priority)
165 unsigned short priority
;
167 /** Size of the print job
171 /** Name of the user that owns the print job
175 /** Name of the print job. This will have no name if an anonymous print
176 * file was opened. Ie smb://server/printer
180 /** Time the print job was spooled
184 #endif /* _CLIENT_H */
187 /**@ingroup structure
190 typedef struct _SMBCSRV SMBCSRV
;
192 /**@ingroup structure
193 * File or directory handle
195 typedef struct _SMBCFILE SMBCFILE
;
197 /**@ingroup structure
198 * File or directory handle
200 typedef struct _SMBCCTX SMBCCTX
;
207 * Authentication callback function type (traditional method)
209 * Type for the the authentication function called by the library to
210 * obtain authentication credentals
212 * @param srv Server being authenticated to
214 * @param shr Share being authenticated to
216 * @param wg Pointer to buffer containing a "hint" for the
217 * workgroup to be authenticated. Should be filled in
218 * with the correct workgroup if the hint is wrong.
220 * @param wglen The size of the workgroup buffer in bytes
222 * @param un Pointer to buffer containing a "hint" for the
223 * user name to be use for authentication. Should be
224 * filled in with the correct workgroup if the hint is
227 * @param unlen The size of the username buffer in bytes
229 * @param pw Pointer to buffer containing to which password
232 * @param pwlen The size of the password buffer in bytes
235 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
239 char *pw
, int pwlen
);
241 * Authentication callback function type (method that includes context)
243 * Type for the the authentication function called by the library to
244 * obtain authentication credentals
246 * @param c Pointer to the smb context
248 * @param srv Server being authenticated to
250 * @param shr Share being authenticated to
252 * @param wg Pointer to buffer containing a "hint" for the
253 * workgroup to be authenticated. Should be filled in
254 * with the correct workgroup if the hint is wrong.
256 * @param wglen The size of the workgroup buffer in bytes
258 * @param un Pointer to buffer containing a "hint" for the
259 * user name to be use for authentication. Should be
260 * filled in with the correct workgroup if the hint is
263 * @param unlen The size of the username buffer in bytes
265 * @param pw Pointer to buffer containing to which password
268 * @param pwlen The size of the password buffer in bytes
271 typedef void (*smbc_get_auth_data_with_context_fn
)(SMBCCTX
*c
,
276 char *pw
, int pwlen
);
280 * Print job info callback function type.
282 * @param i pointer to print job information structure
285 typedef void (*smbc_list_print_job_fn
)(struct print_job_info
*i
);
289 * Check if a server is still good
291 * @param c pointer to smb context
293 * @param srv pointer to server to check
295 * @return 0 when connection is good. 1 on error.
298 typedef int (*smbc_check_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
301 * Remove a server if unused
303 * @param c pointer to smb context
305 * @param srv pointer to server to remove
307 * @return 0 on success. 1 on failure.
310 typedef int (*smbc_remove_unused_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
314 * Add a server to the cache system
316 * @param c pointer to smb context
318 * @param srv pointer to server to add
320 * @param server server name
322 * @param share share name
324 * @param workgroup workgroup used to connect
326 * @param username username used to connect
328 * @return 0 on success. 1 on failure.
331 typedef int (*smbc_add_cached_srv_fn
) (SMBCCTX
* c
, SMBCSRV
*srv
,
332 const char * server
, const char * share
,
333 const char * workgroup
, const char * username
);
336 * Look up a server in the cache system
338 * @param c pointer to smb context
340 * @param server server name to match
342 * @param share share name to match
344 * @param workgroup workgroup to match
346 * @param username username to match
348 * @return pointer to SMBCSRV on success. NULL on failure.
351 typedef SMBCSRV
* (*smbc_get_cached_srv_fn
) (SMBCCTX
* c
, const char * server
,
352 const char * share
, const char * workgroup
,
353 const char * username
);
356 * Check if a server is still good
358 * @param c pointer to smb context
360 * @param srv pointer to server to remove
362 * @return 0 when found and removed. 1 on failure.
365 typedef int (*smbc_remove_cached_srv_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
369 * Try to remove all servers from the cache system and disconnect
371 * @param c pointer to smb context
373 * @return 0 when found and removed. 1 on failure.
376 typedef int (*smbc_purge_cached_fn
) (SMBCCTX
* c
);
379 /**@ingroup structure
380 * Structure that contains a client context information
381 * This structure is know as SMBCCTX
388 /** netbios name used for making connections
392 /** workgroup name used for making connections
396 /** username used for making connections
400 /** timeout used for waiting on connections / response data (in milliseconds)
404 /** callable functions for files:
405 * For usage and return values see the smbc_* functions
407 SMBCFILE
* (*open
) (SMBCCTX
*c
, const char *fname
, int flags
, mode_t mode
);
408 SMBCFILE
* (*creat
) (SMBCCTX
*c
, const char *path
, mode_t mode
);
409 ssize_t (*read
) (SMBCCTX
*c
, SMBCFILE
*file
, void *buf
, size_t count
);
410 ssize_t (*write
) (SMBCCTX
*c
, SMBCFILE
*file
, void *buf
, size_t count
);
411 int (*unlink
) (SMBCCTX
*c
, const char *fname
);
412 int (*rename
) (SMBCCTX
*ocontext
, const char *oname
,
413 SMBCCTX
*ncontext
, const char *nname
);
414 off_t (*lseek
) (SMBCCTX
*c
, SMBCFILE
* file
, off_t offset
, int whence
);
415 int (*stat
) (SMBCCTX
*c
, const char *fname
, struct stat
*st
);
416 int (*fstat
) (SMBCCTX
*c
, SMBCFILE
*file
, struct stat
*st
);
417 int (*close_fn
) (SMBCCTX
*c
, SMBCFILE
*file
);
419 /** callable functions for dirs
421 SMBCFILE
* (*opendir
) (SMBCCTX
*c
, const char *fname
);
422 int (*closedir
)(SMBCCTX
*c
, SMBCFILE
*dir
);
423 struct smbc_dirent
* (*readdir
)(SMBCCTX
*c
, SMBCFILE
*dir
);
424 int (*getdents
)(SMBCCTX
*c
, SMBCFILE
*dir
,
425 struct smbc_dirent
*dirp
, int count
);
426 int (*mkdir
) (SMBCCTX
*c
, const char *fname
, mode_t mode
);
427 int (*rmdir
) (SMBCCTX
*c
, const char *fname
);
428 off_t (*telldir
) (SMBCCTX
*c
, SMBCFILE
*dir
);
429 int (*lseekdir
)(SMBCCTX
*c
, SMBCFILE
*dir
, off_t offset
);
430 int (*fstatdir
)(SMBCCTX
*c
, SMBCFILE
*dir
, struct stat
*st
);
431 int (*chmod
)(SMBCCTX
*c
, const char *fname
, mode_t mode
);
432 int (*utimes
)(SMBCCTX
*c
,
433 const char *fname
, struct timeval
*tbuf
);
434 int (*setxattr
)(SMBCCTX
*context
,
440 int (*getxattr
)(SMBCCTX
*context
,
445 int (*removexattr
)(SMBCCTX
*context
,
448 int (*listxattr
)(SMBCCTX
*context
,
453 /** callable functions for printing
455 int (*print_file
)(SMBCCTX
*c_file
, const char *fname
,
456 SMBCCTX
*c_print
, const char *printq
);
457 SMBCFILE
* (*open_print_job
)(SMBCCTX
*c
, const char *fname
);
458 int (*list_print_jobs
)(SMBCCTX
*c
, const char *fname
, smbc_list_print_job_fn fn
);
459 int (*unlink_print_job
)(SMBCCTX
*c
, const char *fname
, int id
);
464 * These callbacks _always_ have to be initialized because they will
465 * not be checked at dereference for increased speed.
467 struct _smbc_callbacks
{
468 /** authentication function callback: called upon auth requests
470 smbc_get_auth_data_fn auth_fn
;
472 /** check if a server is still good
474 smbc_check_server_fn check_server_fn
;
476 /** remove a server if unused
478 smbc_remove_unused_server_fn remove_unused_server_fn
;
481 * For an example cache system see samba/source/libsmb/libsmb_cache.c
482 * Cache subsystem functions follow.
485 /** server cache addition
487 smbc_add_cached_srv_fn add_cached_srv_fn
;
489 /** server cache lookup
491 smbc_get_cached_srv_fn get_cached_srv_fn
;
493 /** server cache removal
495 smbc_remove_cached_srv_fn remove_cached_srv_fn
;
497 /** server cache purging, try to remove all cached servers (disconnect)
499 smbc_purge_cached_fn purge_cached_fn
;
503 /** Space to store private data of the server cache.
505 struct smbc_server_cache
* server_cache
;
509 /** user options selections that apply to this session
511 struct _smbc_options
{
514 * From how many local master browsers should the list of
515 * workgroups be retrieved? It can take up to 12 minutes or
516 * longer after a server becomes a local master browser, for
517 * it to have the entire browse list (the list of
518 * workgroups/domains) from an entire network. Since a client
519 * never knows which local master browser will be found first,
520 * the one which is found first and used to retrieve a browse
521 * list may have an incomplete or empty browse list. By
522 * requesting the browse list from multiple local master
523 * browsers, a more complete list can be generated. For small
524 * networks (few workgroups), it is recommended that this
525 * value be set to 0, causing the browse lists from all found
526 * local master browsers to be retrieved and merged. For
527 * networks with many workgroups, a suitable value for this
528 * variable is probably somewhere around 3. (Default: 3).
530 int browse_max_lmb_count
;
533 * There is a difference in the desired return strings from
534 * smbc_readdir() depending upon whether the filenames are to
535 * be displayed to the user, or whether they are to be
536 * appended to the path name passed to smbc_opendir() to call
537 * a further smbc_ function (e.g. open the file with
538 * smbc_open()). In the former case, the filename should be
539 * in "human readable" form. In the latter case, the smbc_
540 * functions expect a URL which must be url-encoded. Those
541 * functions decode the URL. If, for example, smbc_readdir()
542 * returned a file name of "abc%20def.txt", passing a path
543 * with this file name attached to smbc_open() would cause
544 * smbc_open to attempt to open the file "abc def.txt" since
545 * the %20 is decoded into a space.
547 * Set this option to True if the names returned by
548 * smbc_readdir() should be url-encoded such that they can be
549 * passed back to another smbc_ call. Set it to False if the
550 * names returned by smbc_readdir() are to be presented to the
553 * For backwards compatibility, this option defaults to False.
555 int urlencode_readdir_entries
;
558 * Some Windows versions appear to have a limit to the number
559 * of concurrent SESSIONs and/or TREE CONNECTions. In
560 * one-shot programs (i.e. the program runs and then quickly
561 * ends, thereby shutting down all connections), it is
562 * probably reasonable to establish a new connection for each
563 * share. In long-running applications, the limitation can be
564 * avoided by using only a single connection to each server,
565 * and issuing a new TREE CONNECT when the share is accessed.
567 int one_share_per_server
;
571 * do _NOT_ touch this from your program !
573 struct smbc_internal_data
* internal
;
576 /* Flags for SMBCCTX->flags */
577 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
578 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
579 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
582 * Create a new SBMCCTX (a context).
584 * Must be called before the context is passed to smbc_context_init()
586 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
587 * - ENOMEM Out of memory
589 * @see smbc_free_context(), smbc_init_context()
591 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
593 SMBCCTX
* smbc_new_context(void);
596 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
598 * The context will be deleted if possible.
600 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
602 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
605 * @return Returns 0 on succes. Returns 1 on failure with errno set:
606 * - EBUSY Server connections are still used, Files are open or cache
607 * could not be purged
608 * - EBADF context == NULL
610 * @see smbc_new_context()
612 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
613 * just before exit()'ing. When shutdown_ctx is 0, this function can be
614 * use in periodical cleanup functions for example.
616 int smbc_free_context(SMBCCTX
* context
, int shutdown_ctx
);
620 * Each time the context structure is changed, we have binary backward
621 * compatibility issues. Instead of modifying the public portions of the
622 * context structure to add new options, instead, we put them in the internal
623 * portion of the context structure and provide a set function for these new
626 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
629 * The name of the option for which the value is to be set
631 * @param option_value
632 * The new value of the option being set
636 smbc_option_set(SMBCCTX
*context
,
640 * Retrieve the current value of an option
642 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
645 * The name of the option for which the value is to be
648 * @return The value of the specified option.
651 smbc_option_get(SMBCCTX
*context
,
655 * Initialize a SBMCCTX (a context).
657 * Must be called before using any SMBCCTX API function
659 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
661 * @return A pointer to the given SMBCCTX on success,
662 * NULL on error with errno set:
663 * - EBADF NULL context given
664 * - ENOMEM Out of memory
665 * - ENOENT The smb.conf file would not load
667 * @see smbc_new_context()
669 * @note my_context = smbc_init_context(smbc_new_context())
670 * is perfectly safe, but it might leak memory on
671 * smbc_context_init() failure. Avoid this.
672 * You'll have to call smbc_free_context() yourself
676 SMBCCTX
* smbc_init_context(SMBCCTX
* context
);
679 * Initialize the samba client library.
681 * Must be called before using any of the smbclient API function
683 * @param fn The function that will be called to obtaion
684 * authentication credentials.
686 * @param debug Allows caller to set the debug level. Can be
687 * changed in smb.conf file. Allows caller to set
688 * debugging if no smb.conf.
690 * @return 0 on success, < 0 on error with errno set:
691 * - ENOMEM Out of memory
692 * - ENOENT The smb.conf file would not load
696 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
699 * Set or retrieve the compatibility library's context pointer
701 * @param context New context to use, or NULL. If a new context is provided,
702 * it must have allocated with smbc_new_context() and
703 * initialized with smbc_init_context(), followed, optionally,
704 * by some manual changes to some of the non-internal fields.
706 * @return The old context.
708 * @see smbc_new_context(), smbc_init_context(), smbc_init()
710 * @note This function may be called prior to smbc_init() to force
711 * use of the next context without any internal calls to
712 * smbc_new_context() or smbc_init_context(). It may also
713 * be called after smbc_init() has already called those two
714 * functions, to replace the existing context with a new one.
715 * Care should be taken, in this latter case, to ensure that
716 * the server cache and any data allocated by the
717 * authentication functions have been freed, if necessary.
720 SMBCCTX
* smbc_set_context(SMBCCTX
* new_context
);
723 * Open a file on an SMB server.
725 * @param furl The smb url of the file to be opened.
727 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
728 * request opening the file read-only,write-only
729 * or read/write. flags may also be bitwise-or'd with
730 * one or more of the following:
731 * O_CREAT - If the file does not exist it will be
733 * O_EXCL - When used with O_CREAT, if the file
734 * already exists it is an error and the open will
736 * O_TRUNC - If the file already exists it will be
738 * O_APPEND The file is opened in append mode
740 * @param mode mode specifies the permissions to use if a new
741 * file is created. It is modified by the
742 * process's umask in the usual way: the permissions
743 * of the created file are (mode & ~umask)
745 * Not currently use, but there for future use.
746 * We will map this to SYSTEM, HIDDEN, etc bits
747 * that reverses the mapping that smbc_fstat does.
749 * @return Valid file handle, < 0 on error with errno set:
750 * - ENOMEM Out of memory
751 * - EINVAL if an invalid parameter passed, like no
752 * file, or smbc_init not called.
753 * - EEXIST pathname already exists and O_CREAT and
755 * - EISDIR pathname refers to a directory and
756 * the access requested involved writing.
757 * - EACCES The requested access to the file is not
759 * - ENODEV The requested share does not exist
760 * - ENOTDIR A file on the path is not a directory
761 * - ENOENT A directory component in pathname does
766 * @note This call uses an underlying routine that may create
767 * a new connection to the server specified in the URL.
768 * If the credentials supplied in the URL, or via the
769 * auth_fn in the smbc_init call, fail, this call will
770 * try again with an empty username and password. This
771 * often gets mapped to the guest account on some machines.
774 int smbc_open(const char *furl
, int flags
, mode_t mode
);
777 * Create a file on an SMB server.
779 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
781 * @param furl The smb url of the file to be created
783 * @param mode mode specifies the permissions to use if a new
784 * file is created. It is modified by the
785 * process's umask in the usual way: the permissions
786 * of the created file are (mode & ~umask)
788 * NOTE, the above is not true. We are dealing with
789 * an SMB server, which has no concept of a umask!
791 * @return Valid file handle, < 0 on error with errno set:
792 * - ENOMEM Out of memory
793 * - EINVAL if an invalid parameter passed, like no
794 * file, or smbc_init not called.
795 * - EEXIST pathname already exists and O_CREAT and
797 * - EISDIR pathname refers to a directory and
798 * the access requested involved writing.
799 * - EACCES The requested access to the file is not
801 * - ENOENT A directory component in pathname does
803 * - ENODEV The requested share does not exist.
808 int smbc_creat(const char *furl
, mode_t mode
);
811 * Read from a file using an opened file handle.
813 * @param fd Open file handle from smbc_open() or smbc_creat()
815 * @param buf Pointer to buffer to recieve read data
817 * @param bufsize Size of buf in bytes
819 * @return Number of bytes read, < 0 on error with errno set:
820 * - EISDIR fd refers to a directory
821 * - EBADF fd is not a valid file descriptor or
822 * is not open for reading.
823 * - EINVAL fd is attached to an object which is
824 * unsuitable for reading, or no buffer passed or
825 * smbc_init not called.
827 * @see smbc_open(), smbc_write()
830 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
834 * Write to a file using an opened file handle.
836 * @param fd Open file handle from smbc_open() or smbc_creat()
838 * @param buf Pointer to buffer to recieve read data
840 * @param bufsize Size of buf in bytes
842 * @return Number of bytes written, < 0 on error with errno set:
843 * - EISDIR fd refers to a directory.
844 * - EBADF fd is not a valid file descriptor or
845 * is not open for reading.
846 * - EINVAL fd is attached to an object which is
847 * unsuitable for reading, or no buffer passed or
848 * smbc_init not called.
850 * @see smbc_open(), smbc_read()
853 ssize_t
smbc_write(int fd
, void *buf
, size_t bufsize
);
857 * Seek to a specific location in a file.
859 * @param fd Open file handle from smbc_open() or smbc_creat()
861 * @param offset Offset in bytes from whence
863 * @param whence A location in the file:
864 * - SEEK_SET The offset is set to offset bytes from
865 * the beginning of the file
866 * - SEEK_CUR The offset is set to current location
868 * - SEEK_END The offset is set to the size of the
869 * file plus offset bytes.
871 * @return Upon successful completion, lseek returns the
872 * resulting offset location as measured in bytes
873 * from the beginning of the file. Otherwise, a value
874 * of (off_t)-1 is returned and errno is set to
875 * indicate the error:
876 * - EBADF Fildes is not an open file descriptor.
877 * - EINVAL Whence is not a proper value or smbc_init
880 * @todo Are all the whence values really supported?
882 * @todo Are errno values complete and correct?
884 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
888 * Close an open file handle.
890 * @param fd The file handle to close
892 * @return 0 on success, < 0 on error with errno set:
893 * - EBADF fd isn't a valid open file descriptor
894 * - EINVAL smbc_init() failed or has not been called
896 * @see smbc_open(), smbc_creat()
898 int smbc_close(int fd
);
901 /**@ingroup directory
902 * Unlink (delete) a file or directory.
904 * @param furl The smb url of the file to delete
906 * @return 0 on success, < 0 on error with errno set:
907 * - EACCES or EPERM Write access to the directory
908 * containing pathname is not allowed or one
909 * of the directories in pathname did not allow
910 * search (execute) permission
911 * - ENOENT A directory component in pathname does
913 * - EINVAL NULL was passed in the file param or
914 * smbc_init not called.
915 * - EACCES You do not have access to the file
916 * - ENOMEM Insufficient kernel memory was available
920 * @todo Are errno values complete and correct?
922 int smbc_unlink(const char *furl
);
925 /**@ingroup directory
926 * Rename or move a file or directory.
928 * @param ourl The original smb url (source url) of file or
929 * directory to be moved
931 * @param nurl The new smb url (destination url) of the file
932 * or directory after the move. Currently nurl must
933 * be on the same share as ourl.
935 * @return 0 on success, < 0 on error with errno set:
936 * - EISDIR nurl is an existing directory, but ourl is
938 * - EEXIST nurl is a non-empty directory,
939 * i.e., contains entries other than "." and ".."
940 * - EINVAL The new url contained a path prefix
941 * of the old, or, more generally, an attempt was
942 * made to make a directory a subdirectory of itself
943 * or smbc_init not called.
944 * - ENOTDIR A component used as a directory in ourl
945 * or nurl path is not, in fact, a directory. Or,
946 * ourl is a directory, and newpath exists but is not
948 * - EACCES or EPERM Write access to the directory
949 * containing ourl or nurl is not allowed for the
950 * process's effective uid, or one of the
951 * directories in ourl or nurl did not allow search
952 * (execute) permission, or ourl was a directory
953 * and did not allow write permission.
954 * - ENOENT A directory component in ourl or nurl
956 * - EXDEV Rename across shares not supported.
957 * - ENOMEM Insufficient kernel memory was available.
958 * - EEXIST The target file, nurl, already exists.
961 * @todo Are we going to support copying when urls are not on the same
962 * share? I say no... NOTE. I agree for the moment.
965 int smbc_rename(const char *ourl
, const char *nurl
);
968 /**@ingroup directory
969 * Open a directory used to obtain directory entries.
971 * @param durl The smb url of the directory to open
973 * @return Valid directory handle. < 0 on error with errno set:
974 * - EACCES Permission denied.
975 * - EINVAL A NULL file/URL was passed, or the URL would
976 * not parse, or was of incorrect form or smbc_init not
978 * - ENOENT durl does not exist, or name is an
979 * - ENOMEM Insufficient memory to complete the
981 * - ENOTDIR name is not a directory.
982 * - EPERM the workgroup could not be found.
983 * - ENODEV the workgroup or server could not be found.
985 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
988 int smbc_opendir(const char *durl
);
991 /**@ingroup directory
992 * Close a directory handle opened by smbc_opendir().
994 * @param dh Directory handle to close
996 * @return 0 on success, < 0 on error with errno set:
997 * - EBADF dh is an invalid directory handle
999 * @see smbc_opendir()
1001 int smbc_closedir(int dh
);
1004 /**@ingroup directory
1005 * Get multiple directory entries.
1007 * smbc_getdents() reads as many dirent structures from the an open
1008 * directory handle into a specified memory area as will fit.
1010 * @param dh Valid directory as returned by smbc_opendir()
1012 * @param dirp pointer to buffer that will receive the directory
1015 * @param count The size of the dirp buffer in bytes
1017 * @returns If any dirents returned, return will indicate the
1018 * total size. If there were no more dirents available,
1019 * 0 is returned. < 0 indicates an error.
1020 * - EBADF Invalid directory handle
1021 * - EINVAL Result buffer is too small or smbc_init
1023 * - ENOENT No such directory.
1024 * @see , smbc_dirent, smbc_readdir(), smbc_open()
1026 * @todo Are errno values complete and correct?
1028 * @todo Add example code so people know how to parse buffers.
1030 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
1033 /**@ingroup directory
1034 * Get a single directory entry.
1036 * @param dh Valid directory as returned by smbc_opendir()
1038 * @return A pointer to a smbc_dirent structure, or NULL if an
1039 * error occurs or end-of-directory is reached:
1040 * - EBADF Invalid directory handle
1041 * - EINVAL smbc_init() failed or has not been called
1043 * @see smbc_dirent, smbc_getdents(), smbc_open()
1045 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
1048 /**@ingroup directory
1049 * Get the current directory offset.
1051 * smbc_telldir() may be used in conjunction with smbc_readdir() and
1054 * @param dh Valid directory as returned by smbc_opendir()
1056 * @return The current location in the directory stream or -1
1057 * if an error occur. The current location is not
1058 * an offset. Becuase of the implementation, it is a
1059 * handle that allows the library to find the entry
1061 * - EBADF dh is not a valid directory handle
1062 * - EINVAL smbc_init() failed or has not been called
1063 * - ENOTDIR if dh is not a directory
1065 * @see smbc_readdir()
1068 off_t
smbc_telldir(int dh
);
1071 /**@ingroup directory
1072 * lseek on directories.
1074 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1075 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1077 * @param fd Valid directory as returned by smbc_opendir()
1079 * @param offset The offset (as returned by smbc_telldir). Can be
1080 * NULL, in which case we will rewind
1082 * @return 0 on success, -1 on failure
1083 * - EBADF dh is not a valid directory handle
1084 * - ENOTDIR if dh is not a directory
1085 * - EINVAL offset did not refer to a valid dirent or
1086 * smbc_init not called.
1088 * @see smbc_telldir()
1091 * @todo In what does the reture and errno values mean?
1093 int smbc_lseekdir(int fd
, off_t offset
);
1095 /**@ingroup directory
1096 * Create a directory.
1098 * @param durl The url of the directory to create
1100 * @param mode Specifies the permissions to use. It is modified
1101 * by the process's umask in the usual way: the
1102 * permissions of the created file are (mode & ~umask).
1104 * @return 0 on success, < 0 on error with errno set:
1105 * - EEXIST directory url already exists
1106 * - EACCES The parent directory does not allow write
1107 * permission to the process, or one of the directories
1108 * - ENOENT A directory component in pathname does not
1110 * - EINVAL NULL durl passed or smbc_init not called.
1111 * - ENOMEM Insufficient memory was available.
1116 int smbc_mkdir(const char *durl
, mode_t mode
);
1119 /**@ingroup directory
1120 * Remove a directory.
1122 * @param durl The smb url of the directory to remove
1124 * @return 0 on success, < 0 on error with errno set:
1125 * - EACCES or EPERM Write access to the directory
1126 * containing pathname was not allowed.
1127 * - EINVAL durl is NULL or smbc_init not called.
1128 * - ENOENT A directory component in pathname does not
1130 * - ENOTEMPTY directory contains entries.
1131 * - ENOMEM Insufficient kernel memory was available.
1133 * @see smbc_mkdir(), smbc_unlink()
1135 * @todo Are errno values complete and correct?
1137 int smbc_rmdir(const char *durl
);
1140 /**@ingroup attribute
1141 * Get information about a file or directory.
1143 * @param url The smb url to get information for
1145 * @param st pointer to a buffer that will be filled with
1146 * standard Unix struct stat information.
1148 * @return 0 on success, < 0 on error with errno set:
1149 * - ENOENT A component of the path file_name does not
1151 * - EINVAL a NULL url was passed or smbc_init not called.
1152 * - EACCES Permission denied.
1153 * - ENOMEM Out of memory
1154 * - ENOTDIR The target dir, url, is not a directory.
1159 int smbc_stat(const char *url
, struct stat
*st
);
1162 /**@ingroup attribute
1163 * Get file information via an file descriptor.
1165 * @param fd Open file handle from smbc_open() or smbc_creat()
1167 * @param st pointer to a buffer that will be filled with
1168 * standard Unix struct stat information.
1170 * @return EBADF filedes is bad.
1171 * - EACCES Permission denied.
1172 * - EBADF fd is not a valid file descriptor
1173 * - EINVAL Problems occurred in the underlying routines
1174 * or smbc_init not called.
1175 * - ENOMEM Out of memory
1177 * @see smbc_stat(), Unix stat()
1180 int smbc_fstat(int fd
, struct stat
*st
);
1183 /**@ingroup attribue
1184 * Change the ownership of a file or directory.
1186 * @param url The smb url of the file or directory to change
1189 * @param owner I have no idea?
1191 * @param group I have not idea?
1193 * @return 0 on success, < 0 on error with errno set:
1194 * - EPERM The effective UID does not match the owner
1195 * of the file, and is not zero; or the owner or group
1196 * were specified incorrectly.
1197 * - ENOENT The file does not exist.
1198 * - ENOMEM Insufficient was available.
1199 * - ENOENT file or directory does not exist
1201 * @todo Are we actually going to be able to implement this function
1203 * @todo How do we abstract owner and group uid and gid?
1206 int smbc_chown(const char *url
, uid_t owner
, gid_t group
);
1209 /**@ingroup attribute
1210 * Change the permissions of a file.
1212 * @param url The smb url of the file or directory to change
1215 * @param mode The permissions to set:
1216 * - Put good explaination of permissions here!
1218 * @return 0 on success, < 0 on error with errno set:
1219 * - EPERM The effective UID does not match the owner
1220 * of the file, and is not zero
1221 * - ENOENT The file does not exist.
1222 * - ENOMEM Insufficient was available.
1223 * - ENOENT file or directory does not exist
1225 * @todo Actually implement this fuction?
1227 * @todo Are errno values complete and correct?
1229 int smbc_chmod(const char *url
, mode_t mode
);
1231 /**@ingroup attribute
1232 * Change the last modification time on a file
1234 * @param url The smb url of the file or directory to change
1235 * the modification time of
1237 * @param tbuf A timeval structure which contains the desired
1238 * modification time. NOTE: Only the tv_sec field is
1239 * used. The tv_usec (microseconds) portion is ignored.
1241 * @return 0 on success, < 0 on error with errno set:
1242 * - EINVAL The client library is not properly initialized
1243 * - EPERM Permission was denied.
1246 int smbc_utimes(const char *url
, struct timeval
*tbuf
);
1249 /**@ingroup attribute
1250 * Change the last modification time on a file
1252 * @param url The smb url of the file or directory to change
1253 * the modification time of
1255 * @param utbuf A utimebuf structure which contains the desired
1256 * modification time. NOTE: Although the structure contains
1257 * an access time as well, the access time value is ignored.
1259 * @return 0 on success, < 0 on error with errno set:
1260 * - EINVAL The client library is not properly initialized
1261 * - ENOMEM No memory was available for internal needs
1262 * - EPERM Permission was denied.
1265 int smbc_utime(const char *fname
, struct utimbuf
*utbuf
);
1268 /**@ingroup attribute
1269 * Set extended attributes for a file. This is used for modifying a file's
1270 * security descriptor (i.e. owner, group, and access control list)
1272 * @param url The smb url of the file or directory to set extended
1275 * @param name The name of an attribute to be changed. Names are of
1276 * one of the following forms:
1278 * system.nt_sec_desc.<attribute name>
1279 * system.nt_sec_desc.*
1280 * system.nt_sec_desc.*+
1282 * where <attribute name> is one of:
1290 * acl+:<name or sid>
1292 * In the forms "system.nt_sec_desc.*" and
1293 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1294 * literal, i.e. the string is provided exactly as shown, and
1295 * the value parameter should contain a complete security
1296 * descriptor with name:value pairs separated by tabs,
1297 * commas, or newlines (not spaces!).
1299 * The plus sign ('+') indicates that SIDs should be mapped
1300 * to names. Without the plus sign, SIDs are not mapped;
1301 * rather they are simply converted to a string format.
1303 * @param value The value to be assigned to the specified attribute name.
1304 * This buffer should contain only the attribute value if the
1305 * name was of the "system.nt_sec_desc.<attribute_name>"
1306 * form. If the name was of the "system.nt_sec_desc.*" form
1307 * then a complete security descriptor, with name:value pairs
1308 * separated by tabs, commas, or newlines (not spaces!),
1309 * should be provided in this value buffer. A complete
1310 * security descriptor will contain one or more entries
1311 * selected from the following:
1313 * REVISION:<revision number>
1314 * OWNER:<sid or name>
1315 * GROUP:<sid or name>
1316 * ACL:<sid or name>:<type>/<flags>/<mask>
1318 * The revision of the ACL specifies the internal Windows NT
1319 * ACL revision for the security descriptor. If not specified
1320 * it defaults to 1. Using values other than 1 may cause
1321 * strange behaviour.
1323 * The owner and group specify the owner and group sids for
1324 * the object. If the attribute name (either '*+' with a
1325 * complete security descriptor, or individual 'owner+' or
1326 * 'group+' attribute names) ended with a plus sign, the
1327 * specified name is resolved to a SID value, using the
1328 * server on which the file or directory resides. Otherwise,
1329 * the value should be provided in SID-printable format as
1330 * S-1-x-y-z, and is used directly. The <sid or name>
1331 * associated with the ACL: attribute should be provided
1334 * @param size The number of the bytes of data in the value buffer
1336 * @param flags A bit-wise OR of zero or more of the following:
1337 * SMBC_XATTR_FLAG_CREATE -
1338 * fail if the named attribute already exists
1339 * SMBC_XATTR_FLAG_REPLACE -
1340 * fail if the attribute does not already exist
1342 * If neither flag is specified, the specified attributes
1343 * will be added or replace existing attributes of the same
1344 * name, as necessary.
1346 * @return 0 on success, < 0 on error with errno set:
1347 * - EINVAL The client library is not properly initialized
1348 * or one of the parameters is not of a correct
1350 * - ENOMEM No memory was available for internal needs
1351 * - EEXIST If the attribute already exists and the flag
1352 * SMBC_XATTR_FLAG_CREAT was specified
1353 * - ENOATTR If the attribute does not exist and the flag
1354 * SMBC_XATTR_FLAG_REPLACE was specified
1355 * - EPERM Permission was denied.
1356 * - ENOTSUP The referenced file system does not support
1357 * extended attributes
1359 * @note Attribute names are compared in a case-insensitive
1360 * fashion. All of the following are equivalent, although
1361 * the all-lower-case name is the preferred format:
1362 * system.nt_sec_desc.owner
1363 * SYSTEM.NT_SEC_DESC.OWNER
1364 * sYsTeM.nt_sEc_desc.owNER
1367 int smbc_setxattr(const char *url
,
1374 /**@ingroup attribute
1375 * Set extended attributes for a file. This is used for modifying a file's
1376 * security descriptor (i.e. owner, group, and access control list). The
1377 * POSIX function which this maps to would act on a symbolic link rather than
1378 * acting on what the symbolic link points to, but with no symbolic links in
1379 * SMB file systems, this function is functionally identical to
1382 * @param url The smb url of the file or directory to set extended
1385 * @param name The name of an attribute to be changed. Names are of
1386 * one of the following forms:
1388 * system.nt_sec_desc.<attribute name>
1389 * system.nt_sec_desc.*
1390 * system.nt_sec_desc.*+
1392 * where <attribute name> is one of:
1400 * acl+:<name or sid>
1402 * In the forms "system.nt_sec_desc.*" and
1403 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1404 * literal, i.e. the string is provided exactly as shown, and
1405 * the value parameter should contain a complete security
1406 * descriptor with name:value pairs separated by tabs,
1407 * commas, or newlines (not spaces!).
1409 * The plus sign ('+') indicates that SIDs should be mapped
1410 * to names. Without the plus sign, SIDs are not mapped;
1411 * rather they are simply converted to a string format.
1413 * @param value The value to be assigned to the specified attribute name.
1414 * This buffer should contain only the attribute value if the
1415 * name was of the "system.nt_sec_desc.<attribute_name>"
1416 * form. If the name was of the "system.nt_sec_desc.*" form
1417 * then a complete security descriptor, with name:value pairs
1418 * separated by tabs, commas, or newlines (not spaces!),
1419 * should be provided in this value buffer. A complete
1420 * security descriptor will contain one or more entries
1421 * selected from the following:
1423 * REVISION:<revision number>
1424 * OWNER:<sid or name>
1425 * GROUP:<sid or name>
1426 * ACL:<sid or name>:<type>/<flags>/<mask>
1428 * The revision of the ACL specifies the internal Windows NT
1429 * ACL revision for the security descriptor. If not specified
1430 * it defaults to 1. Using values other than 1 may cause
1431 * strange behaviour.
1433 * The owner and group specify the owner and group sids for
1434 * the object. If the attribute name (either '*+' with a
1435 * complete security descriptor, or individual 'owner+' or
1436 * 'group+' attribute names) ended with a plus sign, the
1437 * specified name is resolved to a SID value, using the
1438 * server on which the file or directory resides. Otherwise,
1439 * the value should be provided in SID-printable format as
1440 * S-1-x-y-z, and is used directly. The <sid or name>
1441 * associated with the ACL: attribute should be provided
1444 * @param size The number of the bytes of data in the value buffer
1446 * @param flags A bit-wise OR of zero or more of the following:
1447 * SMBC_XATTR_FLAG_CREATE -
1448 * fail if the named attribute already exists
1449 * SMBC_XATTR_FLAG_REPLACE -
1450 * fail if the attribute does not already exist
1452 * If neither flag is specified, the specified attributes
1453 * will be added or replace existing attributes of the same
1454 * name, as necessary.
1456 * @return 0 on success, < 0 on error with errno set:
1457 * - EINVAL The client library is not properly initialized
1458 * or one of the parameters is not of a correct
1460 * - ENOMEM No memory was available for internal needs
1461 * - EEXIST If the attribute already exists and the flag
1462 * SMBC_XATTR_FLAG_CREAT was specified
1463 * - ENOATTR If the attribute does not exist and the flag
1464 * SMBC_XATTR_FLAG_REPLACE was specified
1465 * - EPERM Permission was denied.
1466 * - ENOTSUP The referenced file system does not support
1467 * extended attributes
1469 * @note Attribute names are compared in a case-insensitive
1470 * fashion. All of the following are equivalent, although
1471 * the all-lower-case name is the preferred format:
1472 * system.nt_sec_desc.owner
1473 * SYSTEM.NT_SEC_DESC.OWNER
1474 * sYsTeM.nt_sEc_desc.owNER
1477 int smbc_lsetxattr(const char *url
,
1484 /**@ingroup attribute
1485 * Set extended attributes for a file. This is used for modifying a file's
1486 * security descriptor (i.e. owner, group, and access control list)
1488 * @param fd A file descriptor associated with an open file (as
1489 * previously returned by smbc_open(), to get extended
1492 * @param name The name of an attribute to be changed. Names are of
1493 * one of the following forms:
1495 * system.nt_sec_desc.<attribute name>
1496 * system.nt_sec_desc.*
1497 * system.nt_sec_desc.*+
1499 * where <attribute name> is one of:
1507 * acl+:<name or sid>
1509 * In the forms "system.nt_sec_desc.*" and
1510 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1511 * literal, i.e. the string is provided exactly as shown, and
1512 * the value parameter should contain a complete security
1513 * descriptor with name:value pairs separated by tabs,
1514 * commas, or newlines (not spaces!).
1516 * The plus sign ('+') indicates that SIDs should be mapped
1517 * to names. Without the plus sign, SIDs are not mapped;
1518 * rather they are simply converted to a string format.
1520 * @param value The value to be assigned to the specified attribute name.
1521 * This buffer should contain only the attribute value if the
1522 * name was of the "system.nt_sec_desc.<attribute_name>"
1523 * form. If the name was of the "system.nt_sec_desc.*" form
1524 * then a complete security descriptor, with name:value pairs
1525 * separated by tabs, commas, or newlines (not spaces!),
1526 * should be provided in this value buffer. A complete
1527 * security descriptor will contain one or more entries
1528 * selected from the following:
1530 * REVISION:<revision number>
1531 * OWNER:<sid or name>
1532 * GROUP:<sid or name>
1533 * ACL:<sid or name>:<type>/<flags>/<mask>
1535 * The revision of the ACL specifies the internal Windows NT
1536 * ACL revision for the security descriptor. If not specified
1537 * it defaults to 1. Using values other than 1 may cause
1538 * strange behaviour.
1540 * The owner and group specify the owner and group sids for
1541 * the object. If the attribute name (either '*+' with a
1542 * complete security descriptor, or individual 'owner+' or
1543 * 'group+' attribute names) ended with a plus sign, the
1544 * specified name is resolved to a SID value, using the
1545 * server on which the file or directory resides. Otherwise,
1546 * the value should be provided in SID-printable format as
1547 * S-1-x-y-z, and is used directly. The <sid or name>
1548 * associated with the ACL: attribute should be provided
1551 * @param size The number of the bytes of data in the value buffer
1553 * @param flags A bit-wise OR of zero or more of the following:
1554 * SMBC_XATTR_FLAG_CREATE -
1555 * fail if the named attribute already exists
1556 * SMBC_XATTR_FLAG_REPLACE -
1557 * fail if the attribute does not already exist
1559 * If neither flag is specified, the specified attributes
1560 * will be added or replace existing attributes of the same
1561 * name, as necessary.
1563 * @return 0 on success, < 0 on error with errno set:
1564 * - EINVAL The client library is not properly initialized
1565 * or one of the parameters is not of a correct
1567 * - ENOMEM No memory was available for internal needs
1568 * - EEXIST If the attribute already exists and the flag
1569 * SMBC_XATTR_FLAG_CREAT was specified
1570 * - ENOATTR If the attribute does not exist and the flag
1571 * SMBC_XATTR_FLAG_REPLACE was specified
1572 * - EPERM Permission was denied.
1573 * - ENOTSUP The referenced file system does not support
1574 * extended attributes
1576 * @note Attribute names are compared in a case-insensitive
1577 * fashion. All of the following are equivalent, although
1578 * the all-lower-case name is the preferred format:
1579 * system.nt_sec_desc.owner
1580 * SYSTEM.NT_SEC_DESC.OWNER
1581 * sYsTeM.nt_sEc_desc.owNER
1584 int smbc_fsetxattr(int fd
,
1591 /**@ingroup attribute
1592 * Get extended attributes for a file.
1594 * @param url The smb url of the file or directory to get extended
1597 * @param name The name of an attribute to be retrieved. Names are of
1598 * one of the following forms:
1600 * system.nt_sec_desc.<attribute name>
1601 * system.nt_sec_desc.*
1602 * system.nt_sec_desc.*+
1604 * where <attribute name> is one of:
1612 * acl+:<name or sid>
1614 * In the forms "system.nt_sec_desc.*" and
1615 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1616 * literal, i.e. the string is provided exactly as shown, and
1617 * the value parameter will return a complete security
1618 * descriptor with name:value pairs separated by tabs,
1619 * commas, or newlines (not spaces!).
1621 * The plus sign ('+') indicates that SIDs should be mapped
1622 * to names. Without the plus sign, SIDs are not mapped;
1623 * rather they are simply converted to a string format.
1625 * @param value A pointer to a buffer in which the value of the specified
1626 * attribute will be placed (unless size is zero).
1628 * @param size The size of the buffer pointed to by value. This parameter
1629 * may also be zero, in which case the size of the buffer
1630 * required to hold the attribute value will be returned,
1631 * but nothing will be placed into the value buffer.
1633 * @return 0 on success, < 0 on error with errno set:
1634 * - EINVAL The client library is not properly initialized
1635 * or one of the parameters is not of a correct
1637 * - ENOMEM No memory was available for internal needs
1638 * - EEXIST If the attribute already exists and the flag
1639 * SMBC_XATTR_FLAG_CREAT was specified
1640 * - ENOATTR If the attribute does not exist and the flag
1641 * SMBC_XATTR_FLAG_REPLACE was specified
1642 * - EPERM Permission was denied.
1643 * - ENOTSUP The referenced file system does not support
1644 * extended attributes
1647 int smbc_getxattr(const char *url
,
1653 /**@ingroup attribute
1654 * Get extended attributes for a file. The POSIX function which this maps to
1655 * would act on a symbolic link rather than acting on what the symbolic link
1656 * points to, but with no symbolic links in SMB file systems, this function
1657 * is functionally identical to smbc_getxattr().
1659 * @param url The smb url of the file or directory to get extended
1662 * @param name The name of an attribute to be retrieved. Names are of
1663 * one of the following forms:
1665 * system.nt_sec_desc.<attribute name>
1666 * system.nt_sec_desc.*
1667 * system.nt_sec_desc.*+
1669 * where <attribute name> is one of:
1677 * acl+:<name or sid>
1679 * In the forms "system.nt_sec_desc.*" and
1680 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1681 * literal, i.e. the string is provided exactly as shown, and
1682 * the value parameter will return a complete security
1683 * descriptor with name:value pairs separated by tabs,
1684 * commas, or newlines (not spaces!).
1686 * The plus sign ('+') indicates that SIDs should be mapped
1687 * to names. Without the plus sign, SIDs are not mapped;
1688 * rather they are simply converted to a string format.
1690 * @param value A pointer to a buffer in which the value of the specified
1691 * attribute will be placed (unless size is zero).
1693 * @param size The size of the buffer pointed to by value. This parameter
1694 * may also be zero, in which case the size of the buffer
1695 * required to hold the attribute value will be returned,
1696 * but nothing will be placed into the value buffer.
1698 * @return 0 on success, < 0 on error with errno set:
1699 * - EINVAL The client library is not properly initialized
1700 * or one of the parameters is not of a correct
1702 * - ENOMEM No memory was available for internal needs
1703 * - EEXIST If the attribute already exists and the flag
1704 * SMBC_XATTR_FLAG_CREAT was specified
1705 * - ENOATTR If the attribute does not exist and the flag
1706 * SMBC_XATTR_FLAG_REPLACE was specified
1707 * - EPERM Permission was denied.
1708 * - ENOTSUP The referenced file system does not support
1709 * extended attributes
1712 int smbc_lgetxattr(const char *url
,
1718 /**@ingroup attribute
1719 * Get extended attributes for a file.
1721 * @param fd A file descriptor associated with an open file (as
1722 * previously returned by smbc_open(), to get extended
1725 * @param name The name of an attribute to be retrieved. Names are of
1726 * one of the following forms:
1728 * system.nt_sec_desc.<attribute name>
1729 * system.nt_sec_desc.*
1730 * system.nt_sec_desc.*+
1732 * where <attribute name> is one of:
1740 * acl+:<name or sid>
1742 * In the forms "system.nt_sec_desc.*" and
1743 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1744 * literal, i.e. the string is provided exactly as shown, and
1745 * the value parameter will return a complete security
1746 * descriptor with name:value pairs separated by tabs,
1747 * commas, or newlines (not spaces!).
1749 * The plus sign ('+') indicates that SIDs should be mapped
1750 * to names. Without the plus sign, SIDs are not mapped;
1751 * rather they are simply converted to a string format.
1753 * @param value A pointer to a buffer in which the value of the specified
1754 * attribute will be placed (unless size is zero).
1756 * @param size The size of the buffer pointed to by value. This parameter
1757 * may also be zero, in which case the size of the buffer
1758 * required to hold the attribute value will be returned,
1759 * but nothing will be placed into the value buffer.
1761 * @return 0 on success, < 0 on error with errno set:
1762 * - EINVAL The client library is not properly initialized
1763 * or one of the parameters is not of a correct
1765 * - ENOMEM No memory was available for internal needs
1766 * - EEXIST If the attribute already exists and the flag
1767 * SMBC_XATTR_FLAG_CREAT was specified
1768 * - ENOATTR If the attribute does not exist and the flag
1769 * SMBC_XATTR_FLAG_REPLACE was specified
1770 * - EPERM Permission was denied.
1771 * - ENOTSUP The referenced file system does not support
1772 * extended attributes
1775 int smbc_fgetxattr(int fd
,
1781 /**@ingroup attribute
1782 * Remove extended attributes for a file. This is used for modifying a file's
1783 * security descriptor (i.e. owner, group, and access control list)
1785 * @param url The smb url of the file or directory to remove the extended
1788 * @param name The name of an attribute to be removed. Names are of
1789 * one of the following forms:
1791 * system.nt_sec_desc.<attribute name>
1792 * system.nt_sec_desc.*
1793 * system.nt_sec_desc.*+
1795 * where <attribute name> is one of:
1803 * acl+:<name or sid>
1805 * In the forms "system.nt_sec_desc.*" and
1806 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1807 * literal, i.e. the string is provided exactly as shown, and
1808 * the value parameter will return a complete security
1809 * descriptor with name:value pairs separated by tabs,
1810 * commas, or newlines (not spaces!).
1812 * The plus sign ('+') indicates that SIDs should be mapped
1813 * to names. Without the plus sign, SIDs are not mapped;
1814 * rather they are simply converted to a string format.
1816 * @return 0 on success, < 0 on error with errno set:
1817 * - EINVAL The client library is not properly initialized
1818 * - ENOMEM No memory was available for internal needs
1819 * - EPERM Permission was denied.
1820 * - ENOTSUP The referenced file system does not support
1821 * extended attributes
1824 int smbc_removexattr(const char *url
,
1828 /**@ingroup attribute
1829 * Remove extended attributes for a file. This is used for modifying a file's
1830 * security descriptor (i.e. owner, group, and access control list) The POSIX
1831 * function which this maps to would act on a symbolic link rather than acting
1832 * on what the symbolic link points to, but with no symbolic links in SMB file
1833 * systems, this function is functionally identical to smbc_removexattr().
1835 * @param url The smb url of the file or directory to remove the extended
1838 * @param name The name of an attribute to be removed. Names are of
1839 * one of the following forms:
1841 * system.nt_sec_desc.<attribute name>
1842 * system.nt_sec_desc.*
1843 * system.nt_sec_desc.*+
1845 * where <attribute name> is one of:
1853 * acl+:<name or sid>
1855 * In the forms "system.nt_sec_desc.*" and
1856 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1857 * literal, i.e. the string is provided exactly as shown, and
1858 * the value parameter will return a complete security
1859 * descriptor with name:value pairs separated by tabs,
1860 * commas, or newlines (not spaces!).
1862 * The plus sign ('+') indicates that SIDs should be mapped
1863 * to names. Without the plus sign, SIDs are not mapped;
1864 * rather they are simply converted to a string format.
1866 * @return 0 on success, < 0 on error with errno set:
1867 * - EINVAL The client library is not properly initialized
1868 * - ENOMEM No memory was available for internal needs
1869 * - EPERM Permission was denied.
1870 * - ENOTSUP The referenced file system does not support
1871 * extended attributes
1874 int smbc_lremovexattr(const char *url
,
1878 /**@ingroup attribute
1879 * Remove extended attributes for a file. This is used for modifying a file's
1880 * security descriptor (i.e. owner, group, and access control list)
1882 * @param fd A file descriptor associated with an open file (as
1883 * previously returned by smbc_open(), to get extended
1886 * @param name The name of an attribute to be removed. Names are of
1887 * one of the following forms:
1889 * system.nt_sec_desc.<attribute name>
1890 * system.nt_sec_desc.*
1891 * system.nt_sec_desc.*+
1893 * where <attribute name> is one of:
1901 * acl+:<name or sid>
1903 * In the forms "system.nt_sec_desc.*" and
1904 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1905 * literal, i.e. the string is provided exactly as shown, and
1906 * the value parameter will return a complete security
1907 * descriptor with name:value pairs separated by tabs,
1908 * commas, or newlines (not spaces!).
1910 * The plus sign ('+') indicates that SIDs should be mapped
1911 * to names. Without the plus sign, SIDs are not mapped;
1912 * rather they are simply converted to a string format.
1914 * @return 0 on success, < 0 on error with errno set:
1915 * - EINVAL The client library is not properly initialized
1916 * - ENOMEM No memory was available for internal needs
1917 * - EPERM Permission was denied.
1918 * - ENOTSUP The referenced file system does not support
1919 * extended attributes
1922 int smbc_fremovexattr(int fd
,
1926 /**@ingroup attribute
1927 * List the supported extended attribute names associated with a file
1929 * @param url The smb url of the file or directory to list the extended
1932 * @param list A pointer to a buffer in which the list of attributes for
1933 * the specified file or directory will be placed (unless
1936 * @param size The size of the buffer pointed to by list. This parameter
1937 * may also be zero, in which case the size of the buffer
1938 * required to hold all of the attribute names will be
1939 * returned, but nothing will be placed into the list buffer.
1941 * @return 0 on success, < 0 on error with errno set:
1942 * - EINVAL The client library is not properly initialized
1943 * - ENOMEM No memory was available for internal needs
1944 * - EPERM Permission was denied.
1945 * - ENOTSUP The referenced file system does not support
1946 * extended attributes
1948 * @note This function always returns all attribute names supported
1949 * by NT file systems, regardless of wether the referenced
1950 * file system supports extended attributes (e.g. a Windows
1951 * 2000 machine supports extended attributes if NTFS is used,
1952 * but not if FAT is used, and Windows 98 doesn't support
1953 * extended attributes at all. Whether this is a feature or
1954 * a bug is yet to be decided.
1956 int smbc_listxattr(const char *url
,
1960 /**@ingroup attribute
1961 * List the supported extended attribute names associated with a file The
1962 * POSIX function which this maps to would act on a symbolic link rather than
1963 * acting on what the symbolic link points to, but with no symbolic links in
1964 * SMB file systems, this function is functionally identical to
1967 * @param url The smb url of the file or directory to list the extended
1970 * @param list A pointer to a buffer in which the list of attributes for
1971 * the specified file or directory will be placed (unless
1974 * @param size The size of the buffer pointed to by list. This parameter
1975 * may also be zero, in which case the size of the buffer
1976 * required to hold all of the attribute names will be
1977 * returned, but nothing will be placed into the list buffer.
1979 * @return 0 on success, < 0 on error with errno set:
1980 * - EINVAL The client library is not properly initialized
1981 * - ENOMEM No memory was available for internal needs
1982 * - EPERM Permission was denied.
1983 * - ENOTSUP The referenced file system does not support
1984 * extended attributes
1986 * @note This function always returns all attribute names supported
1987 * by NT file systems, regardless of wether the referenced
1988 * file system supports extended attributes (e.g. a Windows
1989 * 2000 machine supports extended attributes if NTFS is used,
1990 * but not if FAT is used, and Windows 98 doesn't support
1991 * extended attributes at all. Whether this is a feature or
1992 * a bug is yet to be decided.
1994 int smbc_llistxattr(const char *url
,
1998 /**@ingroup attribute
1999 * List the supported extended attribute names associated with a file
2001 * @param fd A file descriptor associated with an open file (as
2002 * previously returned by smbc_open(), to get extended
2005 * @param list A pointer to a buffer in which the list of attributes for
2006 * the specified file or directory will be placed (unless
2009 * @param size The size of the buffer pointed to by list. This parameter
2010 * may also be zero, in which case the size of the buffer
2011 * required to hold all of the attribute names will be
2012 * returned, but nothing will be placed into the list buffer.
2014 * @return 0 on success, < 0 on error with errno set:
2015 * - EINVAL The client library is not properly initialized
2016 * - ENOMEM No memory was available for internal needs
2017 * - EPERM Permission was denied.
2018 * - ENOTSUP The referenced file system does not support
2019 * extended attributes
2021 * @note This function always returns all attribute names supported
2022 * by NT file systems, regardless of wether the referenced
2023 * file system supports extended attributes (e.g. a Windows
2024 * 2000 machine supports extended attributes if NTFS is used,
2025 * but not if FAT is used, and Windows 98 doesn't support
2026 * extended attributes at all. Whether this is a feature or
2027 * a bug is yet to be decided.
2029 int smbc_flistxattr(int fd
,
2034 * Print a file given the name in fname. It would be a URL ...
2036 * @param fname The URL of a file on a remote SMB server that the
2037 * caller wants printed
2039 * @param printq The URL of the print share to print the file to.
2041 * @return 0 on success, < 0 on error with errno set:
2043 * - EINVAL fname or printq was NULL or smbc_init not
2045 * and errors returned by smbc_open
2048 int smbc_print_file(const char *fname
, const char *printq
);
2051 * Open a print file that can be written to by other calls. This simply
2052 * does an smbc_open call after checking if there is a file name on the
2053 * URI. If not, a temporary name is added ...
2055 * @param fname The URL of the print share to print to?
2057 * @returns A file handle for the print file if successful.
2058 * Returns -1 if an error ocurred and errno has the values
2059 * - EINVAL fname was NULL or smbc_init not called.
2060 * - all errors returned by smbc_open
2063 int smbc_open_print_job(const char *fname
);
2066 * List the print jobs on a print share, for the moment, pass a callback
2068 * @param purl The url of the print share to list the jobs of
2070 * @param fn Callback function the receives printjob info
2072 * @return 0 on success, < 0 on error with errno set:
2073 * - EINVAL fname was NULL or smbc_init not called
2076 int smbc_list_print_jobs(const char *purl
, smbc_list_print_job_fn fn
);
2079 * Delete a print job
2081 * @param purl Url of the print share
2083 * @param id The id of the job to delete
2085 * @return 0 on success, < 0 on error with errno set:
2086 * - EINVAL fname was NULL or smbc_init not called
2088 * @todo what errno values are possible here?
2090 int smbc_unlink_print_job(const char *purl
, int id
);
2092 /**@ingroup callback
2093 * Remove a server from the cached server list it's unused.
2095 * @param context pointer to smb context
2097 * @param srv pointer to server to remove
2099 * @return On success, 0 is returned. 1 is returned if the server could not
2100 * be removed. Also useable outside libsmbclient.
2102 int smbc_remove_unused_server(SMBCCTX
* context
, SMBCSRV
* srv
);
2108 /**@ingroup directory
2109 * Convert strings of %xx to their single character equivalent.
2111 * @param dest A pointer to a buffer in which the resulting decoded
2112 * string should be placed. This may be a pointer to the
2113 * same buffer as src_segment.
2115 * @param src A pointer to the buffer containing the URL to be decoded.
2116 * Any %xx sequences herein are converted to their single
2117 * character equivalent. Each 'x' must be a valid hexadecimal
2118 * digit, or that % sequence is left undecoded.
2120 * @param max_dest_len
2121 * The size of the buffer pointed to by dest_segment.
2123 * @return The number of % sequences which could not be converted
2124 * due to lack of two following hexadecimal digits.
2130 smbc_urldecode(char *dest
, char * src
, size_t max_dest_len
);
2137 * Convert any characters not specifically allowed in a URL into their %xx
2140 * @param dest A pointer to a buffer in which the resulting encoded
2141 * string should be placed. Unlike smbc_urldecode(), this
2142 * must be a buffer unique from src.
2144 * @param src A pointer to the buffer containing the string to be encoded.
2145 * Any character not specifically allowed in a URL is converted
2146 * into its hexadecimal value and encoded as %xx.
2148 * @param max_dest_len
2149 * The size of the buffer pointed to by dest_segment.
2151 * @returns The remaining buffer length.
2157 smbc_urlencode(char * dest
, char * src
, int max_dest_len
);
2163 /**@ingroup directory
2164 * Return the version of the linked Samba code, and thus the version of the
2165 * libsmbclient code.
2167 * @return The version string.
2179 #endif /* SMBCLIENT_H_INCLUDED */