[apple/libc.git] / libdarwin / h / stdlib.h

/*
 * Copyright (c) 2018 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

/*!
 * @header
 * Non-standard, Darwin-specific additions to the stdlib(3) family of APIs.
 *
 * The os_malloc() and os_strdup() routines are wrappers to be used for small,
 * fixed-size allocations, the assumption being that such allocation should
 * always succeed absent other critical problems. Thus, if the requested size is
 * is a compile-time constant, the return value is asserted to be non-NULL.
 * Otherwise, for sizes that are not known at compile-time, the implementations
 * loop until the allocation succeeds, assuming the failure to be due to
 * transient resource shortages. The implementation will not loop if the program
 * has not become multi-threaded, under the assertion that there would be no
 * point since no other thread could possibly free up resources for the calling
 * thread to use. Thus, in a single-threaded program, all allocations will
 * be treated like small, fixed-size allocations and be expected to succeed.
 *
 * These wrappers should not be used for large allocations whose bounds cannot
 * be determined at compile-time. For such allocations, malloc(3), calloc(3), et
 * al. (with appropriate error handling) are the appropriate interfaces.
 */
#ifndef __DARWIN_STDLIB_H
#define __DARWIN_STDLIB_H

#include <os/base.h>
#include <os/api.h>
#include <os/assumes.h>
#include <dispatch/private.h>

#include <stdlib.h>
#include <sys/types.h>
#include <sys/cdefs.h>

__BEGIN_DECLS;

/*!
 * @function __os_temporary_resource_shortage
 * A function whose purpose is to appear in stack traces to indicate transient
 * resource shortage conditions. Do not call.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_NOT_TAIL_CALLED
void
__os_temporary_resource_shortage(void);

/*!
 * @functiongroup
 * Internal inline definitions.
 */
DARWIN_API_AVAILABLE_20170407
OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1)
static inline void *
_os_malloc_loop(size_t size)
{
	void *ptr = NULL;
	while (!(ptr = malloc(size))) {
		__os_temporary_resource_shortage();
	}
	return ptr;
}

DARWIN_API_AVAILABLE_20170407
OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1)
static inline void *
_os_malloc_known(size_t size)
{
	return malloc(size);
}

DARWIN_API_AVAILABLE_20170407
OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1, 2)
static inline void *
_os_calloc_loop(size_t cnt, size_t size)
{
	void *ptr = NULL;
	while (!(ptr = calloc(cnt, size))) {
		__os_temporary_resource_shortage();
	}
	return ptr;
}

DARWIN_API_AVAILABLE_20170407
OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1, 2)
static inline void *
_os_calloc_known(size_t cnt, size_t size)
{
	return calloc(cnt, size);
}

DARWIN_API_AVAILABLE_20170407
OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC
static inline char *
_os_strdup_loop(const char *str)
{
	char *ptr = NULL;
	while (!(ptr = strdup(str))) {
		__os_temporary_resource_shortage();
	}
	return ptr;
}

DARWIN_API_AVAILABLE_20170407
OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC
static inline char *
_os_strdup_known(const char *str)
{
	return strdup(str);
}

/*!
 * @function os_malloc
 * Wrapper around malloc(3) which guarantees that the allocation succeeds.
 *
 * @param __size
 * The size of the allocation.
 *
 * @result
 * A new object that the caller is responsible for free(3)ing.
 *
 * This routine will never return NULL. If the size of the allocation is known
 * at compile-time, a failure to allocate the object will abort the caller. If
 * the size is not known at compile-time, the routine will retry until it is
 * successful.
 */
#define os_malloc(__size) ({ \
	void *ptr = NULL; \
	size_t _size = (__size); \
	if (__builtin_constant_p(__size) || !_dispatch_is_multithreaded()) { \
		ptr = _os_malloc_known(_size); \
		os_assert_malloc("known-constant allocation", ptr, _size); \
	} else { \
		ptr = _os_malloc_loop(_size); \
	} \
	(ptr); \
})

/*!
 * @function os_calloc
 * Wrapper around calloc(3) which guarantees that the allocation succeeds.
 *
 * @param __cnt
 * The number of elements to allocate.
 *
 * @param __size
 * The size of each element to allocate.
 *
 * @result
 * A new object that the caller is responsible for free(3)ing.
 *
 * This routine will never return NULL. If the size of the allocation is known
 * at compile-time, a failure to allocate the object will abort the caller. If
 * the size is not known at compile-time, the routine will retry until it is
 * successful.
 */
