Miscellaneous Functions
[Libsmbclient]

Functions that don't fit in to other categories [詳細]

関数
SMBCCTX *	smbc_new_context (void)
	Create a new SBMCCTX (a context).
int	smbc_free_context (SMBCCTX *context, int shutdown_ctx)
	Delete a SBMCCTX (a context) acquired from smbc_new_context().
void	smbc_option_set (SMBCCTX *context, char *option_name,...)
	Each time the context structure is changed, we have binary backward compatibility issues.
SMBCCTX *	smbc_init_context (SMBCCTX *context)
	Initialize a SBMCCTX (a context).
int	smbc_init (smbc_get_auth_data_fn fn, int debug)
	Initialize the samba client library.
SMBCCTX *	smbc_set_context (SMBCCTX *new_context)
	Set or retrieve the compatibility library's context pointer

---

説明

Functions that don't fit in to other categories

---

関数

SMBCCTX* smbc_new_context

(

void

)

Create a new SBMCCTX (a context).

Must be called before the context is passed to smbc_context_init()

戻り値:

The given SMBCCTX pointer on success, NULL on error with errno set:

• ENOMEM Out of memory

参照:

smbc_free_context(), smbc_init_context()

覚え書き:

Do not forget to smbc_init_context() the returned SMBCCTX pointer !

libsmbclient.c の 6222 行で定義されています。

参照先 smbc_internal_data::_share_mode・_SMBCCTX::_smbc_options::browse_max_lmb_count・_SMBCCTX::callbacks・_SMBCCTX::_smbc_callbacks::check_server_fn・_SMBCCTX::chmod・_SMBCCTX::close_fn・_SMBCCTX::closedir・_SMBCCTX::creat・_SMBCCTX::debug・errno・_SMBCCTX::fstat・_SMBCCTX::fstatdir・_SMBCCTX::getdents・_SMBCCTX::getxattr・_SMBCCTX::internal・_SMBCCTX::list_print_jobs・_SMBCCTX::listxattr・_SMBCCTX::lseek・_SMBCCTX::lseekdir・_SMBCCTX::mkdir・_SMBCCTX::_smbc_options::one_share_per_server・_SMBCCTX::open・_SMBCCTX::open_print_job・_SMBCCTX::opendir・_SMBCCTX::options・_SMBCCTX::print_file・_SMBCCTX::read・_SMBCCTX::readdir・_SMBCCTX::_smbc_callbacks::remove_unused_server_fn・_SMBCCTX::removexattr・_SMBCCTX::rename・_SMBCCTX::rmdir・_SMBCCTX::setxattr・smbc_check_server()・smbc_chmod_ctx()・smbc_close_ctx()・smbc_closedir_ctx()・smbc_creat_ctx()・smbc_default_cache_functions()・smbc_fstat_ctx()・smbc_fstatdir_ctx()・smbc_getdents_ctx()・smbc_getxattr_ctx()・smbc_list_print_jobs_ctx()・smbc_listxattr_ctx()・smbc_lseek_ctx()・smbc_lseekdir_ctx()・smbc_mkdir_ctx()・smbc_open_ctx()・smbc_open_print_job_ctx()・smbc_opendir_ctx()・smbc_print_file_ctx()・smbc_read_ctx()・smbc_readdir_ctx()・smbc_remove_unused_server()・smbc_removexattr_ctx()・smbc_rename_ctx()・smbc_rmdir_ctx()・smbc_setxattr_ctx()・SMBC_SHAREMODE_DENY_NONE・smbc_stat_ctx()・smbc_telldir_ctx()・smbc_unlink_ctx()・smbc_unlink_print_job_ctx()・smbc_utimes_ctx()・smbc_write_ctx()・_SMBCCTX::stat・_SMBCCTX::telldir・_SMBCCTX::timeout・_SMBCCTX::unlink・_SMBCCTX::unlink_print_job・_SMBCCTX::_smbc_options::urlencode_readdir_entries・_SMBCCTX::utimes・_SMBCCTX::write.

参照元 cac_NewServerHandle()・smbc_init().

