OS API

From ComputerCraft
(Redirected from Os API)
Jump to navigation Jump to search
Error creating thumbnail: Unable to save thumbnail to destination
Functionos.cancelAlarm
Stops a Alarm.

The Alarm event will not be fired when the alarm triggers after calling this function.

You can set a alarm with with os.setAlarm.
Syntax os.cancelAlarm()
Returns nil
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleStarts and stops a alarm.
Starts a Alarm for 5 seconds, then stops it after 3 seconds.
Code
local Id = os.setAlarm(5)
sleep(3)
os.cancelAlarm(Id)


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.cancelTimer
Stops a timer.

The Timer event will not be fired when the timer finishes after calling this function.

You can start a timer with os.startTimer.
Syntax os.cancelTimer()
Returns nil
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleStarts and stops a timer.
Starts a Timer with 5 seconds, then stops it after 3 seconds.
Code
local Id = os.startTimer(5)
sleep(3)
os.cancelTimer(Id)


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.clock
Returns the time since the Computer was booted in seconds.
Syntax os.clock()
Returns number
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet the running Time
Print the time since the Computer is running in seconds.
Code
print("The Computer is running since "..os.clock().." seconds")
Output
The Computer is running since 10 seconds


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.day
Returns the number of Days passed. It starts counting from 1.

There are 3 possible arguments:
ingame: Returns the current day in world time
local: Returns the number of Days passed since 1.1.1970 in your current timezone
utc: Returns the number of Days passed since 1.1.1970 in utc

If no argument given, it will use "ingame".
Syntax os.day()
Returns number day
Part of CC:Tweaked
API OS
Error creating thumbnail: Unable to save thumbnail to destination
ExamplePrint the date
Prints the number of the current day to the term.
Code
print(os.day())
Output
1


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.epoch
Returns the current Unix epoch or the in-game epoch in milliseconds. Valid arguments for source are "utc", "local", and "ingame".
Syntax os.epoch()
Returns number
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet the current Unix epoch in seconds (UTC)
Gets the current Unix epoch, then prints it out while dividing the epoch by 1000, to convert milliseconds to seconds.
Code
local epoch = os.epoch("utc")
print("Current Unix epoch in seconds: " .. epoch / 1000) -- division by thousand to convert milliseconds to seconds
Output Current Unix epoch in seconds: 1533874800


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.getComputerID
Returns a number representing the unique ID of the Computer.
Syntax os.getComputerID()
Returns number id
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet the Computer ID
Retrieves and prints the Computer's ID.
Code
print(os.getComputerID())
Output
Varies depending on the computer.  If it is the first computer placed in the world, it will display 0.


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.getComputerLabel
Returns a string representing the computer's label.
Syntax os.getComputerLabel()
Returns string label
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet the Computer Label
Retrieves and prints the Computer's Label.
Code
print(os.getComputerLabel())
Output
The computer's label, or nil if none has been set.


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.loadAPI
This function is deprecated. Use of this function will pollute the global table, use require instead.
Globally loads a user created program as a table of functions, using the name of the file as the reference to put the table under.
Syntax os.loadAPI()
Returns boolean
Part of CC:Tweaked
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleLoading a user created API
Loads an API from a file called myAPI.lua in the base directory. All functions in the 'myAPI.lua' API will be accessible through the use of myAPI.<function name>
Code
isLoaded = os.loadAPI("/myAPI.lua")
if isLoaded then
  print("myAPI is ready to use!")