#define os_calloc(__cnt, __size) ({ \
	void *ptr = NULL; \
	size_t _size = (__size); \
	size_t _cnt = (__size); \
	if ((__builtin_constant_p(__cnt) && __builtin_constant_p(__size)) || \
			 !_dispatch_is_multithreaded()) { \
		ptr = _os_calloc_known(_cnt, _size); \
		os_assert_malloc("known-constant allocation", ptr, _size); \
	} else { \
		ptr = _os_calloc_loop(_cnt, _size); \
	} \
	(ptr); \
})

/*!
 * @function os_strdup
 * A wrapper around strdup(3) which guarantees that the string duplication
 * succeeds.
 *
 * @param __str
 * The string to duplicate.
 *
 * @result
 * A new string that the caller is responsible for free(3)ing.
 *
 * This routine will never return NULL. If the given string is a compile-time
 * constant, a failure to duplicate it will abort the caller. If the string is
 * not a compile-time constant, the routine will retry until it is successful.
 *
 * @discussion
 * strdup(3) is found in the string(3) API family, but this interface is in the
 * stdlib.h header because its semantic changes are solely related to the manner
 * in which memory is allocated.
 */
#define os_strdup(__str) ({ \
	char *ptr = NULL; \
	const char *_str = (__str); \
	if (__builtin_constant_p(__str) || !_dispatch_is_multithreaded()) { \
		ptr = _os_strdup_known(_str); \
		os_assert_malloc("known-constant allocation", ptr, strlen(_str)); \
	} else { \
		ptr = _os_strdup_loop(_str); \
	} \
	(ptr); \
})

/*!
 * @function os_localtime_file
 * A routine to generate a time stamp that is suitable for embedding in a file
 * name.
 *
 * @param buff
 * A pointer to a buffer where the resulting time stamp will be stored.
 *
 * @discussion
 * The resulting time stamp will not include characters which require escaping
 * in shells, such as spaces. The current implementation format is
 *
 * YYYY-MM-DD_HH.MM.SS.us
 *
 * e.g.
 *
 * 2017-04-24_12.45.15.045609
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT
void
os_localtime_file(char buff[32]);

/*!
 * @function os_simple_hash
 * An implementation of a simple non-cryptographic hashing algorithm.
 *
 * @param buff
 * A pointer to the buffer to hash.
 *
 * @param len
 * The length of the buffer.
 *
 * @result
 * The hashed value of the input.
 *
 * @discussion
 * This routine is meant to be used as a simple way to obtain a value that can
 * be used to choose a bucket in a simple hash table. Do not attach security
 * assumptions to the output of this routine. Do not assume thst the computed
 * hash is stable between hosts, OS versions, or boot sessions.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_NONNULL1
uint64_t
os_simple_hash(const void *buff, size_t len);

/*!
 * @function os_simple_hash_string
 * An implementation of a simple non-cryptographic hashing algorithm.
 *
 * @param string
 * A pointer to the null-terminated string to hash.
 *
 * @result
 * The hashed value of the input.
 *
 * @discussion
 * This routine is the moral equivalent of a call to
 *
 * os_simple_hash(buff, strlen(buff));
 *
 * All the same considerations of {@link os_simple_hash} apply.
 */
DARWIN_API_AVAILABLE_20170407
OS_EXPORT OS_NONNULL1
uint64_t
os_simple_hash_string(const char *string);

__END_DECLS;