{
        SMBCCTX *context;

        context = SMB_MALLOC_P(SMBCCTX);
        if (!context) {
                errno = ENOMEM;
                return NULL;
        }

        ZERO_STRUCTP(context);

        context->internal = SMB_MALLOC_P(struct smbc_internal_data);
        if (!context->internal) {
                SAFE_FREE(context);
                errno = ENOMEM;
                return NULL;
        }

        ZERO_STRUCTP(context->internal);

        
        /* ADD REASONABLE DEFAULTS */
        context->debug            = 0;
        context->timeout          = 20000; /* 20 seconds */

        context->options.browse_max_lmb_count      = 3;    /* # LMBs to query */
        context->options.urlencode_readdir_entries = False;/* backward compat */
        context->options.one_share_per_server      = False;/* backward compat */
        context->internal->_share_mode             = SMBC_SHAREMODE_DENY_NONE;
                                /* backward compat */

        context->open                              = smbc_open_ctx;
        context->creat                             = smbc_creat_ctx;
        context->read                              = smbc_read_ctx;
        context->write                             = smbc_write_ctx;
        context->close_fn                          = smbc_close_ctx;
        context->unlink                            = smbc_unlink_ctx;
        context->rename                            = smbc_rename_ctx;
        context->lseek                             = smbc_lseek_ctx;
        context->stat                              = smbc_stat_ctx;
        context->fstat                             = smbc_fstat_ctx;
        context->opendir                           = smbc_opendir_ctx;
        context->closedir                          = smbc_closedir_ctx;
        context->readdir                           = smbc_readdir_ctx;
        context->getdents                          = smbc_getdents_ctx;
        context->mkdir                             = smbc_mkdir_ctx;
        context->rmdir                             = smbc_rmdir_ctx;
        context->telldir                           = smbc_telldir_ctx;
        context->lseekdir                          = smbc_lseekdir_ctx;
        context->fstatdir                          = smbc_fstatdir_ctx;
        context->chmod                             = smbc_chmod_ctx;
        context->utimes                            = smbc_utimes_ctx;
        context->setxattr                          = smbc_setxattr_ctx;
        context->getxattr                          = smbc_getxattr_ctx;
        context->removexattr                       = smbc_removexattr_ctx;
        context->listxattr                         = smbc_listxattr_ctx;
        context->open_print_job                    = smbc_open_print_job_ctx;
        context->print_file                        = smbc_print_file_ctx;
        context->list_print_jobs                   = smbc_list_print_jobs_ctx;
        context->unlink_print_job                  = smbc_unlink_print_job_ctx;

        context->callbacks.check_server_fn         = smbc_check_server;
        context->callbacks.remove_unused_server_fn = smbc_remove_unused_server;

        smbc_default_cache_functions(context);

        return context;
}

int smbc_free_context	(	SMBCCTX *	context,
		int	shutdown_ctx
	)

Delete a SBMCCTX (a context) acquired from smbc_new_context().

The context will be deleted if possible.

引数:

	context	A pointer to a SMBCCTX obtained from smbc_new_context()
	shutdown_ctx	If 1, all connections and files will be closed even if they are busy.

戻り値:

Returns 0 on succes. Returns 1 on failure with errno set:

• EBUSY Server connections are still used, Files are open or cache could not be purged
• EBADF context == NULL

参照:

smbc_new_context()

覚え書き:

It is advised to clean up all the contexts with shutdown_ctx set to 1 just before exit()'ing. When shutdown_ctx is 0, this function can be use in periodical cleanup functions for example.

libsmbclient.c の 6300 行で定義されています。

参照先 smbc_internal_data::_files・smbc_internal_data::_servers・_SMBCCTX::callbacks・cli_shutdown()・_SMBCCTX::close_fn・errno・_SMBCCTX::internal・_SMBCCTX::netbios_name・_SMBCFILE::next・_SMBCSRV::next・_SMBCCTX::_smbc_callbacks::purge_cached_fn・_SMBCCTX::_smbc_callbacks::remove_cached_srv_fn・_SMBCCTX::user・_SMBCCTX::workgroup.

参照元 cac_FreeHandle()・smbc_init().

