launchd check-in: Where's the documentation?

[Sidney San Martín]

I can't find any documentation on the launchd checkin process. Using
SampleD, launch.h, and other people's documentation of their
discoveries it's possible to put together a working daemon, but with
no guarantee that you're doing everything right. (Even though launchd
is open source, its APIs need documentation.)

launchd.plist(5) is the first place I even saw the check-in process
mentioned: "The job must check-in to get a copy of the file
descriptors using APIs outlined in launch(3)". launch(3) doesn't exist
(<rdar://problem/7130390>). It seems like the following, at least,
should be documented:

1) What check-in is and when it is necessary
2) The consequences of a job not checking in when launchd expects it
3) What keys in the response dictionary are filled in at runtime
4) How to memory manage launch data returned by check-in functions
(i.e. what needs to be released)
5) Error conditions and how to handle them

What do you think? Has this come up before? Is there some secret store
of documentation I'm missing? Is this API so intuitive that
documentation is redundant?
_______________________________________________
launchd-dev mailing list
launchd-dev@...
http://lists.macosforge.org/mailman/listinfo.cgi/launchd-dev

[Damien Sorresso]

On Aug 10, 2009, at 9:56 AM, Sidney San Martín wrote:
> I can't find any documentation on the launchd checkin process. Using
> SampleD, launch.h, and other people's documentation of their
> discoveries it's possible to put together a working daemon, but with
> no guarantee that you're doing everything right. (Even though launchd
> is open source, its APIs need documentation.)

The SampleD project is fine. Its purpose is to illustrate how to check  
in.

> launchd.plist(5) is the first place I even saw the check-in process
> mentioned: "The job must check-in to get a copy of the file
> descriptors using APIs outlined in launch(3)". launch(3) doesn't exist
> (<rdar://problem/7130390>). It seems like the following, at least,
> should be documented:

It won't be. We're going to deprecate that API. Just use the SampleD  
project. The comments are reliable as documentation of what's going on.

> 1) What check-in is and when it is necessary

If you don't know, you probably don't need it. :) Only use this API if  
your job advertises a socket.

> 2) The consequences of a job not checking in when launchd expects it

The only consequences are that the job won't receive the file  
descriptors for the sockets whose connection caused it to launch on-
demand. But if your job isn't launch-on-demand, you don't need to worry.

> 3) What keys in the response dictionary are filled in at runtime

See SampleD.

> 4) How to memory manage launch data returned by check-in functions
> (i.e. what needs to be released)

See SampleD.

> 5) Error conditions and how to handle them

See SampleD.

> What do you think? Has this come up before? Is there some secret store
> of documentation I'm missing? Is this API so intuitive that
> documentation is redundant?


No. We don't like that API very much and plan on getting rid of it and  
replacing it with something that is intuitive. So you're not really  
missing anything.
--
Damien Sorresso
BSD Engineering
Apple Inc.



_______________________________________________
launchd-dev mailing list
launchd-dev@...
http://lists.macosforge.org/mailman/listinfo.cgi/launchd-dev

[Sidney San Martín]

Thanks for your help on both questions, Damien.

On Mon, Aug 10, 2009 at 2:59 PM, Damien Sorresso<dsorresso@...> wrote:
> No. We don't like that API very much and plan on getting rid of it and
> replacing it with something that is intuitive. So you're not really missing
> anything.
> --
> Damien Sorresso
> BSD Engineering
> Apple Inc.
>
>
_______________________________________________
launchd-dev mailing list
launchd-dev@...
http://lists.macosforge.org/mailman/listinfo.cgi/launchd-dev