#endif // __DARWIN_STDLIB_H
Commit	Line	Data
70ad1dc8 A	1	/*
	2	* Copyright (c) 2018 Apple Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. Please obtain a copy of the License at
	10	* http://www.opensource.apple.com/apsl/ and read it before using this
	11	* file.
	12	*
	13	* The Original Code and all software distributed under the License are
	14	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	18	* Please see the License for the specific language governing rights and
	19	* limitations under the License.
	20	*
	21	* @APPLE_LICENSE_HEADER_END@
	22	*/
	23
	24	/*!
	25	* @header
	26	* Non-standard, Darwin-specific additions to the stdlib(3) family of APIs.
	27	*
	28	* The os_malloc() and os_strdup() routines are wrappers to be used for small,
	29	* fixed-size allocations, the assumption being that such allocation should
	30	* always succeed absent other critical problems. Thus, if the requested size is
	31	* is a compile-time constant, the return value is asserted to be non-NULL.
	32	* Otherwise, for sizes that are not known at compile-time, the implementations
	33	* loop until the allocation succeeds, assuming the failure to be due to
	34	* transient resource shortages. The implementation will not loop if the program
	35	* has not become multi-threaded, under the assertion that there would be no
	36	* point since no other thread could possibly free up resources for the calling
	37	* thread to use. Thus, in a single-threaded program, all allocations will
	38	* be treated like small, fixed-size allocations and be expected to succeed.
	39	*
	40	* These wrappers should not be used for large allocations whose bounds cannot
	41	* be determined at compile-time. For such allocations, malloc(3), calloc(3), et
	42	* al. (with appropriate error handling) are the appropriate interfaces.
	43	*/
	44	#ifndef __DARWIN_STDLIB_H
	45	#define __DARWIN_STDLIB_H
	46
	47	#include <os/base.h>
	48	#include <os/api.h>
	49	#include <os/assumes.h>
	50	#include <dispatch/private.h>
	51
	52	#include <stdlib.h>
	53	#include <sys/types.h>
	54	#include <sys/cdefs.h>
	55
	56	__BEGIN_DECLS;
	57
	58	/*!
	59	* @function __os_temporary_resource_shortage
	60	* A function whose purpose is to appear in stack traces to indicate transient
	61	* resource shortage conditions. Do not call.
	62	*/
	63	DARWIN_API_AVAILABLE_20170407
	64	OS_EXPORT OS_NOT_TAIL_CALLED
