blob: a04fc7e38bee01fc8a75397e4fe257c580dbf05e [file] [log] [blame]
/*
* Copyright (C) 2018 The Android Open Source Project
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#pragma once
#include <sys/cdefs.h>
#include <stdbool.h>
#include <stdint.h>
__BEGIN_DECLS
/*
* Error checking for close(2).
*
* Mishandling of file descriptor ownership is a common source of errors that
* can be extremely difficult to diagnose. Mistakes like the following can
* result in seemingly 'impossible' failures showing up on other threads that
* happened to try to open a file descriptor between the buggy code's close and
* fclose:
*
* int print(int fd) {
* int rc;
* char buf[128];
* while ((rc = read(fd, buf, sizeof(buf))) > 0) {
* printf("%.*s", rc);
* }
* close(fd);
* }
*
* int bug() {
* FILE* f = fopen("foo", "r");
* print(fileno(f));
* fclose(f);
* }
*
* To make it easier to find this class of bugs, bionic provides a method to
* require that file descriptors are closed by their owners. File descriptors
* can be associated with tags with which they must be closed. This allows
* objects that conceptually own an fd (FILE*, unique_fd, etc.) to use their
* own address at the tag, to enforce that closure of the fd must come as a
* result of their own destruction (fclose, ~unique_fd, etc.)
*
* By default, a file descriptor's tag is 0, and close(fd) is equivalent to
* closing fd with the tag 0.
*/
/*
* For improved diagnostics, the type of a file descriptors owner can be
* encoded in the most significant byte of the owner tag. Values of 0 and 0xff
* are ignored, which allows for raw pointers to be used as owner tags without
* modification.
*/
enum android_fdsan_owner_type {
/*
* Generic Java or native owners.
*
* Generic Java objects always use 255 as their type, using identityHashCode
* as the value of the tag, leaving bits 33-56 unset. Native pointers are sign
* extended from 48-bits of virtual address space, and so can have the MSB
* set to 255 as well. Use the value of bits 49-56 to distinguish between
* these cases.
*/
ANDROID_FDSAN_OWNER_TYPE_GENERIC_00 = 0,
ANDROID_FDSAN_OWNER_TYPE_GENERIC_FF = 255,
/* FILE* */
ANDROID_FDSAN_OWNER_TYPE_FILE = 1,
/* DIR* */
ANDROID_FDSAN_OWNER_TYPE_DIR = 2,
/* android::base::unique_fd */
ANDROID_FDSAN_OWNER_TYPE_UNIQUE_FD = 3,
/* sqlite-owned file descriptors */
ANDROID_FDSAN_OWNER_TYPE_SQLITE = 4,
/* java.io.FileInputStream */
ANDROID_FDSAN_OWNER_TYPE_FILEINPUTSTREAM = 5,
/* java.io.FileOutputStream */
ANDROID_FDSAN_OWNER_TYPE_FILEOUTPUTSTREAM = 6,
/* java.io.RandomAccessFile */
ANDROID_FDSAN_OWNER_TYPE_RANDOMACCESSFILE = 7,
/* android.os.ParcelFileDescriptor */
ANDROID_FDSAN_OWNER_TYPE_PARCELFILEDESCRIPTOR = 8,
/* ART FdFile */
ANDROID_FDSAN_OWNER_TYPE_ART_FDFILE = 9,
/* java.net.DatagramSocketImpl */
ANDROID_FDSAN_OWNER_TYPE_DATAGRAMSOCKETIMPL = 10,
/* java.net.SocketImpl */
ANDROID_FDSAN_OWNER_TYPE_SOCKETIMPL = 11,
/* libziparchive's ZipArchive */
ANDROID_FDSAN_OWNER_TYPE_ZIPARCHIVE = 12,
/* native_handle_t */
ANDROID_FDSAN_OWNER_TYPE_NATIVE_HANDLE = 13,
/* android::Parcel */
ANDROID_FDSAN_OWNER_TYPE_PARCEL = 14,
};
/*
* Create an owner tag with the specified type and least significant 56 bits of tag.
*/
#if __BIONIC_AVAILABILITY_GUARD(29)
uint64_t android_fdsan_create_owner_tag(enum android_fdsan_owner_type type, uint64_t tag) __INTRODUCED_IN(29) __attribute__((__weak__));
/*
* Exchange a file descriptor's tag.
*
* Logs and aborts if the fd's tag does not match expected_tag.
*/
void android_fdsan_exchange_owner_tag(int fd, uint64_t expected_tag, uint64_t new_tag) __INTRODUCED_IN(29) __attribute__((__weak__));
/*
* Close a file descriptor with a tag, and resets the tag to 0.
*
* Logs and aborts if the tag is incorrect.
*/
int android_fdsan_close_with_tag(int fd, uint64_t tag) __INTRODUCED_IN(29) __attribute__((__weak__));
/*
* Get a file descriptor's current owner tag.
*
* Returns 0 for untagged and invalid file descriptors.
*/
uint64_t android_fdsan_get_owner_tag(int fd) __INTRODUCED_IN(29);
/*
* Get an owner tag's string representation.
*
* The return value points to memory with static lifetime, do not attempt to modify it.
*/
const char* _Nonnull android_fdsan_get_tag_type(uint64_t tag) __INTRODUCED_IN(29);
/*
* Get an owner tag's value, with the type masked off.
*/
uint64_t android_fdsan_get_tag_value(uint64_t tag) __INTRODUCED_IN(29);
#endif /* __BIONIC_AVAILABILITY_GUARD(29) */
enum android_fdsan_error_level {
// No errors.
ANDROID_FDSAN_ERROR_LEVEL_DISABLED,
// Warn once(ish) on error, and then downgrade to ANDROID_FDSAN_ERROR_LEVEL_DISABLED.
ANDROID_FDSAN_ERROR_LEVEL_WARN_ONCE,
// Warn always on error.
ANDROID_FDSAN_ERROR_LEVEL_WARN_ALWAYS,
// Abort on error.
ANDROID_FDSAN_ERROR_LEVEL_FATAL,
};
/*
* Get the error level.
*/
#if __BIONIC_AVAILABILITY_GUARD(29)
enum android_fdsan_error_level android_fdsan_get_error_level() __INTRODUCED_IN(29) __attribute__((__weak__));
/*
* Set the error level and return the previous state.
*
* Error checking is automatically disabled in the child of a fork, to maintain
* compatibility with code that forks, closes all file descriptors, and then
* execs.
*
* In cases such as the zygote, where the child has no intention of calling
* exec, call this function to reenable fdsan checks.
*
* This function is not thread-safe and does not synchronize with checks of the
* value, and so should probably only be called in single-threaded contexts
* (e.g. postfork).
*/
enum android_fdsan_error_level android_fdsan_set_error_level(enum android_fdsan_error_level new_level) __INTRODUCED_IN(29) __attribute__((__weak__));
#endif /* __BIONIC_AVAILABILITY_GUARD(29) */
/*
* Set the error level to the global setting if available, or a default value.
*/
#if __BIONIC_AVAILABILITY_GUARD(30)
enum android_fdsan_error_level android_fdsan_set_error_level_from_property(enum android_fdsan_error_level default_level) __INTRODUCED_IN(30) __attribute__((__weak__));
#endif /* __BIONIC_AVAILABILITY_GUARD(30) */
__END_DECLS