{
        if (!context) {
                errno = EBADF;
                return 1;
        }
        
        if (shutdown_ctx) {
                SMBCFILE * f;
                DEBUG(1,("Performing aggressive shutdown.\n"));
                
                f = context->internal->_files;
                while (f) {
                        (context->close_fn)(context, f);
                        f = f->next;
                }
                context->internal->_files = NULL;

                /* First try to remove the servers the nice way. */
                if (context->callbacks.purge_cached_fn(context)) {
                        SMBCSRV * s;
                        SMBCSRV * next;
                        DEBUG(1, ("Could not purge all servers, "
                                  "Nice way shutdown failed.\n"));
                        s = context->internal->_servers;
                        while (s) {
                                DEBUG(1, ("Forced shutdown: %p (fd=%d)\n",
                                          s, s->cli->fd));
                                cli_shutdown(s->cli);
                                (context->callbacks.remove_cached_srv_fn)(context,
                                                                          s);
                                next = s->next;
                                DLIST_REMOVE(context->internal->_servers, s);
                                SAFE_FREE(s);
                                s = next;
                        }
                        context->internal->_servers = NULL;
                }
        }
        else {
                /* This is the polite way */    
                if ((context->callbacks.purge_cached_fn)(context)) {
                        DEBUG(1, ("Could not purge all servers, "
                                  "free_context failed.\n"));
                        errno = EBUSY;
                        return 1;
                }
                if (context->internal->_servers) {
                        DEBUG(1, ("Active servers in context, "
                                  "free_context failed.\n"));
                        errno = EBUSY;
                        return 1;
                }
                if (context->internal->_files) {
                        DEBUG(1, ("Active files in context, "
                                  "free_context failed.\n"));
                        errno = EBUSY;
                        return 1;
                }               
        }

        /* Things we have to clean up */
        SAFE_FREE(context->workgroup);
        SAFE_FREE(context->netbios_name);
        SAFE_FREE(context->user);
        
        DEBUG(3, ("Context %p successfully freed\n", context));
        SAFE_FREE(context->internal);
        SAFE_FREE(context);
        return 0;
}

void smbc_option_set	(	SMBCCTX *	context,
		char *	option_name,
			...
	)

Each time the context structure is changed, we have binary backward compatibility issues.

Instead of modifying the public portions of the context structure to add new options, instead, we put them in the internal portion of the context structure and provide a set function for these new options.

引数:

	context	A pointer to a SMBCCTX obtained from smbc_new_context()
	option_name	The name of the option for which the value is to be set
	option_value	The new value of the option being set

libsmbclient.c の 6382 行で定義されています。

参照先 smbc_internal_data::_auth_fn_with_context・smbc_internal_data::_debug_stderr・smbc_internal_data::_full_time_names・smbc_internal_data::_share_mode・smbc_internal_data::_user_data・auth_fn()・_SMBCCTX::internal.

{
        va_list ap;
        union {
                int i;
                BOOL b;
                smbc_get_auth_data_with_context_fn auth_fn;
                void *v;
        } option_value;

        va_start(ap, option_name);

        if (strcmp(option_name, "debug_to_stderr") == 0) {
                /*
                 * Log to standard error instead of standard output.
                 */
                option_value.b = (BOOL) va_arg(ap, int);
                context->internal->_debug_stderr = option_value.b;

        } else if (strcmp(option_name, "full_time_names") == 0) {
                /*
                 * Use new-style time attribute names, e.g. WRITE_TIME rather
                 * than the old-style names such as M_TIME.  This allows also
                 * setting/getting CREATE_TIME which was previously
                 * unimplemented.  (Note that the old C_TIME was supposed to
                 * be CHANGE_TIME but was confused and sometimes referred to
                 * CREATE_TIME.)
                 */
                option_value.b = (BOOL) va_arg(ap, int);
                context->internal->_full_time_names = option_value.b;

        } else if (strcmp(option_name, "open_share_mode") == 0) {
                /*
                 * The share mode to use for files opened with
                 * smbc_open_ctx().  The default is SMBC_SHAREMODE_DENY_NONE.
                 */
                option_value.i = va_arg(ap, int);
                context->internal->_share_mode =
                        (smbc_share_mode) option_value.i;

        } else if (strcmp(option_name, "auth_function") == 0) {
                /*
                 * Use the new-style authentication function which includes
                 * the context.
                 */
                option_value.auth_fn =
                        va_arg(ap, smbc_get_auth_data_with_context_fn);
                context->internal->_auth_fn_with_context =
                        option_value.auth_fn;
        } else if (strcmp(option_name, "user_data") == 0) {
                /*
                 * Save a user data handle which may be retrieved by the user
                 * with smbc_option_get()
                 */
                option_value.v = va_arg(ap, void *);
                context->internal->_user_data = option_value.v;
        }

        va_end(ap);
}

