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