isc_add_user()
Go Up to API Function Reference
Adds a user record to the InterBase security database (admin.ib by default).
Use of this function is deprecated. It is replaced by a full featured Services API. See Working with Services and the reference entry for isc_service_start().
Syntax
ISC_STATUS isc_add_user(ISC_STATUS *status USER_SEC_DATA *user_sec_data);
| Parameter | Type | Description |
|---|---|---|
|
status vector |
|
Pointer to the error status vector |
|
user_sec_data |
|
Pointer to a struct that is defined in |
Description
The three security functions, isc_add_user(), isc_delete_user(), and isc_modify_user() mirror functionality that is available in the gsec command-line utility. isc_add_user() adds a record to the InterBase security database (admin.ib by default).
At a minimum, you must provide the user name and password. If the server is not local, you must also provide a server name and protocol. Valid choices for the protocol field are sec_protocol_tcpip, sec_protocol_netbeui, and sec_protocol_local.
InterBase reads the settings for the ISC_USER and ISC_PASSWORD environment variables if you do not provide a DBA user name and password.
The definition for the USER_SEC_DATA structure in ibase.h is as follows:
typedef struct {
short sec_flags; /* which fields are specified */
int uid; /* the user's id */
int gid; /* the user's group id */
int protocol; /* protocol to use for connection */
char *server; /* server to administer */
char *user_name; /* the user's name */
char *password; /* the user's password */
char *group_name; /* the group name */
char *first_name; /* the user's first name */
char *middle_name; /* the user's middle name */
char *last_name; /* the user's last name */
char *dba_user_name; /* the dba user name */
char *dba_password; /* the dba password */
} USER_SEC_DATA;
When you pass this structure to one of the three security functions, you can tell it which fields you have specified by doing a bitwise OR of the following values, which are defined in ibase.h:
sec_uid_spec 0x01
sec_gid_spec 0x02
sec_server_spec 0x04
sec_password_spec 0x08
sec_group_name_spec 0x10
sec_first_name_spec 0x20
sec_middle_name_spec 0x40
sec_last_name_spec 0x80
sec_dba_user_name_spec 0x100
sec_dba_password_spec 0x200
No bit values are available for user name and password, since they are required.
The following error messages exist for this function:
| Code | Value | Description |
|---|---|---|
|
|
335544747 |
The user name passed in is greater than 31 bytes. |
|
|
335544748 |
The password passed in is longer than 8 bytes. |
|
|
335544749 |
The operation requires a user name. |
|
|
335544750 |
The operation requires a password. |
|
|
335544751 |
The protocol specified is invalid. |
|
|
335544752 |
The user name being added already exists in the security database. |
|
|
335544753 |
The user name was not found in the security database. |
|
|
335544754 |
An unknown error occurred while adding a user. |
|
|
335544755 |
An unknown error occurred while deleting a user. |
|
|
335544756 |
An unknown error occurred while modifying a user. |
|
|
335544757 |
An unknown error occurred while updating the security database. |
Example
The following example adds a user (“Socks”) to the password database, using the bitwise OR technique for passing values from the USER_SEC_DATA structure.
{
ISC_STATUS status[20];
USER_SEC_DATA sec;
sec.server = "kennel";
sec.dba_user_name = "sysdba";
sec.dba_password = "masterkey";
sec.protocol = sec_protocol_tcpip;
sec.first_name = "Socks";
sec.last_name = "Clinton";
sec.user_name = "socks";
sec.password = "2meow!"; /* Note: do not hardcode passwords */
sec.sec_flags = sec_server_spec
| sec_password_spec
| sec_dba_user_name_spec
| sec_dba_password_spec
| sec_first_name_spec
| sec_last_name_spec;
isc_add_user(status, &sec);
/* check status for errors */
if (status[0] == 1 && status[1]) {
switch (status[1]) {
case isc_usrname_too_long:
printf("Security database cannot accept long user names\n");
break;
...
}
}
}
Return value
isc_add_user() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For more information about examining the status vector, see Handling Error Conditions.