	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

Operation Functions

This section lists the functions that manage locking objects.

Functions
int	R_LOCK_new (R_LOCK_CTX lock_ctx, R_LOCK *lock)
	Creates a new R_LOCK object lock. More...
int	R_LOCK_free (R_LOCK *lock)
	Frees the R_LOCK object lock. More...
int	R_LOCK_get_new_lock_id (R_LOCK lock, char name, int *lock_id)
	Returns a new identifier for the R_LOCK object lock. More...
int	R_LOCK_get_lock_name (R_LOCK lock, int lock_id, char *pname)
	Returns the lock name for the R_LOCK object lock. More...
int	R_LOCK_add (R_LOCK lock, int value, int amount, int lock_id)
	Updates the value of an integer under the protection of the R_LOCK object lock. More...
int	R_LOCK_r_lock (R_LOCK *lock, int lock_id)
	Retrieves a read lock for the R_LOCK object lock. More...
int	R_LOCK_w_lock (R_LOCK *lock, int lock_id)
	Retrieves a write lock for the R_LOCK object lock. More...
int	R_LOCK_r_unlock (R_LOCK *lock, int lock_id)
	Clears the read lock for the R_LOCK object lock. More...
int	R_LOCK_w_unlock (R_LOCK *lock, int lock_id)
	Clears the write lock for the R_LOCK object lock. More...
int R_CDECL	R_lockid_new (char *name)
	Returns a new lock identifier (that is, lock table index number) name for a new lock. More...
void R_CDECL	R_lockids_free (void)
	Frees all current locks and should be called if new locks have been created and are not required. More...
int R_CDECL	R_lock_num (void)
	Returns the number of locks required by the library. More...
char* R_CDECL	R_lock_get_name (int lockid)
	Returns the textual description for the lock identifier lockid. More...
R_LOCK_CB_T* R_CDECL	R_lock_get_cb (void)
	Returns the callback that is called by R_lock_ctrl(). More...
R_LOCKED_ADD_CB_T* R_CDECL	R_locked_add_get_cb (void)
	Returns the callback called via R_lock(). More...
int R_CDECL	R_lock_set_cb (R_LOCK_CB_T *func)
	Sets the locking callback that enables and disables locks. More...
int R_CDECL	R_locked_add_set_cb (R_LOCKED_ADD_CB_T *func)
	Sets the callback called via R_lock(). More...
int R_CDECL	R_lock_ctrl (int mode, int lockid, char *file, int line)
	Sets or clears a specified lock. More...
int R_CDECL	R_locked_add (int pointer, int amount, int lockid, char file, int line)
	Performs a locked add operation for the lock. More...
R_THREAD_ID_CB_T* R_CDECL	R_thread_id_get_cb (void)
	Returns the callback called via R_thread_id(). More...
int R_CDECL	R_thread_id_set_cb (R_THREAD_ID_CB_T *func)
	Sets the callback that returns a unique identifier for each thread. More...
unsigned long R_CDECL	R_thread_id (void)
	Returns the unique identifier for the current thread in which the function is called. More...
int	R_lock_w (int lockid)
	Retrieves a write lock for the lock lockid. More...
int	R_lock_r (int type)
	Retrieves a read lock for the lock type. More...
int	R_lock (int mode, int lockid, char *file, int line)
	Sets a specified lock. More...

Function Documentation

int R_lock ( int mode,

int lockid,

char * file,

int line

) ;

Sets a specified lock.
Parameters:

mode [In] The lock mode. One of:

R_LOCK_READ.
R_LOCK_WRITE.

lockid [In] The lock identifier.

file [In] The source code file (may be NULL).

line [In] The line number in the file (may be 0).

Returns:
>0 indicates success.
<=0 indicates error.

file and line are optional fields indicating the source code file and line number where the lock/unlock occurs. This is useful when debugging.
Applications should call R_lock_r(), R_unlock_r(), R_lock_w() or R_unlock_w() in preference to directly accessing this function.
See also:
R_lock_r(), R_unlock_r(), R_lock_w() and R_unlock_w().

