1cd62a92dSRobert Mustacchi# 2cd62a92dSRobert Mustacchi# This file and its contents are supplied under the terms of the 3cd62a92dSRobert Mustacchi# Common Development and Distribution License ("CDDL"), version 1.0. 4cd62a92dSRobert Mustacchi# You may only use this file in accordance with the terms of version 5cd62a92dSRobert Mustacchi# 1.0 of the CDDL. 6cd62a92dSRobert Mustacchi# 7cd62a92dSRobert Mustacchi# A full copy of the text of the CDDL should have accompanied this 8cd62a92dSRobert Mustacchi# source. A copy of the CDDL is also available via the Internet at 9cd62a92dSRobert Mustacchi# http://www.illumos.org/license/CDDL. 10cd62a92dSRobert Mustacchi# 11cd62a92dSRobert Mustacchi 12cd62a92dSRobert Mustacchi# 13cd62a92dSRobert Mustacchi# Copyright 2020 Robert Mustacchi 14cd62a92dSRobert Mustacchi# 15cd62a92dSRobert Mustacchi _ _ _ 16cd62a92dSRobert Mustacchi ___| |_ __| (_) ___ 17cd62a92dSRobert Mustacchi/ __| __/ _` | |/ _ \ 18cd62a92dSRobert Mustacchi\__ \ || (_| | | (_) | 19cd62a92dSRobert Mustacchi|___/\__\__,_|_|\___/ 20cd62a92dSRobert Mustacchi 21cd62a92dSRobert MustacchiNotes on the design of stdio. 22cd62a92dSRobert Mustacchi 23cd62a92dSRobert Mustacchi------------ 24cd62a92dSRobert MustacchiFile Streams 25cd62a92dSRobert Mustacchi------------ 26cd62a92dSRobert Mustacchi 27cd62a92dSRobert MustacchiAt the heart of the stdio is the 'FILE *'. The 'FILE *' represents a 28cd62a92dSRobert Mustacchistream that can be read, written, and seeked. The streams traditionally 29cd62a92dSRobert Mustacchirefer to a file descriptor, when created by fopen(3C), or may refer to 30cd62a92dSRobert Mustacchimemory, when created by open_memstream(3C) or fmopen(3C). This document 31cd62a92dSRobert Mustacchifocuses on the implementation of streams. Other misc. functions in stdio 32cd62a92dSRobert Mustacchiare not discussed. 33cd62a92dSRobert Mustacchi 34cd62a92dSRobert Mustacchi------------ 35cd62a92dSRobert MustacchiOrganization 36cd62a92dSRobert Mustacchi------------ 37cd62a92dSRobert Mustacchi 38cd62a92dSRobert MustacchiMost functions exist in a file with the same name. When adding new 39cd62a92dSRobert Mustacchifiles to stdio the file name should match the primary function name. 40cd62a92dSRobert MustacchiThere are a few exceptions. Almost all of the logic related to both 41cd62a92dSRobert Mustacchiflushing and knowledge of how to handle the 32-bit ABI issues (described 42cd62a92dSRobert Mustacchiin the next section) can be found in flush.c. 43cd62a92dSRobert Mustacchi 44cd62a92dSRobert Mustacchi----------------------------- 45cd62a92dSRobert Mustacchistruct __FILE_TAG and the ABI 46cd62a92dSRobert Mustacchi----------------------------- 47cd62a92dSRobert Mustacchi 48cd62a92dSRobert MustacchiThe definition of the 'FILE *' is a pointer to a 'struct __FILE_TAG'. 49cd62a92dSRobert MustacchiThe 'struct __FILE_TAG' structure has a long history that dates back to 50cd62a92dSRobert Mustacchihistorical UNIX. For better or for worse, we have inherited some of the 51cd62a92dSRobert Mustacchidesign decisions of the past, it's important to understand what those 52cd62a92dSRobert Mustacchiare as they have profound impact on the stdio design and serve as a good 53cd62a92dSRobert Mustacchicautionary tale for future ABI decisions. 54cd62a92dSRobert Mustacchi 55cd62a92dSRobert MustacchiIn the original UNIX designs, the 'struct __FILE_TAG' was exposed as a 56cd62a92dSRobert Mustacchinon-opaque structure. This was also true on other platforms. This had a 57cd62a92dSRobert Mustacchicouple of challenges: 58cd62a92dSRobert Mustacchi 59cd62a92dSRobert Mustacchi* It meant the size of the 'struct __FILE_TAG' was part of the ABI 60cd62a92dSRobert Mustacchi* Consumers would access the members directly. You can find examples of 61cd62a92dSRobert Mustacchi this in our public headers where things like getc() are inlined in 62cd62a92dSRobert Mustacchi terms of the implementation. Various 3rd-party software that has 63cd62a92dSRobert Mustacchi existed for quite some time knows the offset of members and directly 64cd62a92dSRobert Mustacchi manipulates them. This is still true as of 2020. 65cd62a92dSRobert Mustacchi* The 'struct __FILE_TAG' only used an unsigned char (uint8_t) for the 66cd62a92dSRobert Mustacchi file descriptor in the 32-bit version. Other systems used a short, so 67cd62a92dSRobert Mustacchi they were in better shape. This was changed in the 64-bit version to 68cd62a92dSRobert Mustacchi use an int. 69cd62a92dSRobert Mustacchi* The main C stdio symbols 'stdin', 'stdout', and 'stderr', were (and 70cd62a92dSRobert Mustacchi still are) exposed as an array. This means that while the 64-bit 71cd62a92dSRobert Mustacchi structure is opaque, its size is actually part of the ABI. 72cd62a92dSRobert Mustacchi 73cd62a92dSRobert MustacchiAll of these issues have been dealt with in different ways in the 74cd62a92dSRobert Mustacchisystem. The first thing that is a little confusing is where to find the 75cd62a92dSRobert Mustacchidefinitions of the actual implementation. The 32-bit 'struct __FILE_BUF' 76cd62a92dSRobert Mustacchiis split into two different pieces, the part that is public and a 77cd62a92dSRobert Mustacchisecondary, private part. 78cd62a92dSRobert Mustacchi 79cd62a92dSRobert MustacchiThe public definition of the 'struct __FILE_TAG' for 32-bit code and the 80cd62a92dSRobert Mustacchiopaque definition for 64-bit code may be found in 81cd62a92dSRobert Mustacchi'usr/src/head/stdio_impl.h.'. The actual definition of the 64-bit 82cd62a92dSRobert Mustacchistructure and the 32-bit additions are all found in 83cd62a92dSRobert Mustacchi'usr/src/lib/libc/inc/file64.h.' 84cd62a92dSRobert Mustacchi 85cd62a92dSRobert MustacchiIn file64.h, one will find the 'struct xFILEdata' (extended FILE * data). 86cd62a92dSRobert MustacchiThis represents all of the data that has been added to stdio that is 87cd62a92dSRobert Mustacchimissing from the public structure. Whenever a 'FILE *' is allocated, 88cd62a92dSRobert Mustacchi32-bit code always ensures that there is a corresponding 'struct 89cd62a92dSRobert MustacchixFILEdata' that exists. Currently, we still have plenty of padding left 90cd62a92dSRobert Mustacchiin the 64-bit version of the structure for at least 3 pointers. 91cd62a92dSRobert Mustacchi 92cd62a92dSRobert MustacchiTo add a member to the structure, one has to add data to the structures 93cd62a92dSRobert Mustacchiin 'lib/libc/inc/file64.h'. If for some reason, all the padding would be 94cd62a92dSRobert Mustacchiused up, then you must stop. The size of the 64-bit structure _cannot_ 95cd62a92dSRobert Mustacchibe extended, as noted earlier it is part of the ABI. If we hit this 96cd62a92dSRobert Mustacchicase, then one must introduce the struct xFILEdata for the lp64 97cd62a92dSRobert Mustacchienvironment. 98cd62a92dSRobert Mustacchi 99cd62a92dSRobert Mustacchi-------------------------- 100cd62a92dSRobert MustacchiAllocating FILE Structures 101cd62a92dSRobert Mustacchi-------------------------- 102cd62a92dSRobert Mustacchi 103cd62a92dSRobert Mustacchilibc defines a number of 'FILE *' structures by default. These can all 104cd62a92dSRobert Mustacchibe found in 'data.c'. The first _NFILE (20 or 60 depending on the 105cd62a92dSRobert Mustacchiplatform) are defined statically. In the 32-bit case, the corresponding 106cd62a92dSRobert Mustacchi'struct _xFILEdata' is allocated along with it. 107cd62a92dSRobert Mustacchi 108cd62a92dSRobert MustacchiTo determine if a structure is free or not in the array, the `_flag` 109cd62a92dSRobert Mustacchimember is consulted. If the flag has been set to zero, then the STREAM 110cd62a92dSRobert Mustacchiis considered free and can be allocated. All of the allocated (whether 111cd62a92dSRobert Mustacchiused or not) 'FILE *' structures are present on a linked list which is 112cd62a92dSRobert Mustacchifound in 'flush.c' rooted at the symbol '__first_link'. This list is 113cd62a92dSRobert Mustacchialways scanned to try and reuse an existing 'FILE *' structure before 114cd62a92dSRobert Mustacchiallocating a new one. If all of the existing ones are in use, then one 115cd62a92dSRobert Mustacchiwill be allocated. 116cd62a92dSRobert Mustacchi 117cd62a92dSRobert MustacchiAn important thing to understand is that once allocated, a 'FILE *' will 118cd62a92dSRobert Mustacchinever be freed by libc. It will always exist on the global list of 119cd62a92dSRobert Mustacchistructures to be reused. 120cd62a92dSRobert Mustacchi 121cd62a92dSRobert Mustacchi--------- 122cd62a92dSRobert MustacchiBuffering 123cd62a92dSRobert Mustacchi--------- 124cd62a92dSRobert Mustacchi 125cd62a92dSRobert MustacchiEvery stream in stdio starts out as buffered. Buffering can be changed 126cd62a92dSRobert Mustacchiby calling either setbuf(3C) or setvbuf(3C). This buffer is stored in 127cd62a92dSRobert Mustacchithe `_base` member of the 'struct __FILE_TAG'. The amount of valid data 128cd62a92dSRobert Mustacchiin the buffer is maintained in the '_cnt' member of the structure. By 129cd62a92dSRobert Mustacchidefault, there is no associated buffer with a stream. When the stream is 130cd62a92dSRobert Mustacchifirst used, the buffer will be assigned by a call to _findbuf() in 131cd62a92dSRobert Mustacchi_findbuf.c. 132cd62a92dSRobert Mustacchi 133cd62a92dSRobert MustacchiThere are pre-allocated buffers that exist. There are two specifically 134cd62a92dSRobert Mustacchifor stdin and stdout (stderr is unbuffered). These include space for 135cd62a92dSRobert Mustacchiboth the buffer and the pushback buffer. The pushback buffer is used so 136cd62a92dSRobert Mustacchisomeone can call fungetc(3C) regardless of whether a buffering mode is 137cd62a92dSRobert Mustacchienabled or not. Characters that we 'unget' are placed on the pushback 138cd62a92dSRobert Mustacchibuffer. 139cd62a92dSRobert Mustacchi 140cd62a92dSRobert MustacchiFor other buffering modes, we'll try and allocate an appropriate sized 141cd62a92dSRobert Mustacchibuffer. The buffer size defaults to BUFSIZ, but if the stream is backed 142cd62a92dSRobert Mustacchiby a file descriptor, we'll use fstat() to determine the appropriate 143cd62a92dSRobert Mustacchisize to use and match the file system block size. If we cannot allocate 144cd62a92dSRobert Mustacchithat, we'll fall back to trying to allocate a pushback buffer. 145cd62a92dSRobert Mustacchi 146cd62a92dSRobert Mustacchilibc defines static data for _NFILE worth of pushback buffers which are 147cd62a92dSRobert Mustacchiindexed based on the underlying file descriptor. This and the stdin and 148cd62a92dSRobert Mustacchistdout buffers are all found in 'data.c' in _smbuf, _sibuf, and _sobuf 149cd62a92dSRobert Mustacchirespectively. 150cd62a92dSRobert Mustacchi 151cd62a92dSRobert Mustacchi------------------------------ 152cd62a92dSRobert MustacchiReading, Writing, and Flushing 153cd62a92dSRobert Mustacchi------------------------------ 154cd62a92dSRobert Mustacchi 155cd62a92dSRobert MustacchiBy default, reads and writes on a stream, whether backed by a 156cd62a92dSRobert Mustacchifile-descriptor or not, go through the buffer described in the previous 157cd62a92dSRobert Mustacchisection. If a read or write can be satisfied by the buffer, then no 158cd62a92dSRobert Mustacchiunderlying I/O will occur, unless buffering has been disabled. 159cd62a92dSRobert Mustacchi 160cd62a92dSRobert MustacchiThe various function entry points that read such as fread(3C) or 161cd62a92dSRobert Mustacchifgetc(3C) will not call read() directly but will instead try to fill the 162cd62a92dSRobert Mustacchibuffer, which will cause a read if required. This is centralized in 163cd62a92dSRobert Mustacchi_filbuf(). When a read is required from the underlying file, it will 164cd62a92dSRobert Mustacchicall _xread() in flush.c. For more on _xread() see the operations vector 165cd62a92dSRobert Mustacchisection further along. 166cd62a92dSRobert Mustacchi 167cd62a92dSRobert MustacchiUnlike reads, writes are much less centralized and each of the main 168cd62a92dSRobert Mustacchiwriting entry points has reimplemented the path of writing to the buffer 169cd62a92dSRobert Mustacchiand flushing it. It would be good in the future to consolidate them. In 170cd62a92dSRobert Mustacchigeneral, data will be written directly to the stdio buffer. When that 171cd62a92dSRobert Mustacchibuffer needs to be flushed either the _flsbuf() or _xflsbuf() functions 172cd62a92dSRobert Mustacchiwill be called to actually flush out the buffer. 173cd62a92dSRobert Mustacchi 174cd62a92dSRobert MustacchiWhen data needs to be flushed from a buffer to its underlying file 175cd62a92dSRobert Mustacchidescriptor (or other backing store), all of the write family functions 176cd62a92dSRobert Mustacchiultimately call _xwrite(). 177cd62a92dSRobert Mustacchi 178cd62a92dSRobert MustacchiFlushes can occur in a few different ways: 179cd62a92dSRobert Mustacchi 180cd62a92dSRobert Mustacchi1. A write has filled up the buffer. 181cd62a92dSRobert Mustacchi2. A new line ('\n') is written and new-line buffering is used. 182cd62a92dSRobert Mustacchi3. fflush(3C) or a similar function has been called. 183cd62a92dSRobert Mustacchi4. A read occurs on a buffer that has unflushed writes. 184cd62a92dSRobert Mustacchi5. The stream is being closed. 185cd62a92dSRobert Mustacchi 186cd62a92dSRobert MustacchiMost of these methods are fairly similar; however, the fflush(3C) case 187cd62a92dSRobert Mustacchiis a little different. fflush() may be asked to flush all of the streams 188cd62a92dSRobert Mustacchiwhen it is passed a NULL stream. Even when that happens it will still 189cd62a92dSRobert Mustacchiutilize the same underlying mechanism via _xflsbuf() or _flsbuf(). 190cd62a92dSRobert Mustacchi 191cd62a92dSRobert Mustacchi----------- 192cd62a92dSRobert MustacchiOrientation 193cd62a92dSRobert Mustacchi----------- 194cd62a92dSRobert Mustacchi 195cd62a92dSRobert MustacchiStreams handle both wide characters and narrow characters. There is an 196cd62a92dSRobert Mustacchiinternal multi-byte conversion state buffer that is included with every 197cd62a92dSRobert Mustacchistream. A stream may exist in one of three modes: 198cd62a92dSRobert Mustacchi 199cd62a92dSRobert Mustacchi1. It may have an explicit narrow orientation 200cd62a92dSRobert Mustacchi2. It may have an explicit wide orientation 201cd62a92dSRobert Mustacchi3. It may have no orientation 202cd62a92dSRobert Mustacchi 203cd62a92dSRobert MustacchiWhen most streams are created, they have no orientation. The orientation 204cd62a92dSRobert Mustacchican then be explicitly set by calling fwide(3C). Some streams are also 205cd62a92dSRobert Mustacchicreated with an explicit orientation, for example, open_wmemstream(3C) 206cd62a92dSRobert Mustacchialways sets the stream to be wide. 207cd62a92dSRobert Mustacchi 208cd62a92dSRobert MustacchiThe C standard dictates that certain operations will actually cause a 209cd62a92dSRobert Mustacchistream with no orientation to have an explicit orientation set. Calling 210cd62a92dSRobert Mustacchia narrow or wide related character function, such as 'fgetc(3C)' or 211cd62a92dSRobert Mustacchi'fgetwc(3C)' respectively will then cause the orientation to be set if 212cd62a92dSRobert Mustacchiit has not been. Once an orientation for a stream has been set, it 213cd62a92dSRobert Mustacchicannot be changed until the stream has been closed or it is reset by 214cd62a92dSRobert Mustacchicalling freopen(3C). 215cd62a92dSRobert Mustacchi 216cd62a92dSRobert MustacchiThere are a few functions that don't change this today. One example is 217cd62a92dSRobert Mustacchiungetc(3C). Often this isn't indicative of whether it should or 218cd62a92dSRobert Mustacchishouldn't change the orientation, but is a side effect of the history of 219cd62a92dSRobert Mustacchithe stdio implementation. 220cd62a92dSRobert Mustacchi 221cd62a92dSRobert Mustacchi------------------------------------- 222cd62a92dSRobert MustacchiOperations Vectors and Memory Streams 223cd62a92dSRobert Mustacchi------------------------------------- 224cd62a92dSRobert Mustacchi 225cd62a92dSRobert MustacchiTraditionally, stdio streams were always backed by a file descriptor of 226cd62a92dSRobert Mustacchisome kind and therefore always called out into functions like read(2), 227cd62a92dSRobert Mustacchiwrite(2), lseek(2), and close(2) directly. A series of new functions 228cd62a92dSRobert Mustacchiwere introduced in POSIX 2008 that add support for streams backed by 229cd62a92dSRobert Mustacchimemory in the form of fmemopen(3C), open_memstream(3C), and 230cd62a92dSRobert Mustacchiopen_wmemstream(3C). 231cd62a92dSRobert Mustacchi 232cd62a92dSRobert MustacchiTo deal with this and other possible designs, an operations vector was 233cd62a92dSRobert Mustacchiadded to the stream represented by the 'stdio_ops_t' structure. This is 234cd62a92dSRobert Mustacchistored in the '_ops' member of the 'struct __FILE_BUF'. For a normal 235cd62a92dSRobert Mustacchistream backed by a file descriptor, this member will be NULL. 236cd62a92dSRobert Mustacchi 237cd62a92dSRobert MustacchiIn places where a normal system call would have been made there is now a 238cd62a92dSRobert Mustacchicall to a corresponding function such as _xread(), _xwrite(), xseek(), 239cd62a92dSRobert Mustacchi_xseek64(), and _xclose(). If an operations vector is defined, it will 240cd62a92dSRobert Mustacchicall into the corresponding operation vector. If not, it will perform 241cd62a92dSRobert Mustacchithe traditional system call. This design choice consolidates all of the 242cd62a92dSRobert Mustacchiwork required to implement non-file descriptor backed streams. 243cd62a92dSRobert Mustacchi 244cd62a92dSRobert MustacchiWhen creating a non-file backed stream there are several expectations in 245cd62a92dSRobert Mustacchithe system: 246cd62a92dSRobert Mustacchi 247cd62a92dSRobert Mustacchi* The stream code should obtain a stream normally through a call to 248cd62a92dSRobert Mustacchi _findiop(). 249cd62a92dSRobert Mustacchi* If one needs to translate the normal fopen(3C) arguments, they should 250cd62a92dSRobert Mustacchi use the _stdio_flags() function. This will also construct the 251cd62a92dSRobert Mustacchi appropriate internal stdio flags for the stream. 252cd62a92dSRobert Mustacchi* The stream code must call _xassoc() to set the file operations vector 253cd62a92dSRobert Mustacchi before return a 'FILE *' out of libc. 254cd62a92dSRobert Mustacchi* All of the operations vectors must be implemented. 255cd62a92dSRobert Mustacchi* If the stream is seekable, it must explicitly use the SET_SEEKABLE() 256cd62a92dSRobert Mustacchi macro before return the stream. 257cd62a92dSRobert Mustacchi* If the stream is supposed to have a default orientation, it must set 258cd62a92dSRobert Mustacchi it by calling _setorientation(). Not all streams have a default 259cd62a92dSRobert Mustacchi orientation. 260cd62a92dSRobert Mustacchi* In the stream's close entry point it should call _xunassoc(). 261cd62a92dSRobert Mustacchi 262cd62a92dSRobert Mustacchi-------------------------- 263cd62a92dSRobert MustacchiExtended File and fileno() 264cd62a92dSRobert Mustacchi-------------------------- 265cd62a92dSRobert Mustacchi 266cd62a92dSRobert MustacchiThe 32-bit libc has historically been limited to 255 open streams 267cd62a92dSRobert Mustacchibecause of the use of an unsigned char. This problem does not impact the 268cd62a92dSRobert Mustacchi64-bit libc. To deal with this, libc uses a series of techniques which 269*bbf21555SRichard Loweare summarized for users in extendedFILE(7). The usage of extendedFILE 270cd62a92dSRobert Mustacchican also be enabled by passing the special 'F' character to fopen(3C). 271cd62a92dSRobert Mustacchi 272cd62a92dSRobert MustacchiThe '_magic' member in the 32-bit 'struct __FILE_TAG' contains what used 273cd62a92dSRobert Mustacchito be the file descriptor. When extended file is not in use, the 274cd62a92dSRobert Mustacchi_magic member still does contain the file descriptor. However, when 275cd62a92dSRobert MustacchiextendedFILE is enabled, then the _magic member contains a sentinel 276cd62a92dSRobert Mustacchivalue and the actual value is stored in the 'struct xFILEdata' _magic 277cd62a92dSRobert Mustacchimember. 278cd62a92dSRobert Mustacchi 279cd62a92dSRobert MustacchiThe act of getting the correct file descriptor has been centralized in a 280cd62a92dSRobert Mustacchifunction called _get_fd(). This function knows how to handle the special 281cd62a92dSRobert Mustacchi32-bit case and the normal case. It also centralizes the logic of 282cd62a92dSRobert Mustacchichecking for a non-file backed stream. There are many cases in libc 283cd62a92dSRobert Mustacchiwhere we want to know the file descriptor to perform some operation; 284cd62a92dSRobert Mustacchihowever, non-file backed streams do not have a corresponding file 285cd62a92dSRobert Mustacchidescriptor. When such a stream is detected, we will explicitly return 286cd62a92dSRobert Mustacchi-1. This ensures that a bad file descriptor will be used if someone 287cd62a92dSRobert Mustacchimistakenly calls a system call. Functions like _fileno() call this 288cd62a92dSRobert Mustacchidirectly. 289cd62a92dSRobert Mustacchi 290cd62a92dSRobert Mustacchi------- 291cd62a92dSRobert MustacchiTesting 292cd62a92dSRobert Mustacchi------- 293cd62a92dSRobert Mustacchi 294cd62a92dSRobert MustacchiThere is a burgeoning test suite for stdio in 295cd62a92dSRobert Mustacchiusr/src/test/libc-tests/tests/stdio. If working in stdio (or libc more 296cd62a92dSRobert Mustacchigenerally) it is recommended that you run this test suite and add new 297cd62a92dSRobert Mustacchitests to it where appropriate. For most new functionality it is 298cd62a92dSRobert Mustacchiencouraged that you both import test suites that may already exist and 299cd62a92dSRobert Mustacchithat you also write your own test suites to properly cover a number of 300cd62a92dSRobert Mustacchierror and corner cases. 301cd62a92dSRobert Mustacchi 302cd62a92dSRobert MustacchiTests should also be written against libumem(3LIB), and umem debugging 303cd62a92dSRobert Mustacchishould be explicitly enabled in the program. Enabling umem debugging can 304cd62a92dSRobert Mustacchicatch a number of common memory usage errors. It also makes it easier to 305cd62a92dSRobert Mustacchitest for memory leaks by taking a core file and used the mdb 306cd62a92dSRobert Mustacchi'::findleaks' dcmd. A good starting point is to place the following in 307cd62a92dSRobert Mustacchithe program: 308cd62a92dSRobert Mustacchi 309cd62a92dSRobert Mustacchiconst char * 310cd62a92dSRobert Mustacchi_umem_debug_init(void) 311cd62a92dSRobert Mustacchi{ 312cd62a92dSRobert Mustacchi return ("default,verbose"); 313cd62a92dSRobert Mustacchi} 314cd62a92dSRobert Mustacchi 315cd62a92dSRobert Mustacchiconst char * 316cd62a92dSRobert Mustacchi_umem_logging_init(void) 317cd62a92dSRobert Mustacchi{ 318cd62a92dSRobert Mustacchi return ("fail,contents"); 319cd62a92dSRobert Mustacchi} 320cd62a92dSRobert Mustacchi 321cd62a92dSRobert MustacchiFor the definition of these flags, see umem_debug(3MALLOC). 322cd62a92dSRobert Mustacchi 323cd62a92dSRobert MustacchiIn addition, by leveraging umem debugging it becomes very easy to 324cd62a92dSRobert Mustacchisimulate malloc failure when required. This can be enabled by calling 325cd62a92dSRobert Mustacchiumem_setmtbf(1), which ensures that any subsequent memory requests 326cd62a92dSRobert Mustacchithrough malloc(), including those made indirectly by libc, will fail. To 327cd62a92dSRobert Mustacchirestore the behavior after a test, one can simply call umem_setmtbf(0). 328