isc_modify_user()

Modifies a user record from the InterBase security database (admin.ib by default).

Note: 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_modify_user(
 ISC_STATUS *status
 USER_SEC_DATA *user_sec_data);

Parameter	Type	Description
`status vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`user_sec_data`	`USER_SEC_DATA` `*`	Pointer to a struct that is defined in `ibase.h`.

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_modify_user() modifies a record from the InterBase security database.

At a minimum, you must provide the user name. Any additional user information that you supply, such as first name, last name, or password, overwrites the information that is already in the security database.

If the server is not local, you must provide both a server name and a 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 struct 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 struct 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:

Error messages for isc_modifyuser()
Code	Value	Description
`isc_usrname_too_long`	335544747	The user name passed in is greater than 31 bytes.
`isc_password_too_long`	335544748	The password passed in is longer than 8 bytes.
`isc_usrname_required`	335544749	The operation requires a user name.
`isc_password_required`	335544750	The operation requires a password.
`isc_bad_protocol`	335544751	The protocol specified is invalid.
`isc_dup_usrname_found`	335544752	The user name being added already exists in the security database.
`isc_usrname_not_found`	335544753	The user name was not found in the security database.
`isc_error_adding_sec_record`	335544754	An unknown error occurred while adding a user.
`isc_error_deleting_sec_record`	335544755	An unknown error occurred while deleting a user.
`isc_error_modifying_sec_record`	335544756	An unknown error occurred while modifying a user.
`isc_error_updating_sec_db`	335544757	An unknown error occurred while updating the security database.

Example

The following example modifies the InterBase security database to change the password for the user Socks, using the bitwise OR technique for passing values from the USER_SEC_DATA struct.

{
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.user_name = "socks";
sec.password = "feed_me!"; /* Note: do not hardcode passwords */
sec.sec_flags = sec_server_spec
| sec_password_spec
| sec_dba_user_name_spec
| sec_dba_password_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_modify_user() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. See the “Description” section for this function for a list of error codes. For more information about examining the status vector, see Handling Error Conditions.

Advance To:

isc_open_blob2()