xref: /haiku/docs/user/posix/unistd.dox (revision 344ded80d400028c8f561b4b876257b94c12db4a)
1/*
2 * Copyright 2023 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Adrien Destugues, pulkomandy@pulkomandy.tk
7 *
8 * Corresponds to:
9 *		headers/posix/unistd.h	hrev56953
10 */
11
12/*!
13	\file unistd.h
14	\ingroup libroot
15	\brief Standard symbolic constants and types
16*/
17
18/*!
19	\fn int ioctl(int fd, unsigned long op, void* argument, size_t size)
20	\brief Send a control command to a device through a file descriptor
21
22	ioctls are usually sent to file descriptors corresponding to files in the devfs filesystem
23	(mounted in /dev). It allows sending commands to devices that wouldn't fit the usual flow of
24	the read and write operations.
25
26	The action to perform is identified by the "op" parameter. Each driver can implement its own
27	custom operations as needed, depending on the device being controlled. There are also a few
28	standard ones implemented by most drivers.
29
30	In the standard UNIX version of this function, there is support for only one extra argument,
31	which can be either an integer, or a pointer, either pointing to some data to send to the
32	driver, or some buffer to receive a response. In most UNIX systems, further details about the
33	operation are encoded in the "op" parameter, with bits indicating the direction and size of
34	the buffer.
35
36	In BeOS and Haiku, the allocation of "op" values is done freely in each driver, and no bits are
37	reserved for such use. Instead, a 4th argument is allowed, and can be used to indicate the
38	buffer size. There is no need to encode the transfer direction, as this can be agreed between
39	the calling application and the driver.
40
41	Both the 3rd and 4th parameters are optional. In C++, this is done using C++ function default
42	arguments and causes no problems. However, the C language has no such feature. Therefore, the
43	C implementation is a macro implementing a similar behavior.
44
45	To avoid these divergences between implementations of ioctl, portable applications should
46	consider using the newly standardized posix_devctl function from POSIX 1.2024, which is
47	equivalent to the BeOS/Haiku implementation of ioctl and also has an explicit size parameter.
48*/
49