1 /* 2 * This file is part of ltrace. 3 * Copyright (C) 2011,2012,2013 Petr Machata, Red Hat Inc. 4 * 5 * This program is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU General Public License as 7 * published by the Free Software Foundation; either version 2 of the 8 * License, or (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, but 11 * WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 18 * 02110-1301 USA 19 */ 20 21 #ifndef _CALLBACK_H_ 22 #define _CALLBACK_H_ 23 24 /* Notes on the iteration interface used across ltrace. Typically the 25 * iteration function looks something like this: 26 * 27 * foo *each_foo(foo *start_after, 28 * enum callback_status (*cb)(foo *f, void *data), 29 * void *data); 30 * 31 * The iteration starts after the element designated by START_AFTER, 32 * or at the first element if START_AFTER is NULL. CB is then called 33 * for each element of the collection. DATA is passed verbatim to CB. 34 * If CB returns CBS_STOP, the iteration stops and the current element 35 * is returned. That element can then be passed as START_AFTER to 36 * restart the iteration. NULL is returned when iteration ends. 37 * 38 * CBS_FAIL is not currently handled, and essentially means the same 39 * thing as CBS_STOP. There's no provision for returning error 40 * states. Errors need to be signaled to the caller via DATA, 41 * together with any other data that the callback needs. 42 * 43 * A richer iteration interface looks like this: 44 * 45 * struct each_foo_t { 46 * foo *restart; 47 * int status; 48 * } each_foo(foo *start_after, 49 * enum callback_status (*cb)(foo *f, void *data), 50 * void *data); 51 * 52 * These provide error handling. The two-part structure encodes both 53 * the restart cookie and status. Status of 0 means success, negative 54 * values signify failures. Status of -1 is dedicated to failures in 55 * user callback (such that the callback returns CBS_FAIL). Other 56 * negative values signal failures in the iteration mechanism itself. 57 */ 58 enum callback_status { 59 CBS_STOP, /* The iteration should stop. */ 60 CBS_CONT, /* The iteration should continue. */ 61 CBS_FAIL, /* There was an error. The iteration should stop 62 * and return error. */ 63 }; 64 65 #define CBS_STOP_IF(X) ((X) ? CBS_STOP : CBS_CONT) 66 #define CBS_CONT_IF(X) ((X) ? CBS_CONT : CBS_STOP) 67 68 #endif /* _CALLBACK_H_ */ 69