int R_LOCK_add ( R_LOCK * lock,

int * value,

int amount,

int lock_id

) ;

Updates the value of an integer under the protection of the R_LOCK object lock. It is an atomic adjustment that is performed on an all or nothing basis.
Parameters:

lock [In] The R_LOCK reference.

value [Out] The value to add.

amount [In] The amount to add.

lock_id [In] The lock identifier.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.

int R_CDECL R_lock_ctrl ( int mode,

int lockid,

char * file,

int line

) ;

Sets or clears a specified lock.
Parameters:

mode [In] The lock mode.
See Flags for valid values.

lockid [In] The lock identifier.

file [In] The source code file (may be NULL).

line [In] The line number in the file (may be 0).

Returns:
>0 indicates success.
<=0 indicates error.

file and line are optional parameters indicating the source code file and line number where the lock/unlock occurs. This is useful when debugging.
Applications should call R_lock_r(), R_unlock_r(), R_lock_w() or R_unlock_w() in preference to directly accessing this function.
See also:
R_lock_r(), R_unlock_r(), R_lock_w() and R_unlock_w().

int R_LOCK_free ( R_LOCK * lock ) ;

Frees the R_LOCK object lock.
Parameters:

lock [In, Out] The R_LOCK reference.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.
See also:
R_LOCK_new().

R_LOCK_CB_T* R_CDECL R_lock_get_cb ( void ) ;

Returns the callback that is called by R_lock_ctrl().
Returns:
The locking callback function R_LOCK_CB_T.
See also:
R_lock_set_cb() and R_lock_w().

int R_LOCK_get_lock_name ( R_LOCK * lock,

int lock_id,

char ** pname

) ;

Returns the lock name for the R_LOCK object lock.
Parameters:

lock [In] The R_LOCK reference.

lock_id [In] The lock identifier.

pname [Out] A reference to the lock name. Do not allocate memory for this field and do not free the pointer that is returned.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.

char* R_CDECL R_lock_get_name ( int lockid ) ;

Returns the textual description for the lock identifier lockid.
Parameters:

lockid [In] The lock identifier.

Returns:
The lock identifier name.
NULL indicates no name is set.
Otherwise indicates error.

int R_LOCK_get_new_lock_id ( R_LOCK * lock,

char * name,

int * lock_id

) ;

Returns a new identifier for the R_LOCK object lock. The identifier can then be used in locking operations.
Parameters:

lock [In] The R_LOCK reference.

name [In] The lock name.

lock_id [Out] The lock identifier.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.

int R_LOCK_new ( R_LOCK_CTX * lock_ctx,

R_LOCK ** lock

) ;

Creates a new R_LOCK object lock.
Parameters:

lock_ctx [In] The R_LOCK_CTX reference.

lock [Out] The R_LOCK reference.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.

Locking objects are used to interact (that is, perform operations) on the locking module.
See also:
R_LOCK_free().

int R_CDECL R_lock_num ( void ) ;

Returns the number of locks required by the library. It is a total of the system-defined locks and any application locks defined via R_lockid_new().

Returns:
The current number of locks.

int R_lock_r ( int type ) ;

Retrieves a read lock for the lock type.
Parameters:

type [In] The lock identifier.

Returns:
>0 indicates success.
<=0 indicates error.

The caller is blocked until the lock becomes available.
This macro calls R_lock_ctrl() with __FILE__ and __LINE__ as the file and line parameters. This identifies the source code file and line number where the lock/unlock occurs. This is useful when debugging.
See also:
R_unlock_r(), R_lock_w() and R_unlock_w().
Samples:
app_cache.c, and thread.c.

int R_LOCK_r_lock ( R_LOCK * lock,

int lock_id

) ;

Retrieves a read lock for the R_LOCK object lock.
Parameters:

lock [In] The R_LOCK reference.

lock_id [In] The lock identifier.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.

The caller is blocked until the lock becomes available.
See also:
R_LOCK_r_unlock(), R_LOCK_w_lock() and R_LOCK_w_unlock().

int R_LOCK_r_unlock ( R_LOCK * lock,

int lock_id

) ;

Clears the read lock for the R_LOCK object lock.
Parameters:

lock [In] The R_LOCK reference.

lock_id [In] The lock identifier.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.
See also:
R_LOCK_r_lock(), R_LOCK_w_lock() and R_LOCK_w_unlock().

int R_CDECL R_lock_set_cb ( R_LOCK_CB_T * func ) ;

Sets the locking callback that enables and disables locks. This callback must be provided for multithreading.
Parameters:

func [In] The locking callback function R_LOCK_CB_T.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
R_lock_get_cb() and R_lock_w().

int R_lock_w ( int lockid ) ;

Retrieves a write lock for the lock lockid.
Parameters:

lockid [In] The lock identifier.

Returns:
>0 indicates success.
<=0 indicates error.

The caller is blocked until the lock becomes available.
This macro calls R_lock_ctrl() with __FILE__ and __LINE__ as the file and line parameters. This identifies the source code file and line number where the lock/unlock occurs. This is useful when debugging.
See also:
R_lock_r(), R_unlock_r() and R_unlock_w().
Samples:
app_cache.c, and thread.c.

int R_LOCK_w_lock ( R_LOCK * lock,

int lock_id

) ;

Retrieves a write lock for the R_LOCK object lock.
Parameters:

lock [In] The R_LOCK reference.

lock_id [In] The lock identifier.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.

The caller is blocked until the lock becomes available.
See also:
R_LOCK_r_lock(), R_LOCK_r_unlock() and R_LOCK_w_unlock().

int R_LOCK_w_unlock ( R_LOCK * lock,

int lock_id

) ;

Clears the write lock for the R_LOCK object lock.
Parameters:

lock [In] The R_LOCK reference.

lock_id [In] The lock identifier.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for error values.
See also:
R_LOCK_r_lock(), R_LOCK_r_unlock() and R_LOCK_w_lock().

int R_CDECL R_locked_add ( int * pointer,

int amount,

int lockid,

char * file,

int line

) ;

Performs a locked add operation for the lock.
Parameters:

pointer [Out] A pointer.

amount [In] The amount.

lockid [In] The lock identifier.

file [In] The file name (optional).

line [In] The line in file (optional).

Returns:
>0 indicates success.
<=0 indicates error.

R_LOCKED_ADD_CB_T* R_CDECL R_locked_add_get_cb ( void ) ;

Returns the callback called via R_lock(). The callback is used to increment/decrement an integer for maintaining reference counts against the major data structures.

Returns:
The callback function R_LOCKED_ADD_CB_T.
See also:
R_locked_add_set_cb().

int R_CDECL R_locked_add_set_cb ( R_LOCKED_ADD_CB_T * func ) ;

Sets the callback called via R_lock(). Increments/decrements an integer for maintaining reference counts against the major data structures.
Parameters:

func [In] The callback function R_LOCKED_ADD_CB_T.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
R_locked_add_get_cb().

int R_CDECL R_lockid_new ( char * name ) ;

Returns a new lock identifier (that is, lock table index number) name for a new lock. The application uses the identifier when registering a new lock and assigns a name to the number. The lock identifier is used when locking or unlocking data.
Parameters:

name [In] The lock name.

Returns:
>0 indicates success.
<=0 indicates error.

void R_CDECL R_lockids_free ( void ) ;

Frees all current locks and should be called if new locks have been created and are not required.

By default this function is called by the library if a default resource list is used.

unsigned long R_CDECL R_thread_id ( void ) ;

Returns the unique identifier for the current thread in which the function is called.
Returns:
The thread identifier.
See also:
R_thread_id_set_cb().

R_THREAD_ID_CB_T* R_CDECL R_thread_id_get_cb ( void ) ;

Returns the callback called via R_thread_id().
Returns:
The unique identifier callback function.
See also:
R_thread_id() and R_thread_id_set_cb().

int R_CDECL R_thread_id_set_cb ( R_THREAD_ID_CB_T * func ) ;

Sets the callback that returns a unique identifier for each thread.
Parameters:

func [In] The thread_id callback function.

Returns:
1 indicates success.
See also:
R_thread_id() and R_thread_id_get_cb().