1.\" Copyright (c) 2014, 2019 The FreeBSD Foundation 2.\" 3.\" Part of this documentation was written by 4.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 5.\" from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd April 19, 2019 31.Dt CASU 9 32.Os 33.Sh NAME 34.Nm casueword , 35.Nm casueword32 , 36.Nm casuword , 37.Nm casuword32 38.Nd fetch, compare and store data from user-space 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/systm.h 42.Ft int 43.Fo casueword 44.Fa "volatile u_long *base" 45.Fa "u_long oldval" 46.Fa "u_long *oldvalp" 47.Fa "u_long newval" 48.Fc 49.Ft int 50.Fo casueword32 51.Fa "volatile uint32_t *base" 52.Fa "uint32_t oldval" 53.Fa "uint32_t *oldvalp" 54.Fa "uint32_t newval" 55.Fc 56.Ft u_long 57.Fo casuword 58.Fa "volatile u_long *base" 59.Fa "u_long oldval" 60.Fa "u_long newval" 61.Fc 62.Ft uint32_t 63.Fo casuword32 64.Fa "volatile uint32_t *base" 65.Fa "uint32_t oldval" 66.Fa "uint32_t newval" 67.Fc 68.Sh DESCRIPTION 69The 70.Nm 71functions are designed to perform atomic compare-and-swap operation on 72the value in the usermode memory of the current process. 73.Pp 74The 75.Nm 76routines reads the value from user memory with address 77.Pa base , 78and compare the value read with 79.Pa oldval . 80If the values are equal, 81.Pa newval 82is written to the 83.Pa *base . 84In case of 85.Fn casueword32 86and 87.Fn casueword , 88old value is stored into the (kernel-mode) variable pointed by 89.Pa *oldvalp . 90The userspace value must be naturally aligned. 91.Pp 92The callers of 93.Fn casuword 94and 95.Fn casuword32 96functions cannot distinguish between -1 read from 97userspace and function failure. 98.Sh RETURN VALUES 99The 100.Fn casuword 101and 102.Fn casuword32 103functions return the data fetched or -1 on failure. 104The 105.Fn casueword 106and 107.Fn casueword32 108functions return 0 on success, -1 on failure to access memory, 109and 1 when comparison or store failed. 110The store can fail on load-linked/store-conditional architectures. 111.Sh SEE ALSO 112.Xr atomic 9 , 113.Xr fetch 9 , 114.Xr store 9 115