end
Output
myAPI is ready to use!


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.pullEvent
Under OS execution, takes argument filter and waits for the current process to be resumed with a vararg list where the first element matches filter. Under sandboxed execution, returns {...} to the application that has resumed the process. Unlike os.pullEventRaw, it will stop the application upon a "terminate" event.
Syntax os.pullEvent()
Returns {...}
Part of CC:Tweaked
API os
See also coroutine.yield
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet mouse_click event
Prints a mouse_click event
Code
local event, e1 = os.pullEvent("mouse_click")
print(event)
print(e1)


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.pullEventRaw
Duplicate of coroutine.yield. Under OS execution, takes argument filter and waits for the current process to be resumed with a vararg list where the first element matches filter. Under sandboxed execution, returns {...} to the application that has resumed the process. Unlike os.pullEvent, it does not stop the application upon a "terminate" event
Syntax os.pullEventRaw()
Returns {...}
Part of CC:Tweaked
API os
See also coroutine.yield
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet mouse_click event
Prints a mouse_click event
Code
local event, e1 = os.pullEventRaw("mouse_click")
print(event)
print(e1)
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet terminate event
Prints a terminate event
Code
local event, e1 = os.pullEventRaw("terminate")
print(event)


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.queueEvent
Queues a Event
Syntax os.queueEvent()
Returns nil
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleQueues a Event
Queues the mouse_click Event.
Code
os.queueEvent("mouse_click",1,1,1)


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.reboot
Reboots the executing machine immediately.
Syntax os.reboot()
Returns nil
Part of CC:Tweaked (source)
API os


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.run
Run a program at the path.
Syntax os.run()
Returns nil
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleLaunch the Shell.
Open the shell.
Code
os.run({},"/rom/programs/shell.lua")


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.setAlarm
Sets an Alarm, which will queue an Alarm Event at the specified time. The returned ID can be used to distinguish the Alarm from others.
Syntax os.setAlarm()
Returns number alarmID
API os


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.setComputerLabel
Sets the computer's label to the passed string or to nothing if nil or an empty string was passed.
Syntax os.setComputerLabel()
Returns nil
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleSet the Computer's Label
Sets the computer's label to the user's input.
Code
os.setComputerLabel(read())
Output
none


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.shutdown
Shuts the executing machine down immediately.
Syntax os.shutdown()
Returns nil
Part of CC:Tweaked (source)
API os


Error creating thumbnail: Unable to save thumbnail to destination
Functionsleep
Pauses execution of the program for time seconds. As it waits for a fixed amount of ticks, time will automatically be rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines or the parallel API, it will only pause execution of the current thread, not the whole program.

Note Note: Because sleep internally uses timers, it is a function that yields. This means that you can use it to prevent "Too long without yielding" errors, however, as the minimum sleep time is 0.05 seconds, it will slow your program down.

Warning Warning: The sleep function internally queues and waits for a timer event, however it does not listen for any other events. This means that any event that occurs while sleeping will be entirely discarded. If you need to receive events while sleeping, consider using timers.
Syntax sleep()
Returns nil
Part of CC:Tweaked (source)
API BIOS globals
Error creating thumbnail: Unable to save thumbnail to destination
ExampleSleep for a few seconds
Prints "Hello", waits 2 seconds, and then prints "world!".
Code
print("Hello")
sleep(2)
print("world!")
Output
Hello
world!
Error creating thumbnail: Unable to save thumbnail to destination
ExampleSleep for the minimum amount of time
Writes 100 random numbers, one every tick.
Code
for i = 1, 100 do -- Run this 100 times
	local x, y = term.getCursorPos() 
	term.setCursorPos(1, y) -- Go back to the start of the line
	term.clearLine()
	write(math.random())
	sleep(0.05)
end


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.startTimer
Starts a Timer.

The Timer event is fired when the timer is finished.

You can stop the timer with os.cancelTimer.
Syntax os.startTimer()
Returns number timerID
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleStarts a Timer
Starts a Timer with 5 seconds.
Code
os.startTimer(5)


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.time
Returns the current real or inagme time. Valid arguments for source are "utc", "local", and "ingame".
Syntax os.time()
Returns number
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet the current Time
Print the current ingame time in a human readable format.
Code
print(textutils.formatTime(os.time()))
Output 7:00 AM


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.unloadAPI
This function is deprecated. Use of this function will pollute the global table, use require instead.
Unloads a API which was loaded by os.loadAPI.
Syntax os.unloadAPI()
Returns nil
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleUnload a API
Unload the "term" API (not recommend)
Code
os.unloadAPI("term")


Error creating thumbnail: Unable to save thumbnail to destination
Functionos.version
Returns a string representing the name and version of CraftOS.
Syntax os.version()
Returns string
Part of CC:Tweaked (source)
API os
Error creating thumbnail: Unable to save thumbnail to destination
ExampleGet CraftOS version
Retrieves and prints the CraftOS version.
Code
print(os.version())
Output
CraftOS 1.8