65	void
66	__os_temporary_resource_shortage(void);
67
68	/*!
69	* @functiongroup
70	* Internal inline definitions.
71	*/
72	DARWIN_API_AVAILABLE_20170407
73	OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1)
74	static inline void *
75	_os_malloc_loop(size_t size)
76	{
77	void *ptr = NULL;
78	while (!(ptr = malloc(size))) {
79	__os_temporary_resource_shortage();
80	}
81	return ptr;
82	}
83
84	DARWIN_API_AVAILABLE_20170407
85	OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1)
86	static inline void *
87	_os_malloc_known(size_t size)
88	{
89	return malloc(size);
90	}
91
92	DARWIN_API_AVAILABLE_20170407
93	OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1, 2)
94	static inline void *
95	_os_calloc_loop(size_t cnt, size_t size)
96	{
97	void *ptr = NULL;
98	while (!(ptr = calloc(cnt, size))) {
99	__os_temporary_resource_shortage();
100	}
101	return ptr;
102	}
103
104	DARWIN_API_AVAILABLE_20170407
105	OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC __alloc_size(1, 2)
106	static inline void *
107	_os_calloc_known(size_t cnt, size_t size)
108	{
109	return calloc(cnt, size);
110	}
111
112	DARWIN_API_AVAILABLE_20170407
113	OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC
114	static inline char *
115	_os_strdup_loop(const char *str)
116	{
117	char *ptr = NULL;
118	while (!(ptr = strdup(str))) {
119	__os_temporary_resource_shortage();
120	}
121	return ptr;
122	}
123
124	DARWIN_API_AVAILABLE_20170407
125	OS_ALWAYS_INLINE OS_WARN_RESULT OS_MALLOC
126	static inline char *
127	_os_strdup_known(const char *str)
128	{
129	return strdup(str);
130	}
131
132	/*!
133	* @function os_malloc
134	* Wrapper around malloc(3) which guarantees that the allocation succeeds.
135	*
136	* @param __size
137	* The size of the allocation.
138	*
139	* @result
140	* A new object that the caller is responsible for free(3)ing.
141	*
142	* This routine will never return NULL. If the size of the allocation is known
143	* at compile-time, a failure to allocate the object will abort the caller. If
144	* the size is not known at compile-time, the routine will retry until it is
145	* successful.
146	*/
147	#define os_malloc(__size) ({ \
148	void *ptr = NULL; \
149	size_t _size = (__size); \
150	if (__builtin_constant_p(__size) \|\| !_dispatch_is_multithreaded()) { \
151	ptr = _os_malloc_known(_size); \
152	os_assert_malloc("known-constant allocation", ptr, _size); \
153	} else { \
154	ptr = _os_malloc_loop(_size); \
155	} \
156	(ptr); \
157	})
158
159	/*!
160	* @function os_calloc
161	* Wrapper around calloc(3) which guarantees that the allocation succeeds.
162	*
163	* @param __cnt
164	* The number of elements to allocate.
165	*
166	* @param __size
167	* The size of each element to allocate.
168	*
169	* @result
170	* A new object that the caller is responsible for free(3)ing.
171	*
172	* This routine will never return NULL. If the size of the allocation is known
173	* at compile-time, a failure to allocate the object will abort the caller. If
174	* the size is not known at compile-time, the routine will retry until it is
175	* successful.
176	*/
177	#define os_calloc(__cnt, __size) ({ \
178	void *ptr = NULL; \
179	size_t _size = (__size); \
180	size_t _cnt = (__size); \
181	if ((__builtin_constant_p(__cnt) && __builtin_constant_p(__size)) \|\| \
182	!_dispatch_is_multithreaded()) { \
183	ptr = _os_calloc_known(_cnt, _size); \
184	os_assert_malloc("known-constant allocation", ptr, _size); \
185	} else { \
186	ptr = _os_calloc_loop(_cnt, _size); \
187	} \
188	(ptr); \
189	})
190
191	/*!
192	* @function os_strdup
193	* A wrapper around strdup(3) which guarantees that the string duplication
194	* succeeds.
195	*
196	* @param __str
197	* The string to duplicate.
198	*
199	* @result
200	* A new string that the caller is responsible for free(3)ing.
201	*
202	* This routine will never return NULL. If the given string is a compile-time
203	* constant, a failure to duplicate it will abort the caller. If the string is
204	* not a compile-time constant, the routine will retry until it is successful.
205	*
206	* @discussion
207	* strdup(3) is found in the string(3) API family, but this interface is in the
208	* stdlib.h header because its semantic changes are solely related to the manner
209	* in which memory is allocated.
210	*/
211	#define os_strdup(__str) ({ \
212	char *ptr = NULL; \
213	const char *_str = (__str); \
214	if (__builtin_constant_p(__str) \|\| !_dispatch_is_multithreaded()) { \
215	ptr = _os_strdup_known(_str); \
216	os_assert_malloc("known-constant allocation", ptr, strlen(_str)); \
217	} else { \
218	ptr = _os_strdup_loop(_str); \
219	} \
220	(ptr); \
221	})
222
223	/*!
224	* @function os_localtime_file
225	* A routine to generate a time stamp that is suitable for embedding in a file
226	* name.
227	*
228	* @param buff
229	* A pointer to a buffer where the resulting time stamp will be stored.
230	*
231	* @discussion
232	* The resulting time stamp will not include characters which require escaping
233	* in shells, such as spaces. The current implementation format is
234	*
235	* YYYY-MM-DD_HH.MM.SS.us
236	*
237	* e.g.
238	*
239	* 2017-04-24_12.45.15.045609
240	*/
241	DARWIN_API_AVAILABLE_20170407
242	OS_EXPORT
243	void
244	os_localtime_file(char buff[32]);
245
246	/*!
247	* @function os_simple_hash
248	* An implementation of a simple non-cryptographic hashing algorithm.
249	*
250	* @param buff
251	* A pointer to the buffer to hash.
252	*
253	* @param len
254	* The length of the buffer.
255	*
256	* @result
257	* The hashed value of the input.
258	*
259	* @discussion
260	* This routine is meant to be used as a simple way to obtain a value that can
261	* be used to choose a bucket in a simple hash table. Do not attach security
262	* assumptions to the output of this routine. Do not assume thst the computed
263	* hash is stable between hosts, OS versions, or boot sessions.
264	*/
265	DARWIN_API_AVAILABLE_20170407
266	OS_EXPORT OS_NONNULL1
267	uint64_t
268	os_simple_hash(const void *buff, size_t len);
269
270	/*!
271	* @function os_simple_hash_string
272	* An implementation of a simple non-cryptographic hashing algorithm.
273	*
274	* @param string
275	* A pointer to the null-terminated string to hash.
276	*
277	* @result
278	* The hashed value of the input.
279	*
280	* @discussion
281	* This routine is the moral equivalent of a call to
282	*
283	* os_simple_hash(buff, strlen(buff));
284	*
285	* All the same considerations of {@link os_simple_hash} apply.
286	*/
287	DARWIN_API_AVAILABLE_20170407
288	OS_EXPORT OS_NONNULL1
289	uint64_t
290	os_simple_hash_string(const char *string);
291
292	__END_DECLS;
293
294	#endif // __DARWIN_STDLIB_H