launch(3)                BSD Library Functions Manual                launch(3)

NAME
     launchd APIs -- interfaces for interacting with a launchd job.

SYNOPSIS
     #include <launch.h>
     #include <servers/bootstrap.h>

     kern_return_t
     bootstrap_check_in(mach_port_t bp, const name_t service_name,
         mach_port_t *sp);

     int
     launch_activate_socket(const char *name, int **fds, size_t *cnt);

DESCRIPTION
     A launchd(8) job may have resources that are held on behalf of it while
     it is not running to facilitate launch-on-demand. These interfaces allow
     for the job to retrieve these resources as part of its initialization.

     Currently supported resource types are XPC listener connections, Mach
     ports, and sockets. Use of XPC with launchd(8) is documented in the
     xpc(3) family of manual pages.

MACH PORTS
     The bootstrap_check_in() routine allows for a launchd(8) job to retrieve
     the receive right to a Mach port that launchd(8) has created on behalf of
     the job.  launchd(8) creates this port and advertises it in the appropri-
     ate Mach bootstrap namespace by parsing the MachServices entry of the
     job's launchd.plist(5).  The first argument to bootstrap_check_in()
     should always be the bootstrap_port() global. The second argument should
     be the name of the service whose port you wish to retrieve, as specified
     as an entry in the job's MachServices dictionary.  The final argument,
     upon successful return, will be the name of the receive right correspond-
     ing to the port that launchd(8) had advertised in the bootstrap names-
     pace.

     If the job closes the receive right to the port with mach_port_mod_refs()
     or exits, the receive right obtained by this routine will be send back to
     launchd(8) rather than being closed. This allows launchd to resume adver-
     tising the same port in the Mach bootstrap namespace and frees clients
     from the need to re-query for the send right to that port when the job
     dies.

SOCKETS
     The launch_activate_socket() routine allows a launchd(8) job to retrieve
     a set of file descriptors corresponding to a socket service that
     launchd(8) has created and advertised on behalf of the job by parsing the
     Sockets entry in the job's launchd.plist(5).  The first argument should
     be the name of the socket entry as specified in the launchd.plist(5).
     The second argument, upon output, will point to an array of integers
     whose count is filled into the third argument upon success. This array
     represents all the sockets that launchd(8) created corresponding to the
     entry in the job's Sockets dictionary. Depending on the properties speci-
     fied, a single Sockets entry may have multiple descriptors created for it
     (one for IPv4 and one for IPv6, for example). This array is allocated on
     the heap, and it is the caller's responsibility to call free(3) to dis-
     pose of the memory when it is no longer needed.

RETURN VALUES
     If launch_activate_socket() succeeds, zero is returned. In the event of
     failure, a non-zero POSIX-compatible error code indicating the nature of
     the error is returned. This error may be decoded with strerror(3).

     If bootstrap_check_in() succeeds, KERN_SUCCESS is returned. In the event
     of failure, a non-zero error code that may be decoded with
     bootstrap_strerror().

ERRORS
     bootstrap_check_in() will fail if:

     [BOOTSTRAP_UNKNOWN_SERVICE]
                        The Mach service name specified does not exist in the
                        caller's launchd.plist(5).

     [BOOTSTRAP_SERVICE_ACTIVE]
                        The specified Mach service has already been checked in
                        by the job.

     launch_activate_socket() will fail if:

     [ENOENT]           The socket name specified does not exist in the
                        caller's launchd.plist(5).

     [ESRCH]            The calling process is not managed by launchd(8).

     [EALREADY]         The specified socket has already been activated.

SEE ALSO
     xpc(3), xpc_connection_create(3), socket(2), launchd(8),
     launchd.plist(5).

Darwin                          31 March, 2014                          Darwin