From 4cc524097b437b80e5785e25cc1e409e9356b93d Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Sat, 28 Aug 2010 11:29:29 +0000 Subject: [PATCH] Clarified the meaning of 0x0 and 0x30 signal handlers --- test/libburner.c | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/test/libburner.c b/test/libburner.c index 4dbf268..4097a74 100644 --- a/test/libburner.c +++ b/test/libburner.c @@ -20,31 +20,37 @@ Before you can do anything, you have to initialize libburn by burn_initialize() and provide some signal and abort handling, e.g. by the builtin handler, by - burn_set_signal_handling() - as it is done in main() at the end of this file. Then you aquire a - drive in an appropriate way conforming to the API. The two main - approaches are shown here in application functions: + burn_set_signal_handling("libburner : ", NULL, 0x0) + as it is done in main() at the end of this file. + Then you aquire a drive in an appropriate way conforming to the API. The twoi + main approaches are shown here in application functions: libburner_aquire_by_adr() demonstrates usage as of cdrecord traditions libburner_aquire_by_driveno() demonstrates a scan-and-choose approach - With that aquired drive you can blank a CD-RW or DVD-RW + + With that aquired drive you can blank a CD-RW or DVD-RW as shown in libburner_blank_disc() or you can format a DVD-RW to profile "Restricted Overwrite" (needed once) or an unused BD to default size with spare blocks libburner_format() - With the aquired drive you can burn to CD, DVD, BD + With the aquired drive you can burn to CD, DVD, BD. See libburner_payload() + + These three functions switch temporarily to a non-fatal signal handler + while they are waiting for the drive to become idle again: + burn_set_signal_handling("libburner : ", NULL, 0x30) + After the waiting loop ended, they check for eventual abort events by + burn_is_aborting(0) + The 0x30 handler will eventually execute + burn_abort() + but not wait for the drive to become idle and not call exit(). + This is needed because the worker threads might block as long as the signal + handler has not returned. The 0x0 handler would wait for them to finish. + Take this into respect when implementing own signal handlers. + When everything is done, main() releases the drive and shuts down libburn: burn_drive_release(); burn_finish() - FreeBSD does not work well with the convenient synchronous signal handler. So - the waiting loops for blanking, formatting, and writing use the asynchronous - mode of the libburn signal handler. It will not shutdown the library and - abort the program, but rather tell the ongoing drive operation to stop as - soon as possible. After the loops and at the end of the program there is a - call to determine whether an abort happened: - burn_is_aborting() - Applications must use 64 bit off_t. E.g. by defining #define _LARGEFILE_SOURCE #define _FILE_OFFSET_BITS 64 @@ -60,7 +66,7 @@ /* This program insists in the own headerfile. */ #include "../libburn/libburn.h" -/* libburn is intended for Linux systems with kernel 2.4 or 2.6 for now */ +/* libburn works on Linux systems with kernel 2.4 or 2.6, FreeBSD, Solaris */ #include #include #include @@ -333,7 +339,7 @@ int libburner_blank_disc(struct burn_drive *drive, int blank_fast) if (burn_is_aborting(0) > 0) return -1; /* Back to synchronous handling */ - burn_set_signal_handling("libburner : ", NULL, 0); + burn_set_signal_handling("libburner : ", NULL, 0x0); printf("Done\n"); return 1; } @@ -401,7 +407,7 @@ int libburner_format(struct burn_drive *drive) } if (burn_is_aborting(0) > 0) return -1; - burn_set_signal_handling("libburner : ", NULL, 0); + burn_set_signal_handling("libburner : ", NULL, 0x0); burn_disc_get_profile(drive_list[0].drive, ¤t_profile, current_profile_name); if (current_profile == 0x14 || current_profile == 0x13) @@ -757,7 +763,7 @@ int main(int argc, char **argv) /* Activate the synchronous signal handler which eventually will try to properly shutdown drive and library on aborting events. */ - burn_set_signal_handling("libburner : ", NULL, 0); + burn_set_signal_handling("libburner : ", NULL, 0x0); /** Note: driveno might change its value in this call */ ret = libburner_aquire_drive(drive_adr, &driveno);