LSL Wiki : touch

touch_start(integer num_detected)

This event is raised when an agent first touches the object the script is attached to. The number of touching agents is passed to the script in the num_detected parameter. Information on those objects may be gathered via the llDetected* functions.

Event:	Triggered:	Triggered multiple times:
`touch()`	while a user is clicking on the object.	YES
`touch_start()`	when a user starts clicking on the object.	NO
`touch_end()`	when a user stops clicking on the object.	NO

Notes:

"Touch" means "click on", not "collide with"; to deal with collisions, use the collision, collision_start, and collision_end events.
A script containing a touch, touch_start, or touch_end event may be subject to "prim drift" caused by the user dragging the object when they mean to click it. To avoid this, use llSetStatus(STATUS_BLOCK_GRAB, TRUE) to block grabs, or see below.
This kind of drift happens if the script changes state while the mouse button is down and the new state does not have any of the 3 touch event handlers. Adding a handler that does nothing to these states also avoids the problem, while still allowing the user to control-drag the object.
The "NO" in the table above is inaccurate. Your script can get multiple touch_start or touch_end events on a single mouse click. Go figure! This happens with some mice but not others, and is probably mouse driver related.
If you call for a state change in the touch_start event, you can trigger a touch_start event in the new state if your finger is still on the mouse button when the new state is actived. Avoid this by using the touch_end event to trigger the state change.

See also the llSetTouchText and llPassTouches functions.

Q: I see a lot of llDetected*(0), which seems like hacky laziness since even though this is a singular event and so unlikely to coincide, it seems possible for two touch starts to be described in a single event. Does it work that way?
A: Yes, multiple touches can be combined into a single event, but since this is rare you can get away with just checking index 0. When you suspect things get clicked a lot and close together, such as perhaps in competitive games, you should use a for or while loop to step though all the avatar references.
Q: Why you can't touch objects attached to somebody else?
A: As of 1.12 you can
Q: how to code so only the touchable object's owner can touch it?
A: Use a For loop and compare llDetectedKey to llGetOwner
Q: How the owner can script the touchable object to only allow specific people to touch it?
A: Use a For loop and use llDetectedName to compare to a list of names using llListFindList
Q: How to prevent inappropriate invisible touchable objects in PG sims?
A: Use llRequestSimulatorData.

You can also time how long the touch went for with this quick hack:

//By Charlie Rezillo
float time = 0.1;
default
{
    touch_start(integer num_detected)
    {
        llSetTimerEvent(0.1);
    }
    timer()
    {
        time = time + 0.1;
    }
    touch_end(integer num_detected)
    {
        llSetTimerEvent(0.0);
        llInstantMessage(llDetectedKey(0),llDetectedName(0) + " you held down your mouse button for " + (string)time + " seconds.");
        time  = 0.0;
    }
}

This is a very dirty way of doing it! I highly advise using Time calculations instead by noting the current timestamp at the start of the touch and comparing it with the timestamp at the end. - EthariHallstrom

Events

LSL Wiki : touch_start