SMBCCTX* smbc_init_context

(

SMBCCTX *

context

)

Initialize a SBMCCTX (a context).

Must be called before using any SMBCCTX API function

引数:

context

A pointer to a SMBCCTX obtained from smbc_new_context()

戻り値:

A pointer to the given SMBCCTX on success, NULL on error with errno set:

• EBADF NULL context given
• ENOMEM Out of memory
• ENOENT The smb.conf file would not load

参照:

smbc_new_context()

覚え書き:

my_context = smbc_init_context(smbc_new_context()) is perfectly safe, but it might leak memory on smbc_context_init() failure. Avoid this. You'll have to call smbc_free_context() yourself on failure.

libsmbclient.c の 6503 行で定義されています。

参照先 smbc_internal_data::_auth_fn_with_context・smbc_internal_data::_debug_stderr・smbc_internal_data::_initialized・_SMBCCTX::_smbc_callbacks::auth_fn・BlockSignals()・_SMBCCTX::callbacks・dbf・_SMBCCTX::debug・DEBUGLEVEL・dyn_CONFIGFILE・errno・global_myname・in_client・_SMBCCTX::internal・load_case_tables()・load_interfaces()・lp_workgroup()・_SMBCCTX::netbios_name・reopen_logs()・setup_logging()・smbc_initialized・sys_getpid()・_SMBCCTX::timeout・_SMBCCTX::user・_SMBCCTX::workgroup・x_setbuf()・x_stderr.

参照元 cac_Connect()・smbc_init().

{
        pstring conf;
        int pid;
        char *user = NULL;
        char *home = NULL;

        if (!context || !context->internal) {
                errno = EBADF;
                return NULL;
        }

        /* Do not initialise the same client twice */
        if (context->internal->_initialized) { 
                return 0;
        }

        if ((!context->callbacks.auth_fn &&
             !context->internal->_auth_fn_with_context) ||
            context->debug < 0 ||
            context->debug > 100) {

                errno = EINVAL;
                return NULL;

        }

        if (!smbc_initialized) {
                /*
                 * Do some library-wide intializations the first time we get
                 * called
                 */
                BOOL conf_loaded = False;

                /* Set this to what the user wants */
                DEBUGLEVEL = context->debug;
                
                load_case_tables();

                setup_logging("libsmbclient", True);
                if (context->internal->_debug_stderr) {
                        dbf = x_stderr;
                        x_setbuf(x_stderr, NULL);
                }

                /* Here we would open the smb.conf file if needed ... */
                
                in_client = True; /* FIXME, make a param */

                home = getenv("HOME");
                if (home) {
                        slprintf(conf, sizeof(conf), "%s/.smb/smb.conf", home);
                        if (lp_load(conf, True, False, False, True)) {
                                conf_loaded = True;
                        } else {
                                DEBUG(5, ("Could not load config file: %s\n",
                                          conf));
                        }
                }
 
                if (!conf_loaded) {
                        /*
                         * Well, if that failed, try the dyn_CONFIGFILE
                         * Which points to the standard locn, and if that
                         * fails, silently ignore it and use the internal
                         * defaults ...
                         */

                        if (!lp_load(dyn_CONFIGFILE, True, False, False, False)) {
                                DEBUG(5, ("Could not load config file: %s\n",
                                          dyn_CONFIGFILE));
                        } else if (home) {
                                /*
                                 * We loaded the global config file.  Now lets
                                 * load user-specific modifications to the
                                 * global config.
                                 */
                                slprintf(conf, sizeof(conf),
                                         "%s/.smb/smb.conf.append", home);
                                if (!lp_load(conf, True, False, False, False)) {
                                        DEBUG(10,
                                              ("Could not append config file: "
                                               "%s\n",
                                               conf));
                                }
                        }
                }

                load_interfaces();  /* Load the list of interfaces ... */
                
                reopen_logs();  /* Get logging working ... */
        
                /* 
                 * Block SIGPIPE (from lib/util_sock.c: write())  
                 * It is not needed and should not stop execution 
                 */
                BlockSignals(True, SIGPIPE);
                
                /* Done with one-time initialisation */
                smbc_initialized = 1; 

        }
        
        if (!context->user) {
                /*
                 * FIXME: Is this the best way to get the user info? 
                 */
                user = getenv("USER");
                /* walk around as "guest" if no username can be found */
                if (!user) context->user = SMB_STRDUP("guest");
                else context->user = SMB_STRDUP(user);
        }

        if (!context->netbios_name) {
                /*
                 * We try to get our netbios name from the config. If that
                 * fails we fall back on constructing our netbios name from
                 * our hostname etc
                 */
                if (global_myname()) {
                        context->netbios_name = SMB_STRDUP(global_myname());
                }
                else {
                        /*
                         * Hmmm, I want to get hostname as well, but I am too
                         * lazy for the moment
                         */
                        pid = sys_getpid();
                        context->netbios_name = (char *)SMB_MALLOC(17);
                        if (!context->netbios_name) {
                                errno = ENOMEM;
                                return NULL;
                        }
                        slprintf(context->netbios_name, 16,
                                 "smbc%s%d", context->user, pid);
                }
        }

        DEBUG(1, ("Using netbios name %s.\n", context->netbios_name));

        if (!context->workgroup) {
                if (lp_workgroup()) {
                        context->workgroup = SMB_STRDUP(lp_workgroup());
                }
                else {
                        /* TODO: Think about a decent default workgroup */
                        context->workgroup = SMB_STRDUP("samba");
                }
        }

        DEBUG(1, ("Using workgroup %s.\n", context->workgroup));
                                        
        /* shortest timeout is 1 second */
        if (context->timeout > 0 && context->timeout < 1000) 
                context->timeout = 1000;

        /*
         * FIXME: Should we check the function pointers here? 
         */

        context->internal->_initialized = True;
        
        return context;
}

