1.\" $NetBSD: fetch.9,v 1.2 1996/01/09 21:59:24 perry Exp $ 2.\" 3.\" Copyright (c) 1996 Jason R. Thorpe. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed by Kenneth Stailey. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed for the NetBSD Project 19.\" by Jason R. Thorpe. 20.\" 4. The name of the author may not be used to endorse or promote products 21.\" derived from this software without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 24.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 25.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 26.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 27.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 28.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 30.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 31.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.Dd July 22, 2021 36.Dt FETCH 9 37.Os 38.Sh NAME 39.Nm fetch , 40.Nm fubyte , 41.Nm fuword , 42.Nm fuword16 , 43.Nm fuword32 , 44.Nm fuword64 , 45.Nm fueword , 46.Nm fueword32 , 47.Nm fueword64 48.Nd fetch data from user-space 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/systm.h 52.Ft int 53.Fn fubyte "volatile const void *base" 54.Ft long 55.Fn fuword "volatile const void *base" 56.Ft int 57.Fn fuword16 "volatile const void *base" 58.Ft int32_t 59.Fn fuword32 "volatile const void *base" 60.Ft int64_t 61.Fn fuword64 "volatile const void *base" 62.Ft int 63.Fn fueword "volatile const void *base" "long *val" 64.Ft int 65.Fn fueword32 "volatile const void *base" "int32_t *val" 66.Ft int 67.Fn fueword64 "volatile const void *base" "int64_t *val" 68.Sh DESCRIPTION 69The 70.Nm 71functions are designed to copy small amounts of data from user-space 72of the current process. 73If the user address is naturally aligned, then the operation will be 74performed atomically. 75Otherwise it may fail or be performed non-atomically, depending on 76the platform. 77.Pp 78The 79.Nm 80routines provide the following functionality: 81.Bl -tag -width "fueword32()" 82.It Fn fubyte 83Fetches a byte of data from the user-space address 84.Pa base . 85The byte read is zero-extended into the results variable. 86.It Fn fuword 87Fetches a word of data (long) from the user-space address 88.Pa base . 89.It Fn fuword16 90Fetches 16 bits of data from the user-space address 91.Pa base . 92The half-word read is zero-extended into the results variable. 93.It Fn fuword32 94Fetches 32 bits of data from the user-space address 95.Pa base . 96.It Fn fuword64 97Fetches 64 bits of data from the user-space address 98.Pa base . 99.It Fn fueword 100Fetches a word of data (long) from the user-space address 101.Pa base 102and stores the result in the variable pointed by 103.Pa val . 104.It Fn fueword32 105Fetches 32 bits of data from the user-space address 106.Pa base 107and stores the result in the variable pointed by 108.Pa val . 109.It Fn fueword64 110Fetches 64 bits of data from the user-space address 111.Pa base 112and stores the result in the variable pointed by 113.Pa val . 114.El 115.Pp 116The callers of 117.Fn fuword , 118.Fn fuword32 119and 120.Fn fuword64 121functions cannot distinguish between -1 read from 122userspace and function failure. 123.Sh RETURN VALUES 124The 125.Fn fubyte , 126.Fn fuword , 127.Fn fuword16 , 128.Fn fuword32 , 129and 130.Fn fuword64 131functions return the data fetched or -1 on failure. 132The 133.Fn fueword , 134.Fn fueword32 135and 136.Fn fueword64 137functions return 0 on success and -1 on failure. 138.Sh SEE ALSO 139.Xr copy 9 , 140.Xr store 9 141