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.Dd April 19, 2019 29.Dt CASU 9 30.Os 31.Sh NAME 32.Nm casueword , 33.Nm casueword32 , 34.Nm casuword , 35.Nm casuword32 36.Nd fetch, compare and store data from user-space 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/systm.h 40.Ft int 41.Fo casueword 42.Fa "volatile u_long *base" 43.Fa "u_long oldval" 44.Fa "u_long *oldvalp" 45.Fa "u_long newval" 46.Fc 47.Ft int 48.Fo casueword32 49.Fa "volatile uint32_t *base" 50.Fa "uint32_t oldval" 51.Fa "uint32_t *oldvalp" 52.Fa "uint32_t newval" 53.Fc 54.Ft u_long 55.Fo casuword 56.Fa "volatile u_long *base" 57.Fa "u_long oldval" 58.Fa "u_long newval" 59.Fc 60.Ft uint32_t 61.Fo casuword32 62.Fa "volatile uint32_t *base" 63.Fa "uint32_t oldval" 64.Fa "uint32_t newval" 65.Fc 66.Sh DESCRIPTION 67The 68.Nm 69functions are designed to perform atomic compare-and-swap operation on 70the value in the usermode memory of the current process. 71.Pp 72The 73.Nm 74routines reads the value from user memory with address 75.Pa base , 76and compare the value read with 77.Pa oldval . 78If the values are equal, 79.Pa newval 80is written to the 81.Pa *base . 82In case of 83.Fn casueword32 84and 85.Fn casueword , 86old value is stored into the (kernel-mode) variable pointed by 87.Pa *oldvalp . 88The userspace value must be naturally aligned. 89.Pp 90The callers of 91.Fn casuword 92and 93.Fn casuword32 94functions cannot distinguish between -1 read from 95userspace and function failure. 96.Sh RETURN VALUES 97The 98.Fn casuword 99and 100.Fn casuword32 101functions return the data fetched or -1 on failure. 102The 103.Fn casueword 104and 105.Fn casueword32 106functions return 0 on success, -1 on failure to access memory, 107and 1 when comparison or store failed. 108The store can fail on load-linked/store-conditional architectures. 109.Sh SEE ALSO 110.Xr atomic 9 , 111.Xr fetch 9 , 112.Xr store 9 113