int smbc_init	(	smbc_get_auth_data_fn	fn,
		int	debug
	)

Initialize the samba client library.

Must be called before using any of the smbclient API function

引数:

	fn	The function that will be called to obtaion authentication credentials.
	debug	Allows caller to set the debug level. Can be changed in smb.conf file. Allows caller to set debugging if no smb.conf.

戻り値:

0 on success, < 0 on error with errno set:

• ENOMEM Out of memory
• ENOENT The smb.conf file would not load

libsmb_compat.c の 116 行で定義されています。

参照先 _SMBCCTX::_smbc_callbacks::auth_fn・_SMBCCTX::callbacks・_SMBCCTX::debug・smbc_compat_initialized・smbc_free_context()・smbc_init_context()・smbc_new_context()・statcont.

参照元 main()・process().

{
        if (!smbc_compat_initialized) {
                statcont = smbc_new_context();
                if (!statcont) 
                        return -1;

                statcont->debug = debug;
                statcont->callbacks.auth_fn = fn;
                
                if (!smbc_init_context(statcont)) {
                        smbc_free_context(statcont, False);
                        return -1;
                }

                smbc_compat_initialized = 1;

                return 0;
        }
        return 0;
}

SMBCCTX* smbc_set_context

(

SMBCCTX *

new_context

)

Set or retrieve the compatibility library's context pointer

引数:

context

New context to use, or NULL. If a new context is provided, it must have allocated with smbc_new_context() and initialized with smbc_init_context(), followed, optionally, by some manual changes to some of the non-internal fields.

戻り値:

The old context.

参照:

smbc_new_context(), smbc_init_context(), smbc_init()

覚え書き:

This function may be called prior to smbc_init() to force use of the next context without any internal calls to smbc_new_context() or smbc_init_context(). It may also be called after smbc_init() has already called those two functions, to replace the existing context with a new one. Care should be taken, in this latter case, to ensure that the server cache and any data allocated by the authentication functions have been freed, if necessary.

libsmb_compat.c の 139 行で定義されています。

参照先 smbc_compat_initialized・statcont.

{
        SMBCCTX *old_context = statcont;

        if (context) {
                /* Save provided context.  It must have been initialized! */
                statcont = context;

                /* You'd better know what you're doing.  We won't help you. */
                smbc_compat_initialized = 1;
        }
        
        return old_context;
}

---