[become] / src / userdb.h

/* -*-c-*-
 *
 * $Id*
 *
 * User database management
 *
 * (c) 1998 EBI
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of `become'
 *
 * `Become' is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * `Become' is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with `become'; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------*
 *
 * $Log: userdb.h,v $
 * Revision 1.4  1998/01/12 16:46:38  mdw
 * Fix copyright date.
 *
 * Revision 1.3  1997/08/20  16:25:08  mdw
 * Rename `userdb_reinit' to `userdb_end' for more sensible restart.
 *
 * Revision 1.2  1997/08/04 10:24:26  mdw
 * Sources placed under CVS control.
 *
 * Revision 1.1  1997/07/21  13:47:42  mdw
 * Initial revision
 *
 */

#ifndef USERDB_H
#define USERDB_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Required headers --------------------------------------------------*/

#include <grp.h>
#include <pwd.h>

#ifndef SYM_H
#  include "sym.h"
#endif

/*----- Type definitions --------------------------------------------------*/

/* --- Iterator objects --- */

typedef sym_iter userdb_iter;

/*----- User and group block manipulation ---------------------------------*/

/* --- @userdb_copyUser@ --- *
 *
 * Arguments:   @struct passwd *pw@ = pointer to block to copy
 *
 * Returns:     Pointer to the copy.
 *
 * Use:         Copies a user block.  The copy is `deep' so all the strings
 *              are copied too.  Free the copy with @userdb_freeUser@ when
 *              you don't want it any more.
 */

extern struct passwd *userdb_copyUser(struct passwd */*pw*/);

/* --- @userdb_freeUser@ --- *
 *
 * Arguments:   @void *rec@ = pointer to a user record
 *
 * Returns:     ---
 *
 * Use:         Frees a user record.
 */

extern void userdb_freeUser(void */*rec*/);

/* --- @userdb_copyGroup@ --- *
 *
 * Arguments:   @struct group *gr@ = pointer to group block
 *
 * Returns:     Pointer to copied block
 *
 * Use:         Copies a group block.  The copy is `deep' so all the strings
 *              are copied too.  Free the copy with @userdb_freeGroup@ when
 *              you don't want it any more.
 */

extern struct group *userdb_copyGroup(struct group */*gr*/);

/* --- @userdb_freeGroup@ --- *
 *
 * Arguments:   @void *rec@ = pointer to a group record
 *
 * Returns:     ---
 *
 * Use:         Frees a group record.
 */

extern void userdb_freeGroup(void */*rec*/);

/*----- Internal user database mapping ------------------------------------*/

/* --- @userdb_local@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     ---
 *
 * Use:         Reads the local list of users into the maps.
 */

extern void userdb_local(void);

/* --- @userdb_yp@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     ---
 *
 * Use:         Fetches the YP database of users.
 */

extern void userdb_yp(void);

/* --- @userdb_userByName@, @userdb_userById@ --- *
 *
 * Arguments:   @const char *name@ = pointer to user's name
 *              @uid_t id@ = user id to find
 *
 * Returns:     Pointer to user block, or zero if not found.
 *
 * Use:         Looks up a user by name or id.
 */

extern struct passwd *userdb_userByName(const char */*name*/);
extern struct passwd *userdb_userById(uid_t /*id*/);

/* --- @userdb_iterateUsers@, @userdb_iterateUsers_r@ --- *
 *
 * Arguments:   @userdb_iter *i@ = pointer to a symbol table iterator object
 *
 * Returns:     ---
 *
 * Use:         Initialises an iteration for the user database.
 */

extern void userdb_iterateUsers(void);
extern void userdb_iterateUsers_r(userdb_iter */*i*/);

/* --- @userdb_nextUser@, @userdb_nextUser_r@ --- *
 *
 * Arguments:   @userdb_iter *i@ = pointer to a symbol table iterator oject
 *
 * Returns:     Pointer to the next user block, or null.
 *
 * Use:         Returns another user block.
 */

extern struct passwd *userdb_nextUser(void);
extern struct passwd *userdb_nextUser_r(userdb_iter */*i*/);

/* --- @userdb_groupByName@, @userdb_groupById@ --- *
 *
 * Arguments:   @const char *name@ = pointer to group's name
 *              @gid_t id@ = group id to find
 *
 * Returns:     Pointer to group block, or zero if not found.
 *
 * Use:         Looks up a group by name or id.
 */

extern struct group *userdb_groupByName(const char */*name*/);
extern struct group *userdb_groupById(gid_t /*id*/);

/* --- @userdb_iterateGroups@, @userdb_iterateGroups_r@ --- *
 *
 * Arguments:   @userdb_iter *i@ = pointer to a symbol table iterator object
 *
 * Returns:     ---
 *
 * Use:         Initialises an iteration for the group database.
 */

extern void userdb_iterateGroups(void);
extern void userdb_iterateGroups_r(userdb_iter */*i*/);

/* --- @userdb_nextGroup@, @userdb_nextGroup_r@ --- *
 *
 * Arguments:   @userdb_iter *i@ = pointer to a symbol table iterator oject
 *
 * Returns:     Pointer to the next group block, or null.
 *
 * Use:         Returns another group block.
 */

extern struct group *userdb_nextGroup(void);
extern struct group *userdb_nextGroup_r(userdb_iter */*i*/);

/* --- @userdb_init@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     ---
 *
 * Use:         Initialises the user database.
 */

extern void userdb_init(void);

/* --- @userdb_end@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     ---
 *
 * Use:         Closes down the user database.
 */

extern void userdb_end(void);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif