lockl Kernel Service

Purpose

Locks a conventional process lock.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/lockl.h>

int lockl ( lock_word, flags) lock_t *lock_word; int flags;

Parameters

Item	Description
lock _word	Specifies the address of the lock word.
flags	Specifies the flags that control waiting for a lock. The flags parameter is used to control how signals affect waiting for a lock. The four flags are: LOCK_NDELAY Controls whether the caller waits for the lock. Setting the flag causes the request to be terminated. The lock is assigned to the caller. Not setting the flag causes the caller to wait until the lock is not owned by another process before the lock is assigned to the caller. LOCK_SHORT Prevents signals from terminating the wait for the lock. LOCK_SHORT is the default flag for the lockl Kernel Service. This flag causes non-preemptive sleep. LOCK_SIGRET Causes the wait for the lock to be terminated by an unmasked signal. LOCK_SIGWAKE Causes the wait for the lock to be terminated by an unmasked signal and control transferred to the return from the last operation by the setjmpx kernel service. Note: The LOCK_SIGRET flag overrides the LOCK_SIGWAKE flag.

Item

Description

lock _word

Specifies the address of the lock word.

flags

Specifies the flags that control waiting for a lock. The flags parameter is used to control how signals affect waiting for a lock. The four flags are:

LOCK_NDELAY: Controls whether the caller waits for the lock. Setting the flag causes the request to be terminated. The lock is assigned to the caller. Not setting the flag causes the caller to wait until the lock is not owned by another process before the lock is assigned to the caller.
LOCK_SHORT: Prevents signals from terminating the wait for the lock. LOCK_SHORT is the default flag for the lockl Kernel Service. This flag causes non-preemptive sleep.
LOCK_SIGRET: Causes the wait for the lock to be terminated by an unmasked signal.
LOCK_SIGWAKE: Causes the wait for the lock to be terminated by an unmasked signal and control transferred to the return from the last operation by the setjmpx kernel service.

Note: The LOCK_SIGRET flag overrides the LOCK_SIGWAKE flag.

Description

Note: The lockl kernel service is provided for compatibility only and should not be used in new code, which should instead use simple locks or complex locks.

The lockl kernel service locks a conventional lock

The lock word can be located in shared memory. It must be in the process's address space when the lockl or unlockl services are called. The kernel accesses the lock word only while executing under the caller's process.

The lock_word parameter is typically part of the data structure that describes the resource managed by the lock. This parameter must be initialized to the LOCK_AVAIL value before the first call to the lockl service. Only the lockl and unlockl services can alter this parameter while the lock is in use.

The lockl service is nestable. The caller should use the LOCK_SUCC value for determining when to call the unlockl service to unlock the conventional lock.

The lockl service temporarily assigns the owner the process priority of the most favored waiter for the lock.

A process must release all locks before terminating or leaving kernel mode. Signals are not delivered to kernel processes while those processes own any lock. "Understanding System Call Execution" in AIX® Version 7.1 Kernel Extensions and Device Support Programming Concepts discusses how system calls can use the lockl service when accessing global data.

Execution Environment

The lockl kernel service can be called from the process environment only.

Return Values

Item	Description
LOCK_SUCC	Indicates that the process does not already own the lock or the lock is not owned by another process when the flags parameter is set to LOCK_NDELAY.
LOCK_NEST	Indicates that the process already owns the lock or the lock is not owned by another process when the flags parameter is set to LOCK_NDELAY.
LOCK_FAIL	Indicates that the lock is owned by another process when the flags parameter is set to LOCK_NDELAY.
LOCK_SIG	Indicates that the wait is terminated by a signal when the flags parameter is set to LOCK_SIGRET.