xpc_abort(3) [mojave man page]

xpc_abort(3)						   BSD Library Functions Manual 					      xpc_abort(3)

NAME

     xpc_abort -- conditions which cause XPC to abort

DESCRIPTION

     The XPC API will aggressively defend itself against perceived misuse. Wherever XPC can definitively detect misuse of its APIs or data corrup-
     tion, it will abort. For example, if the retain count of an object underflows by calling xpc_release(3) on it too many times, XPC will abort
     the process.

     Many frameworks opt to keep the program limping along in such a state (and will perhaps print a warning message to the system log), but
     aborting upon detection provides unmistakable warning that there is a bug present in the application which should be fixed before shipping.

     When XPC aborts a process, it will place information about the condition which triggered the abort in the Application Specific Information
     section of the crash report. The message will be human-readable, prefixed with "XPC API Misuse:", and the crash report will indicate the
     stack trace which caused the abort.

     XPC will also abort if it detects unrecoverable data corruption in its internal state. The messages for these conditions will be prefixd with
     "Bug in libxpc:".	If you come across such a crash, please file a bug and include the generated crash log, system log and steps to reproduce
     (if there are any identifiable steps).

     Currently, the manner in which XPC aborts the process will result in termination due to SIGILL (illegal instruction). The exact signal raised
     may change from release to release (or platform to platform). But on OS X Lion, SIGILL may be used as a hint that the process was terminated
     intentionally.

DEBUGGING

     When debugging in Xcode or at the gdb command prompt, the debugger acts as the exception handler for the process being debugged. As a result,
     if the process is aborted by XPC, no crash report will be generated, and thus it may not be obvious why the program was terminated.

     As mentioned before, SIGILL is an indication that the process was terminated intentionally. If you observe the last frame in the crashing
     stack to be _xpc_api_misuse(), you may use the xpc_debugger_api_misuse_info() API from within the debugger to obtain a human-readable string
     describing why the process was aborted. For example:

	   Program received signal EXC_BAD_INSTRUCTION, Illegal instruction/operand.
	   0x000000010012b25e in _xpc_api_misuse ()
	   (gdb) p (char *)xpc_debugger_api_misuse_info()
	   $1 = 0x7fff5fbff908 "XPC API Misuse: Over-release of object."
	   (gdb)

     This message indicates that xpc_release(3) was called too many times on an object.

     IMPORTANT: The xpc_debugger_api_misuse_info() API can ONLY be called from within a debugger. It is not meant to be called directly from the
     program. Do not call it directly from your code, and do not rely on the address of the result for any reason.

SEE ALSO

     xpc(3), xpc_object(3), xpc_objects(3)

Darwin								   1 July, 2011 							    Darwin

xpcservice.plist(5)					      BSD File Formats Manual					       xpcservice.plist(5)

NAME

     xpcservice.plist -- XPC Service configuration keys and values

DESCRIPTION

     This document describes the keys-value pairs which configure an XPC Service.  An XPC Service is a process which implements the server-side of
     an XPC connection.  The service program is contained inside a Mac OS X bundle.  The bundle contains an Info.plist.  The XPC Service configu-
     ration settings are specified by keys and values defined in a dictionary included within the Info.plist.

OVERVIEW

     An application has a namespace which maps a service name to a running instance of the service program.  The namespace is created dynamically
     and is unique to each application.  The namespace is populated with the set of services embedded in the application bundle and embedded in
     the frameworks used by the application.

     System frameworks may have embedded XPC Services.	Typically, a developer would not connect to this service directly.  Instead, the developer
     would call an API function in the framework and that would contact the service.  However, the name of XPC Service must be in the applica-
     tion's namespace so that the framework code can "see" and connect to the service.

     XPC Services are "launched-on-demand". They are only started when an application creates a connection to the service and sends a message to
     it. The service process can be terminated when it is inactive and has been idle for a a period of time.  The service process can be started
     again upon receipt of a new message or connection request.  XPC Services should be state-less so that they can come and go as needed.

     The results of a connection request to an XPC Service from two different applications depends upon the type of the service.  The service type
     controls the policy used to create a new instance of the service.	For example, a new connection request from two different applications to
     an Application-type service in a framework will result in a new instance of the service being created for each application.  However, if two
     applications request the same User-type service, then only one instance of the service will be created for each user.

     Services embedded in an application bundle will only be visible to the containing application and will be, by definition, Applicaton-type
     services. A subsequent connection request from an application to a service will result in a new connection to an existing service.

CF Bundle Keys
     These top-level Info.plist keys are required to be defined in the Info.plist file:

     CFBundleIdentifier <string>
     This key defines the name of the service; clients use this name to connect to the service.

     CFBundlePackageType "XPC!"
     This key identifies the bundle as being an XPC Service.

     XPCService <dictionary>
     This key defines a dictionary which contains the settings to configure the XPC Service.

XPCService Dictionary Keys
     The XPC Service may be configured by setting these keys in the XPCService dictionary:

     ServiceType <string> (default: Application)
     The type of the XPC Service specifies how the service is instantiated. The values are:

     o	 Application
	 Each application will have a unique instance of this service.

     o	 User
	 There is one instance of the service process created for each user.

     o	 System
	 There is one instance of the service process for the whole system.  System XPC Services are restricted to reside in system frameworks and
	 must be owned by root.

     RunLoopType <string> (default: dispatch_main)
     The RunLoop type specifies which style of runloop will be started once xpc_main has finished initializing. The values are:

     o	 dispatch_main
	 xpc_main will call dispatch_main().

     o	 NSRunLoop
	 xpc_main will call [[NSRunLoop currentRunLoop] run].

     JoinExistingSession <bool> (default: False)
     By default XPC Services are placed into their own unique audit session.  If this key is true, then the service is placed into the session of
     the application requesting a connection to the service.

     EnvironmentVariables <dictionary> (default: none)
     A dictionary containing environment variables (represented as key-value pairs) which are set in the environment of the service process.

SEE ALSO

     plist(5)

Darwin								 February 8, 2011							    Darwin