[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

cs Subroutine

Purpose

Compares and swaps data.

Library

Standard C Library (libc.a)

Syntax

int cs (Destination, Compare, Value)
int *Destination;
int Compare;
int Value;

Description

Note: The cs subroutine is only provided to support binary compatibility with AIX Version 3 applications. When writing new applications, it is not recommended to use this subroutine; it may cause reduced performance in the future. Applications should use the compare_and_swap subroutine, unless they need to use unaligned memory locations.

The cs subroutine compares the Compare value with the integer pointed to by Destination address. If they are equal, Value is stored in the integer pointed to by the Destination address and cs returns 0. If the values are different, the cs subroutine returns 1, and the value pointed to by Destination address is not affected. The compare and store operations are executed atomically. Therefore, no process switches occur between them.

The cs subroutine can be used to implement interprocess communication facilities or to manipulate data structures shared among several processes, such as linked lists stored in shared memory.

The following example shows how a new element can be inserted in a null-terminated list that is stored in shared memory and maintained by several processes:

struct elem {
       struct elem  *next;
        ...
};
struct elem   *list, *new_elem;
do
       new_elem->next = list;
while (cs((int *)&list, (int)(new_elem->next),
           (int)new_elem));

Parameters

Destination Specifies the address of the integer to be compared with the Compare value, and if need be, where Value will be stored.
Compare Specifies the value to be compared with the integer pointed by Destination parameter address.
Value Specifies the value stored in the integer pointed to by the Destination address if the Destination and Compare values are equal.

Return Codes

The cs subroutine returns a value of 0 if the two values compared are equal. If the values are not equal, the cs subroutine returns a value of 1.

Error Codes

If the integer pointed by the Destination parameter references memory that does not belong to the process address space, the SIGSEGV signal is sent to the process.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The shmat subroutine, shmctl subroutine, shmdt subroutine, shmget subroutine, sigaction, signal, or sigvec.

Program Address Space Overview in AIX General Programming Concepts: Writing and Debugging Programs.

Subroutines Overview in AIX General Programming Concepts: Writing and Debugging Programs.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]