@ianlancetaylor in case he has opinions

I'm not opposed to this. I don't think it's very important. For functions like these I don't think it's all that interesting to document precisely how they break. No working program is going to pass them invalid values.

Well NULL is (or could be) a valid value. I'm at the moment reviewing some improvements to some golang bindings for a C library. A particular C library function takes a numeric ID for an entity and returns a string (which the caller must free) if the ID is found, or NULL if it's not found. I'm trying to figure out if the following code is correct:

func (Ctx *Context) DomidToName(id Domid) (name string) {
	cDomName := C.libxl_domid_to_name(Ctx.ctx, C.uint32_t(id))
	defer C.free(unsafe.Pointer(cDomName))

	name = C.GoString(cDomName)
	return
}

If cDomName is NULL, will C.GoString return nil? Or do I have to do the check myself? I haven't been able to find the answer so far.

Defining what will happen if C.GoString is passed NULL seems like a minimum requirement.

Same with C.free really -- in normal C, calling free on NULL is fine; I'd assume it's the same in cgo, but it would be good for that to be documented somewhere.

c.GoString returns a string, so it never returns nil.

At present if you call c.GoString with nil it will return the empty string. I'm fine with documenting that.

C.free is not specially implemented by cgo. It will simply call the C free function. If the C free function on your system ignores NULL pointers (as it should), then C.free will ignore nil pointers.

Awesome, thanks.

@DryHumour No, getting things documented for backwards compatibility is always a good idea, rather than just relying on the implementation never to change. Things end up changing for all kinds of random reasons that people don't even notice. If there's documentation that GoString behaves in a certain way, then people will check to make sure that behavior is maintained; if not, they just might forget that's a possibility, and change the behavior without even realizing it.